Skip to main content
A campaign bundles a schedule, settings, an email sequence (with A/B variants), the sending accounts, its tags, and its leads. The API is task-shaped: you create a fully-configured campaign in one call rather than stitching together six.

Scopes

Lifecycle is deliberately a separate scope from campaigns:write: starting a campaign spends send quota and sender reputation. A key with only campaigns:write can build and edit a campaign but cannot start sending. Creating with launch: true therefore needs both scopes.

Create a campaign

By default a new campaign sends from all connected mailboxes of your workspace (settings.useAllAccounts: true). To send only from specific mailboxes, pass their ids in accounts and set settings.useAllAccounts to false - then accounts must hold at least one id. While useAllAccounts is true, accounts does not limit which mailboxes send.
One call configures everything. The configuration - campaign, schedule, settings, sending accounts, tags, and sequence - is all-or-nothing: if any part fails validation (for example an SMTP account or a tag that isn’t yours, or a step after the first with a delay under 1 hour), nothing is created. accounts and tags must be your workspace’s own. leads are best-effort and summarized in the response. If launch: true is set and the campaign can’t start, the call still returns 201 - the campaign is created as a draft, with launched: false and a launchError explaining why (start it later with POST /v1/campaigns/{id}/start). Because the response is a success, a retry with the same Idempotency-Key replays it instead of creating a second draft.
sendingMinutesStart / sendingMinutesEnd are minutes from midnight in the campaign timezone, in 30-minute steps - 540 = 09:00, 1020 = 17:00, 1440 = midnight, and the start must be before the end. Step delays are counted from the previous step; the first step sends immediately when a lead enters. endDate is optional: the campaign sends until the end of that day in its timezone and then completes, and it can’t be before startDate. On PATCH, "endDate": null removes it.

Campaigns that keep receiving leads

By default a campaign completes once every lead has received every step. Leads added after that are not sent until someone restarts the campaign in the dashboard - the API cannot restart a completed campaign. If leads keep arriving over time - for example an automation that calls POST /v1/campaigns/{id}/leads every day - set "keepActiveWhenNoLeads": true in settings (in the dashboard: Settings → Advanced → Campaign Completion):
The campaign then stays active when it runs out of leads and starts scheduling new leads as soon as they are added - no restart needed. It still completes on its endDate, and you can pause or delete it as usual. Switch it on for an existing campaign with PATCH /v1/campaigns/{id} before its leads run out - it does not reopen a campaign that has already completed. /start needs at least one lead, so add the first leads before starting; an empty campaign cannot be started to wait for them.

Per-day windows (advanced schedule)

Instead of one window for all sendingDays, you can give each day its own windows - the same “Advanced schedule” as in the dashboard. Pass intervals (this implies "mode": "advanced"); day is 1 = Monday … 7 = Sunday and times are minutes from midnight in the campaign timezone. A shifted week - Monday from 09:30, Tuesday from 10:30, and so on:
Rules (a violation is a 400, nothing is changed):
  • up to 50 windows; a day may have several, but they must not overlap;
  • start and end on a 30-minute step, each window at least 30 minutes long;
  • at least one window must be enabled (enabled defaults to true).
intervals replaces all existing windows. "mode": "simple" switches back to sendingDays + sendingMinutesStart/sendingMinutesEnd and keeps the windows for later; "mode": "advanced" alone re-enables the saved ones. Every campaign response reports schedule.mode and schedule.intervals.

A/B variants

A step is either one email (subject + body) or an A/B test: variants, up to 5, lettered A, B, C… in the order you pass them - the same as the sequence editor in the dashboard. Leads are split evenly between the active variants of a step (two → 50% each, three → 33.33%). A variant with "isActive": false is kept but not sent; at least one per step must stay active. A variant without isActive is on - when you send variants back, pass each one’s isActive as the campaign shows it, or a switched-off variant starts sending again.
Pass either variants or subject + body on a step, not both (400). A step read back from GET shows its variant A as subject + body next to variants; when you send the step back, send only its variants. With settings.abTestingOptimization: true, once every active variant of a step has at least 1000 sends, the variant with the best reply rate is kept and the others are switched off - variants[].isActive shows the result.

Settings

settings holds everything on the campaign’s Settings page. Every field is optional; on PATCH only the fields you pass change. A new campaign starts with the defaults below. The text modes follow the dashboard’s rules: sendAsTextOnly and sendFirstAsText exclude each other - turning one on turns the other off, and both true in one request is a 400. A plain-text-only email has no HTML for an open pixel, tracked links or a body unsubscribe link, so turning sendAsTextOnly on turns trackOpens, trackClicks and unsubscribeLinkBody off, and asking for any of them as true while it is on is a 400. To track the follow-ups but keep the first email plain, use sendFirstAsText. Every field may be left out, and null counts as left out (the current value stays) everywhere except schedule.endDate, where null removes the end date. The response returns the created campaign plus a lead-ingest summary:
Response

