Campaigns

Schedule campaign

Changed on

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

Request

  • Base URL
    https://api.sequenzy.com/api/v1
  • URL
    https://api.sequenzy.com/api/v1/campaigns/{campaignId}/schedule
  • Auth
    HTTP bearer

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

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.

sendTimeWindowHoursinteger

STO delivery window in hours from scheduledAt. Defaults to 12. Only used when sendTimeOptimization is true. Recipients whose predicted hour falls outside the window are snapped to the nearest edge.

spreadOverHoursnumber nullable

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

maxRecipientsinteger nullable

Send to at most this many audience members. The first N matching subscribers (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 draft's saved cap, send null to clear it. The response's estimatedRecipientCount reflects the cap. For A/B tests, the cap must be at least the number of variants plus one; a smaller saved or requested cap returns 400 without changing the campaign or schedule.

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' | 'null' 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"
  },
  "sendTimeWindowHours": 12,
  "spreadOverHours": 6,
  "maxRecipients": 100,
  "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"
  }
}

Changes

  • db3873ca3d4dRevision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • e93563b0d37eRevision changes
    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status