> ## Documentation Index
> Fetch the complete documentation index at: https://developer.mailbeast.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a campaign
> Create a campaign with its schedule, settings, sequence, sending accounts, 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`.
## OpenAPI
````yaml /openapi.json post /v1/campaigns
openapi: 3.0.0
info:
title: MailBeast Public API
description: >-
Task-shaped REST API for campaigns, leads, deliverability, verification and
lead discovery. Authenticate with an API key (`Authorization: Bearer
mb_live_…`); the workspace is resolved from the key.
version: '1'
contact: {}
servers:
- url: https://api.mailbeast.ai
security: []
tags:
- name: API Keys
description: Create, list and revoke API keys programmatically.
- name: Campaigns
description: Create, configure, launch and monitor email campaigns.
- name: Leads
description: Add, read, update and bulk-manage a campaign’s leads.
- name: Workspace
description: Read usage, subscription and workspace identity.
- name: Email Accounts
description: >-
Connect and manage the sending mailboxes your campaigns send from
(SMTP/IMAP or native OAuth).
- name: Analytics
description: Engagement reporting – per campaign, over time, and across the workspace.
- name: Lead Finder
description: >-
Discover new companies and leads. List past searches and poll a running
search’s progress.
paths:
/v1/campaigns:
post:
tags:
- Campaigns
summary: Create a campaign
description: >-
Create a campaign with its schedule, settings, sequence, sending
accounts, 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`.
operationId: campaigns_create
parameters:
- name: Idempotency-Key
in: header
description: >-
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`.
required: false
schema:
type: string
maxLength: 255
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCampaignApiDto'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCampaignApiResponseDto'
'400':
description: The request body or parameters failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorDto'
example:
error:
type: invalid_request_error
code: validation_failed
message: One or more fields are invalid.
status: 400
requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
details:
- name should not be empty
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorDto'
example:
error:
type: authentication_error
code: unauthenticated
message: Missing or invalid API key.
status: 401
requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
'403':
description: >-
The key lacks a required scope, or the plan does not include API
access.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorDto'
example:
error:
type: authorization_error
code: permission_denied
message: This API key is missing the required scope.
status: 403
requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
'409':
description: >-
The request conflicts with current state - e.g. a request with the
same Idempotency-Key is still being processed, or the operation
partially applied.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorDto'
example:
error:
type: invalid_request_error
code: conflict
message: The request conflicts with an existing resource.
status: 409
requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
'422':
description: >-
The Idempotency-Key was already used with a different request body.
Use a new key for a new operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorDto'
example:
error:
type: invalid_request_error
code: idempotency_key_reused
message: >-
The Idempotency-Key was already used with a different
request body. Use a new key for a new operation.
status: 422
requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
'429':
description: >-
Rate limit exceeded - retry after the interval in the Retry-After
header.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorDto'
example:
error:
type: rate_limit_error
code: rate_limited
message: >-
Too many requests. Retry after the interval in the
Retry-After header.
status: 429
requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
retryAfter: 30
security:
- ApiKey: []
components:
schemas:
CreateCampaignApiDto:
type: object
properties:
name:
type: string
example: Q4 Product Launch Outreach
maxLength: 255
schedule:
$ref: '#/components/schemas/CampaignScheduleApiDto'
settings:
$ref: '#/components/schemas/CampaignSettingsApiDto'
sequence:
minItems: 1
description: >-
Inline email sequence steps, in send order. Omit for no sequence;
when supplied it must have at least one step.
type: array
items:
$ref: '#/components/schemas/CampaignSequenceStepApiDto'
accounts:
description: SMTP account ids to send from.
example:
- 123e4567-e89b-12d3-a456-426614174000
type: array
items:
type: string
leads:
description: >-
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.
example:
- jane@acme.com
type: array
items:
type: string
launch:
type: boolean
example: false
description: >-
Start sending immediately after the campaign is configured. Requires
the `campaigns:lifecycle` scope in addition to `campaigns:write`.
required:
- name
CreateCampaignApiResponseDto:
type: object
properties:
campaign:
$ref: '#/components/schemas/CampaignApiDto'
leads:
description: Present only when `leads` were supplied.
allOf:
- $ref: '#/components/schemas/CampaignLeadsImportSummaryDto'
launched:
type: boolean
example: false
description: >-
Whether the campaign was launched (true only when `launch: true`
succeeded).
launchError:
type: string
example: >-
Campaign is not ready to launch: No leads added. Start it with POST
/v1/campaigns/{id}/start.
description: >-
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.
required:
- campaign
- launched
ApiErrorDto:
type: object
properties:
error:
$ref: '#/components/schemas/ApiErrorBodyDto'
required:
- error
CampaignScheduleApiDto:
type: object
properties:
timezone:
type: string
example: America/New_York
description: IANA timezone. Defaults to UTC.
sendingDays:
example:
- 1
- 2
- 3
- 4
- 5
description: Sending days, 1=Monday … 7=Sunday.
type: array
items:
type: number
sendingMinutesStart:
type: number
example: 540
minimum: 0
maximum: 1439
description: Send-window start as minutes from midnight (540 = 09:00).
sendingMinutesEnd:
type: number
example: 1020
minimum: 0
maximum: 1439
description: Send-window end as minutes from midnight (1020 = 17:00).
dailyLimit:
type: number
example: 50
minimum: 0
maximum: 10000
description: Maximum emails per day for the campaign.
startDate:
type: string
format: date-time
description: >-
ISO-8601 start. Omit to start as soon as the campaign is launched
(defaults to the creation time).
endDate:
type: string
format: date-time
description: ISO-8601 end; omit to run indefinitely.
CampaignSettingsApiDto:
type: object
properties:
trackOpens:
type: boolean
example: true
description: Track email opens.
trackClicks:
type: boolean
example: true
description: Track link clicks.
sendAsTextOnly:
type: boolean
example: false
description: Send plain-text only (no HTML part).
stopOnReply:
type: boolean
example: true
description: Stop follow-ups to a lead once they reply.
CampaignSequenceStepApiDto:
type: object
properties:
subject:
type: string
example: Quick question about {{companyName}}
maxLength: 500
description: >-
Email subject. Personalization tags like {{firstName}} are
supported.
body:
type: string
example: Hi {{firstName}}, …
description: HTML body. Personalization tags like {{firstName}} are supported.
delayDays:
type: number
example: 0
minimum: 0
maximum: 365
description: Days to wait before this step (0 for the first email).
delayHours:
type: number
example: 0
minimum: 0
maximum: 23
description: Additional hours to wait before this step.
required:
- subject
- body
CampaignApiDto:
type: object
properties:
id:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
name:
type: string
example: Q4 Product Launch Outreach
status:
type: string
enum:
- draft
- scheduled
- active
- paused
- stopped
- completed
- failed
example: draft
schedule:
$ref: '#/components/schemas/CampaignScheduleView'
settings:
$ref: '#/components/schemas/CampaignSettingsView'
metrics:
$ref: '#/components/schemas/CampaignMetricsView'
sequence:
description: >-
The email sequence steps - included on the detail view (GET
/v1/campaigns/:id).
type: array
items:
$ref: '#/components/schemas/CampaignSequenceStepView'
accounts:
description: Attached SMTP account ids - included on the detail view.
example:
- 3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93
type: array
items:
type: string
tags:
description: >-
Tags on this campaign - the same ones the list returns, and the same
ids `?tags=` filters by. Create and delete them in the dashboard.
Campaign tags are a separate dictionary from mailbox tags, so the
ids do not cross over.
type: array
items:
$ref: '#/components/schemas/TagApiDto'
createdAt:
type: string
format: date-time
example: '2026-07-11T08:00:00.000Z'
updatedAt:
type: string
format: date-time
example: '2026-07-11T10:30:00.000Z'
required:
- id
- name
- status
- schedule
- settings
- metrics
- tags
- createdAt
- updatedAt
CampaignLeadsImportSummaryDto:
type: object
properties:
submitted:
type: number
example: 100
description: Emails submitted in the request.
created:
type: number
example: 92
description: New leads created.
duplicates:
type: number
example: 6
description: Skipped as duplicates.
invalid:
type: number
example: 2
description: Rejected as invalid/unparseable.
required:
- submitted
- created
- duplicates
- invalid
ApiErrorBodyDto:
type: object
properties:
type:
type: string
example: authorization_error
description: Broad error class.
code:
type: string
example: permission_denied
description: Stable machine-readable code to switch on.
message:
type: string
example: This API key is missing the required scope.
status:
type: number
example: 403
requestId:
type: string
example: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f
description: Correlation id - quote it in support requests.
details:
description: Field-level validation messages (present on validation errors).
example:
- name should not be empty
type: array
items:
type: string
retryAfter:
type: number
description: Seconds to wait before retrying (present on 429 responses).
example: 30
required:
- type
- code
- message
- status
- requestId
CampaignScheduleView:
type: object
properties:
timezone:
type: string
example: America/New_York
sendingDays:
example:
- 1
- 2
- 3
- 4
- 5
type: array
items:
type: number
sendingMinutesStart:
type: number
example: 540
description: Minutes from midnight.
sendingMinutesEnd:
type: number
example: 1020
description: Minutes from midnight.
dailyLimit:
type: number
example: 50
startDate:
type: string
format: date-time
nullable: true
endDate:
type: string
format: date-time
nullable: true
required:
- timezone
- sendingMinutesStart
- sendingMinutesEnd
- dailyLimit
CampaignSettingsView:
type: object
properties:
trackOpens:
type: boolean
example: true
trackClicks:
type: boolean
example: true
sendAsTextOnly:
type: boolean
example: false
stopOnReply:
type: boolean
example: true
required:
- trackOpens
- trackClicks
- sendAsTextOnly
- stopOnReply
CampaignMetricsView:
type: object
properties:
leadsCount:
type: number
example: 150
sent:
type: number
example: 120
description: Emails sent.
opens:
type: number
example: 90
description: Open events.
clicks:
type: number
example: 25
description: Click events.
replies:
type: number
example: 12
description: Replies received.
required:
- leadsCount
- sent
- opens
- clicks
- replies
CampaignSequenceStepView:
type: object
properties:
subject:
type: string
example: Quick question about {{companyName}}
body:
type: string
example: Hi {{firstName}}, …
delayDays:
type: number
example: 0
delayHours:
type: number
example: 0
required:
- subject
- body
- delayDays
- delayHours
TagApiDto:
type: object
properties:
id:
type: string
format: uuid
example: 5c9b1e77-2f4a-4c31-9d8e-1a2b3c4d5e6f
name:
type: string
example: client-acme
color:
type: string
nullable: true
example: '#4F46E5'
description: Hex colour shown in the dashboard.
required:
- id
- name
- color
securitySchemes:
ApiKey:
scheme: bearer
bearerFormat: mb_live_…
type: http
````
## Related topics
- [Campaigns](/campaigns.md)
- [Create an API key](/api-reference/api-keys/create-an-api-key.md)
- [Authentication](/authentication.md)
- [Quickstart](/quickstart.md)
- [Overview](/introduction.md)