# Sequences API

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.                |
| `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 pull it from everyone's queue.                                                |

## Adding a step

```json
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](/content/docs/api/emails.html#email-source/index.html) 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.

## 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.

See also: [Emails API](/content/docs/api/emails.html) · [Sequences, for humans](/content/docs/usage/sequences.html)