Leads

Add leads

Add 1-100 leads to a campaign. Each is deduplicated by email within the campaign and provider-detected. The response summarizes the outcome and returns the created leads.

Requires one of the following scopes: leads:write, leads:all, all:all.

post/v1/campaigns/{cid}/leads

Request

  • Base URL: https://api.mailbeast.ai
  • URL: https://api.mailbeast.ai/v1/campaigns/{cid}/leads
  • Auth: HTTP bearer

Path parameters

cidstring uuid required
Example:a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60

Headers

Idempotency-Keystring
Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890

Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns 422.

Request body

Example request

{
  "leads": [
    {
      "email": "jane@acme.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "companyName": "Acme Inc",
      "jobTitle": "VP Sales",
      "website": "https://acme.com",
      "linkedinProfile": "https://linkedin.com/in/jane",
      "location": "New York, US",
      "tags": [
        "vip",
        "q4"
      ],
      "customFields": {
        "industry": "SaaS",
        "employees": 120
      },
      "customFieldLabels": {
        "fund_manager": "Fund Manager"
      },
      "customFieldTypes": {
        "logo_url": "image"
      }
    }
  ]
}

Response

Example response

{
  "summary": {
    "submitted": 3,
    "created": 2,
    "duplicates": 1
  },
  "leads": [
    {
      "id": "c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37",
      "email": "jane@acme.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "companyName": "Acme Inc",
      "jobTitle": "VP Sales",
      "website": "https://acme.com",
      "linkedinProfile": "https://www.linkedin.com/in/janedoe",
      "location": "New York, US",
      "tags": [
        "vip",
        "q4"
      ],
      "customFields": {
        "industry": "SaaS"
      },
      "status": "not_contacted",
      "verification": {
        "status": "valid",
        "subStatus": "email_ok"
      },
      "provider": "google",
      "metrics": {
        "sent": 2,
        "opened": 1
      },
      "sequenceProgress": {
        "totalSteps": 3,
        "sentCount": 1,
        "plannedCount": 1
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.