Sign in
latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-18269154992.5 KB

8fbabe82a04d

Campaigns

Schedule campaign

Schedules a draft or already scheduled campaign for a future send time. Requires a verified sending domain. Campaigns that require safety review are held in waiting_approval and scheduled after a reviewer approves them. A waiting_approval result is a normal 200 outcome and is most common on new accounts and recently registered sending domains; retrying the schedule call does not clear the hold, so branch on campaign.status and poll GET /campaigns/{campaignId} instead. See https://docs.sequenzy.com/concepts/campaigns#safety-review

post/campaigns/{campaignId}/schedule

Path parameters

campaignIdstring required

Campaign ID

Request body

scheduledAtstring date-time required

Future send time.

targetListsobject

Optional targeting object. Omit to reuse saved targeting - or, when none is saved, ALL active subscribers. The object is a union discriminated on type: {"type":"all"}, {"type":"lists","listIds":["list_123"]}, {"type":"segment","segmentId":"seg_123"}, {"type":"filtered","filters":[],"filterJoinOperator":"and"}, {"type":"rules","include":[],"exclude":[]}. Mutually exclusive with listIds.

listIdsstring[]

Shorthand for sending to one or more lists. Equivalent to targetLists {"type":"lists","listIds":["list_123"]}. Mutually exclusive with targetLists.

sendTimeOptimizationboolean

Whether to use send-time optimization.

spreadOverHoursnumber nullable

Spread delivery over this many hours. When set, spread delivery takes precedence over send-time optimization.

sendInRecipientTimezoneboolean

Deliver at scheduledAt's wall-clock time in each recipient's own timezone. Requires scheduledTimezone. Contacts without a stored timezone receive the campaign at scheduledAt itself. Not combinable with recurringInterval or spreadOverHours. Omitting it on a reschedule preserves the campaign's existing setting; send false to turn it off.

scheduledTimezonestring nullable

IANA timezone the scheduledAt wall-clock time refers to, for example America/New_York. Required with sendInRecipientTimezone.

recurringInterval'weekly' | 'monthly' nullable

Repeat the campaign on a cadence starting at scheduledAt. The campaign becomes a recurring template - each run is duplicated and sent automatically, re-evaluating audience membership every time. Omit or send null for a one-shot send; scheduling again without it stops the recurrence.

Example request

{
  "scheduledAt": "2026-06-01T14:00:00Z",
  "targetLists": {
    "type": "all"
  },
  "spreadOverHours": 6,
  "scheduledTimezone": "America/New_York",
  "recurringInterval": "monthly"
}

Response

Campaign scheduled successfully

successboolean required
messagestring

Scheduling result message. If the campaign requires review, it is held in waiting_approval instead of queueing a send job.

scheduledAtstring date-time required
jobIdstring nullable
previewUrlstring uri required

Example response

{
  "success": true,
  "message": "Campaign scheduled for 2026-06-01T14:00:00.000Z",
  "jobId": "mock-job-id",
  "previewUrl": "https://sequenzy.com/dashboard/company/comp_abc123/campaign/camp_abc123?step=review",
  "campaign": {
    "id": "camp_abc123",
    "name": "April Launch",
    "subject": "A quick update",
    "status": "scheduled",
    "scheduledTimezone": "America/New_York"
  }
}