Subsequences

A campaign can have subsequences: follow-up flows that start when a lead replies, gets a status (e.g. Interested, Out of office), opens, clicks, or finishes the sequence without replying. GET /v1/campaigns/{id} lists them as "subsequences": [{ "id", "name", "status" }] (an empty array when there are none); manage them under /v1/campaigns/{id}/subsequences and /v1/subsequences/{id}. A subsequence is not a campaign in this API: it is not in GET /v1/campaigns, and /v1/campaigns/{id}… answers 404 for its id.

Launch and control sending

Drive the send lifecycle through explicit routes - /start, /pause, or /resume. To end a campaign, pause it (or delete it); completion otherwise happens automatically when the end date passes or every lead has been sent (unless settings.keepActiveWhenNoLeads is on - then only the end date completes it).
You can also launch at creation time by passing "launch": true in the create body (requires campaigns:lifecycle).
A campaign must have at least one lead and a sequence to start. A launch attempt without them is rejected 400 on POST /start; on create-with-launch the campaign is still created and returned as a draft (201, launched: false, with a launchError).
/start, /pause and /resume answer 409 campaign_busy when the campaign is being changed right now - retry after Retry-After - and 409 campaign_state_changed when it changed (for example completed) while the request ran - read it again before retrying.

Send a test email

Before you launch, send yourself a rendered preview of one step variant, from a real mailbox, exactly as a lead would receive it. Take the variantId from sequence[].variants[].id on the campaign (GET /v1/campaigns/{id}, or the create response). A step written with subject + body has one variant, labelled A; an A/B step has one per variant. Replacing the sequence with PATCH rebuilds the steps, so step and variant ids change - read the campaign again before sending a test.
Response
personalization decides where merge variables come from. lead uses a real lead, which you name with leadId. dummy uses no lead data at all: lead tags such as {{first_name}} render empty (only the sender tags resolve) - use lead to check personalization. There is no fallback: asking for lead without a leadId is rejected, so a test can never quietly leak the wrong person’s data into an email.
The content is the campaign’s own: you cannot supply a body here, so this is not a way to send arbitrary mail.A test goes out from a real mailbox and counts toward that mailbox’s daily limit, but not toward your monthly email quota. It is capped at 12 tests per day per workspace (429 beyond that).The recipient must not be blocked in your workspace. A test carries your campaign content, so the same do-not-email rules apply to it as to a real send: it is refused for anyone on your blacklist, by address or by domain. That list is your own instruction not to contact someone, and a test is not an exception to it.
A 400 means something about the request needs changing – the mailbox rejected the recipient, for example – and the message says what. If the send fails on our side instead, you get a 503: the request was fine, it costs you no quota, and retrying shortly is the right move. Distinguishing the two matters if you retry automatically: a 400 is worth giving up on, a 503 is not.

Tags

Every campaign in GET /v1/campaigns carries its tags. The API reads them, lets you filter by them - so “the campaigns for client X” is a single call rather than a full page-through - and puts them on a campaign: pass tag ids in tags on create, or on PATCH to replace the set ("tags": [] removes them all).
Tags are created, renamed, and deleted in the dashboard, not through the API.Campaign tags and mailbox tags are separate sets. Two tags with the same name on the two pages are different tags, and their ids never cross over: a campaign tag id passed to GET /v1/accounts?tags= matches nothing.

Check status

A lightweight poll of live send-state, the schedule window, and headline metrics. isWithinSchedule / nextScheduleOpensAt are computed for any status - a draft or paused campaign reports whether “now” falls inside its window, not whether it is sending. Campaign dates count: before startDate or after the end of the endDate day (campaign timezone) the window is closed, and nextScheduleOpensAt is never past that day (null instead):
Response

Update

PATCH touches only the sections you supply. Supplying accounts, tags, or sequence replaces that section entirely (the sequence is replaced in place - you always end up with exactly the steps and variants you sent; to keep a step’s A/B test, send its variants again). A supplied sequence must have at least one step - an empty array is rejected (400); omit the field to leave the sequence unchanged. From step 2 on, delayDays + delayHours must add up to at least 1 hour (400, nothing is written).
Unlike create, PATCH applies each supplied section independently - it is not a single cross-section transaction, so a later section failing does not roll back an earlier one. Send one section at a time if you need to isolate failures. The sequence of a campaign that is actively sending cannot be changed; pause it first - a PATCH that includes it is rejected (400) before anything is written. accounts and settings.useAllAccounts can be updated live; with useAllAccounts: false the campaign sends only from accounts, which then may not end up empty.