Campaigns
Schedule Campaign
Schedule a campaign send
POST
Schedule Campaign
Schedule a draft or already scheduled campaign for a future send time. The campaign must have a sender profile whose sending domain is verified, an email with a subject and at least one content block, and an audience with at least one include rule.
The response returns
Send to a single list via the
Repeat a campaign monthly to a segment:
Deliver at 8pm in each recipient’s own timezone (8pm New York wall time):
campaign.status, which is either scheduled or
waiting_approval. Campaigns that require safety review are held in
waiting_approval and are scheduled once a reviewer approves them.
waiting_approval is a normal, successful (200) outcome, and it is most
common on new accounts and recently registered sending domains. Nothing is
sent while a campaign is held, and retrying the schedule call will not clear
the hold. Automated integrations should branch on campaign.status and then
poll GET /api/v1/campaigns/{campaignId}
instead of retrying. See Safety review
for what triggers the hold and how it clears.Request
string
required
Campaign ID.
string
required
Future ISO 8601 send time.
object
Optional targeting object, a union discriminated on
type: {"type": "all"}, {"type": "lists", "listIds": ["list_123"]}, {"type": "segment", "segmentId": "seg_123"}, {"type": "filtered", "filters": [...]}, or
{"type": "rules", "include": [...], "exclude": [...]}. Omit this to reuse
saved campaign targeting - or, when none is saved, to send to ALL active
subscribers. Mutually exclusive with listIds.array
Shorthand for sending to one or more lists, equivalent to
{"type": "lists", "listIds": ["list_123"]}. Mutually exclusive with targetLists.boolean
Deliver each recipient at their predicted best open hour within
sendTimeWindowHours of scheduledAt (default 12h, max 24). Campaign-only:
there is no company or sequence STO toggle. Sequences use sendingWindow
instead. spreadOverHours takes precedence and turns STO off;
sendInRecipientTimezone also turns it off.integer
STO delivery window in hours from
scheduledAt (1-24, default 12). Only used
when sendTimeOptimization is true. Recipients whose predicted hour falls
outside the window are snapped to the nearest edge.number
Spread delivery over 1-72 hours. When set, spread delivery takes precedence
over send-time optimization.
integer | null
Send to at most this many audience members (1-10,000,000). The first N
matching subscribers, ordered by subscriber id, receive the campaign after
every audience and suppression rule is applied; recipients already reached
count against the cap when a paused send resumes. Omit to keep the cap saved
on the draft, or send
null to clear it. The returned
campaign.estimatedRecipientCount reflects the cap. Out-of-range values
return 400. For A/B tests, the cap must allow at least one recipient per
variant plus one for the winner; a smaller saved or requested cap returns
400 without changing the campaign or its schedule. To send the next batch,
duplicate the campaign and exclude contacts who already received it with an
“email sent” audience filter.boolean
Deliver at
scheduledAt’s wall-clock time in each recipient’s own timezone -
“send when it’s 8pm for the customer”. Requires scheduledTimezone. Contacts
without a stored subscriber timezone
receive the campaign at scheduledAt itself, and timezones whose local time
has already passed when processing starts receive it immediately. Not
combinable with recurringInterval or spreadOverHours; enabling it turns
off send-time optimization. Omitting it on a reschedule preserves the
campaign’s existing setting; send false to turn it off.string
IANA timezone the
scheduledAt wall-clock time refers to, for example
America/New_York. Required with sendInRecipientTimezone.string
Repeat the campaign
weekly or monthly starting at scheduledAt. The
campaign becomes a recurring template - each run is duplicated and sent
automatically, re-evaluating audience membership every time. Omit for a
one-shot send; scheduling again without it stops the recurrence. Unschedule
the campaign to stop the series and return it to an editable draft.listIds shorthand: