Skip to main content
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 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.
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.
Send to a single list via the listIds shorthand:
Repeat a campaign monthly to a segment:
Deliver at 8pm in each recipient’s own timezone (8pm New York wall time):

Responses