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.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 callsPOST /v1/campaigns/{id}/leads every day - set
"keepActiveWhenNoLeads": true in settings (in the dashboard: Settings →
Advanced → Campaign Completion):
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 allsendingDays, 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:
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 (
enableddefaults totrue).
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.
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).
"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 thevariantId 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.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 inGET /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.