Campaigns

Create a campaign

Create a campaign with its schedule, settings, sequence (with A/B variants), sending accounts, tags, and optionally its leads, in one call. Set launch: true to start it right away, which also needs the campaigns:lifecycle scope. If it cannot launch, the campaign is still created and launchError says why.

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

post/v1/campaigns

Request

Base URL: https://api.mailbeast.ai
URL: https://api.mailbeast.ai/v1/campaigns
Auth: HTTP bearer

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

namestring required

accountsstring[]

SMTP account ids the campaign sends from when settings.useAllAccounts is false. While useAllAccounts is true (the default) the campaign sends from every connected mailbox and this list does not limit it.

tagsstring[]

Campaign tag ids to put on the campaign. Read the ids from tags[] on any campaign; tags themselves are created in the dashboard. Mailbox tag ids are a different dictionary and are rejected.

leadsstring[]

Lead emails to add. The response summarizes how many were added. Up to 1000. A malformed address is NOT a request-level 400 - it is counted in the leads summary’s invalid, so one bad entry never rejects the create.

launchboolean

Start sending immediately after the campaign is configured. Requires the campaigns:lifecycle scope in addition to campaigns:write.

Example request

{
  "name": "Q4 Product Launch Outreach",
  "schedule": {
    "mode": "advanced",
    "intervals": [
      {
        "day": 1,
        "startMinutes": 570,
        "endMinutes": 1050,
        "enabled": true
      }
    ],
    "timezone": "America/New_York",
    "sendingDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "sendingMinutesStart": 540,
    "sendingMinutesEnd": 1020,
    "dailyLimit": 50
  },
  "settings": {
    "trackOpens": true,
    "trackClicks": true,
    "stopOnReply": true,
    "stopOnBounce": true,
    "stopCompanyOnReply": true,
    "skipInvalidEmails": true,
    "skipUnknownEmails": true,
    "emailProviderMatching": true,
    "unsubscribeLinkHeader": true,
    "newLeadsRatio": 80,
    "keepActiveWhenNoLeads": true,
    "hubspotSyncEnabled": true
  },
  "sequence": [
    {
      "subject": "Quick question about {{company_name}}",
      "body": "<p>Hi {{first_name}}, …</p>",
      "variants": [
        {
          "subject": "Quick question about {{company_name}}",
          "body": "<p>Hi {{first_name}}, …</p>",
          "isActive": true
        }
      ]
    }
  ],
  "accounts": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "tags": [
    "5c9b1e77-2f4a-4c31-9d8e-1a2b3c4d5e6f"
  ],
  "leads": [
    "jane@acme.com"
  ]
}

Response

launchedboolean required

Whether the campaign was launched (true only when launch: true succeeded).

launchErrorstring

Present only when launch: true was requested but the campaign could NOT be started. The campaign is still created (as a draft) - fix the issue and start it via the lifecycle endpoint. Absent on success.

Example response

{
  "campaign": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Q4 Product Launch Outreach",
    "status": "draft",
    "schedule": {
      "mode": "simple",
      "intervals": [
        {
          "day": 1,
          "startMinutes": 570,
          "endMinutes": 1050,
          "enabled": true
        }
      ],
      "timezone": "America/New_York",
      "sendingDays": [
        1,
        2,
        3,
        4,
        5
      ],
      "sendingMinutesStart": 540,
      "sendingMinutesEnd": 1020,
      "dailyLimit": 50
    },
    "settings": {
      "trackOpens": true,
      "trackClicks": true,
      "stopOnReply": true,
      "stopOnBounce": true,
      "stopCompanyOnReply": true,
      "skipInvalidEmails": true,
      "skipUnknownEmails": true,
      "emailProviderMatching": true,
      "unsubscribeLinkHeader": true,
      "newLeadsRatio": 80,
      "hubspotSyncEnabled": true
    },
    "metrics": {
      "leadsCount": 150,
      "sent": 120,
      "opens": 90,
      "clicks": 25,
      "replies": 12
    },
    "sequence": [
      {
        "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
        "subject": "Quick question about {{company_name}}",
        "body": "<p>Hi {{first_name}}, …</p>",
        "variants": [
          {
            "id": "b3f1a2c4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
            "label": "A",
            "subject": "Quick question about {{company_name}}",
            "body": "<p>Hi {{first_name}}, …</p>",
            "isActive": true
          }
        ]
      }
    ],
    "accounts": [
      "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93"
    ],
    "tags": [
      {
        "id": "5c9b1e77-2f4a-4c31-9d8e-1a2b3c4d5e6f",
        "name": "client-acme",
        "color": "#4F46E5"
      }
    ],
    "createdAt": "2026-07-11T08:00:00.000Z",
    "updatedAt": "2026-07-11T10:30:00.000Z"
  },
  "leads": {
    "submitted": 100,
    "created": 92,
    "duplicates": 6,
    "invalid": 2
  },
  "launchError": "Campaign is not ready to launch: No leads added. Start it with POST /v1/campaigns/{id}/start."
}

Changes

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