Sequences API
This page is written for AI agents. People ask their agent to do the work; see How it fits together.
Sequences and their steps: an ordered list of emails with delays, a repeat-run mode, and one switch that means both "can't start" and "hold what's pending".
| Method & path | What it does |
|---|---|
GET /api/v1/sequences |
Every sequence with its steps, delays and how many people are partway through. |
POST /api/v1/sequences |
Create one. Body: name, description, repeat_mode. New sequences start off, so nobody is started on something half-built. |
GET /api/v1/sequences/:id |
One sequence with its ordered steps and the guards that can act on its sends. |
PATCH /api/v1/sequences/:id |
Update name, description, repeat_mode. |
DELETE /api/v1/sequences/:id |
409 while anyone is partway through — turn it off and cancel their runs first. What it already sent stays in each person's history and the emails' reports. |
POST /api/v1/sequences/:id/toggle |
Body: enabled. Answers with how many scheduled emails are now holding. |
POST /api/v1/sequences/:id/add_step |
Add a step. Requires email_source — see below. |
PATCH /api/v1/sequence_steps/:id |
Change delay_amount, delay_unit or status. |
POST /api/v1/sequence_steps/:id/move |
Body: direction. Renumbers so positions stay 1..n with no gaps. |
POST /api/v1/sequence_steps/:id/replace_email |
Point the step at a different email. Requires email_source. |
DELETE /api/v1/sequence_steps/:id |
Remove it and cancel what's still waiting to go out from it. What it already sent stays: see removing a step. |
Adding a step
POST /api/v1/sequences/3/add_step
{ "email_source": "shared", "email_id": 42, "position": 2,
"delay_amount": 3, "delay_unit": "days" }
email_source is required with no default — scratch, shared or copy. See the email-source contract for what each one means after the fact; it is the difference between a later edit reaching one send and reaching twenty.
position inserts there and shifts everything from that point down, so positions stay 1..n with no gaps. Out of range lands at the end. Omit it and it goes last.
New steps arrive as drafts. A draft step doesn't exist for scheduling — people flow through as if it weren't there — until it's activated with PATCH … { "status": "active" }. Activating it means anyone who hasn't reached that position yet will get it; setting it back to draft takes it out of their plan. A pushed sequence file's step status does the same.
Repeat-run modes
| Mode | What a second run does |
|---|---|
resend_all |
Sends every step again, including emails they've already had. |
once_per_email |
Runs again, but skips emails this person has already received. |
single_run |
Never runs a second time. |
"Already received" is tied to the email record, so a copy of an email counts as a different email — which is one of the consequences of choosing copy over shared.
Off means two things
enabled: false stops the sequence being started and holds everything already scheduled from it. Turning it back on releases the holds. It's one switch because those are one intention.
It behaves the same from every path — the sequence page in the web UI, this toggle, MCP's toggle_sequence, and mimeo push with a changed enabled in a sequence file. Held sends show the reason sequence_off in the queue.
The sequence report
GET /api/v1/reporting/sequences/2?preset=30d
{ "sequence": { "id": 2, "name": "Welcome" },
"range": { "preset": "30d", … },
"stats": {
"runs_started": 120, "runs_finished": 80,
"runs_active": 36, "runs_canceled": 4,
"steps": [
{ "id": 5, "position": 1, "status": "active",
"delay": "immediately",
"email": { "id": 12, "subject": "Welcome aboard" },
"waiting": 0, "sent": 120,
"unique_opens": 66, "unique_clicks": 18,
"open_rate": 55.0, "click_rate": 15.0,
"unsubscribes": 1 },
{ "id": null, "position": null, "status": "removed",
"delay": null,
"email": { "id": 13, "subject": "Where to start" },
"waiting": 0, "sent": 64,
"unique_opens": 30, "unique_clicks": 9,
"open_rate": 46.9, "click_rate": 14.1,
"unsubscribes": 0 } ] } }
The same numbers as the sequence's page under Reporting, worked out fresh on every request. Pass preset (7d, 30d, 90d or all) or from and to dates. steps lists the current steps in order, then one entry with status: "removed" for each email a removed step sent, with id, position and delay set to null. Those sends still count toward the sequence. MCP's report with subject: "sequence" returns the same stats.
See also: Emails API · Sequences, for humans