Agent Email API Documentation

Integrate our AI-powered email generation directly into your lead capture systems.

Authentication

All API requests require authentication using an API key. You can generate API keys in your dashboard under Settings → API.

Example:

curl -X POST https://yourdomain.com/api/client/process-lead \
  -H "Content-Type: application/json" \
  -H "x-api-key: agemail_YOUR_API_KEY" \
  -d '{"firstName": "John", "lastName": "Doe", "email": "john@company.com"}'

API Endpoints

POST

/api/client/process-lead

Process a new lead and generate a personalized email based on their company information.

Request Body

{
  "firstName": "John",      // Required: Lead's first name
  "lastName": "Doe",        // Required: Lead's last name
  "email": "john@company.com", // Required: Lead's business email
  "templateId": "uuid"      // Optional: Specific prompt template ID to use
}

Successful Response (200 OK)

{
  "success": true,
  "jobId": "uuid",
  "emailSubject": "Subject line for the generated email",
  "emailBody": "Full body content of the generated email",
  "emailDraft": "Full email content (legacy field)",
  "message": "Lead processed successfully"
}

Non-Business Email Response (200 OK)

{
  "error": "Not a business email domain",
  "businessEmail": false
}

Error Response (4xx/5xx)

{
  "error": "Error message",
  "success": false,
  "status": "error",
  "message": "Detailed error message"
}

GET

/api/client/jobs

Retrieve a list of jobs for your account with pagination and filtering options.

Query Parameters

limit    // Optional: Number of results per page (default: 10)
page     // Optional: Page number (default: 1)
status   // Optional: Filter by job status (pending, processing, completed, failed, etc.)

Successful Response (200 OK)

{
  "jobs": [
    {
      "id": "uuid",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@company.com",
      "domain": "company.com",
      "status": "completed",
      "created_at": "2025-01-01T12:00:00Z",
      "updated_at": "2025-01-01T12:05:00Z",
      "completed_at": "2025-01-01T12:05:00Z",
      "error_message": null
    },
    // More jobs...
  ],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 10,
    "pages": 10
  }
}

Job Status Values

Jobs progress through various statuses as they are processed:

pending

Job has been created but not yet processed

scraping

System is extracting information from the company website

generating

AI is creating a personalized email based on the scraped data

sending

Email is being sent (demo flow only)

completed

Job has been successfully processed

failed

Job processing encountered an error

rejected

Job was rejected (e.g., not a business email)

Integration Guide

1. Generate an API Key

Log in to your Agent Email dashboard and navigate to Settings → API to generate a new API key. Store this key securely as it will only be displayed once.

2. Create Custom Prompt Templates

Navigate to Projects in your dashboard to create custom email templates with variables like {{companyName}}, {{productDescription}}, etc. These will be used when generating personalized emails.

3. Integrate with Your Lead Forms

When a lead submits your form, send their information to our API. Here's an example using JavaScript:

// Example JavaScript integration
async function processLead(firstName, lastName, email) {
  try {
    const response = await fetch('https://yourdomain.com/api/client/process-lead', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
      },
      body: JSON.stringify({
        firstName,
        lastName,
        email,
        // Optional: specify a template ID
        templateId: 'your-template-id'
      })
    });
    
    const data = await response.json();
    
    if (data.success) {
      // Email was successfully generated
      console.log('Email Subject:', data.emailSubject);
      console.log('Email Body:', data.emailBody);
      
      // Use the generated email in your system
      // e.g., send it through your email provider
    } else if (data.businessEmail === false) {
      // Not a business email
      console.log('Not a business email domain');
    } else {
      // Other error
      console.error('Error:', data.message);
    }
  } catch (error) {
    console.error('API request failed:', error);
  }
}

4. Monitor Your Jobs

Use the jobs endpoint to monitor the status of your lead processing jobs and track performance.

Rate Limits

API rate limits vary by plan. Please refer to your account dashboard for your current limits. If you exceed your rate limits, the API will return a 429 Too Many Requests response.

Support

If you need help with the API or have any questions, please contact our support team atsupport@agentemail.com.