> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorbitcrm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sequences API

> Programmatically manage sequences (email and SMS steps), enroll contacts, and track engagement.

The API lets you build sequences (create them, write their steps and activate or pause them), list and inspect sequences and their steps, enroll and unenroll contacts, view analytics, and manage unsubscribes. Sequences with **SMS** steps require a valid **Send from number** and Salesmsg setup as described in the [Salesmsg integration](https://docs.useorbitcrm.ai/integrations/salesmsg.md) guide.

## Available Endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/api/v1/sequences` | List all sequences |
| `POST` | `/api/v1/sequences` | Create a draft sequence (`sequences:manage`) |
| `GET` | `/api/v1/sequences/:id` | Get sequence details |
| `PATCH` | `/api/v1/sequences/:id` | Change a sequence's name, sender, settings, exit criteria or `folder_id` (a folder from `GET /api/v1/folders?kind=sequence`; `null` unfiles it) (`sequences:manage`) |
| `POST` | `/api/v1/sequences/:id/activate` | Start a sequence, or publish the edits of an active one (`sequences:manage`) |
| `POST` | `/api/v1/sequences/:id/pause` | Pause an active sequence (`sequences:manage`) |
| `GET` | `/api/v1/sequences/:id/steps` | List a sequence's steps |
| `POST` | `/api/v1/sequences/:id/steps` | Append a step (`sequences:manage`) |
| `PUT` | `/api/v1/sequences/:id/steps` | Reorder the steps (`sequences:manage`) |
| `PATCH` | `/api/v1/sequences/:id/steps/:stepId` | Change a step (`sequences:manage`) |
| `DELETE` | `/api/v1/sequences/:id/steps/:stepId` | Delete a step (`sequences:manage`) |
| `GET` | `/api/v1/sequences/:id/analytics` | Get sequence analytics |
| `GET` | `/api/v1/sequences/:id/enrollments` | List enrollments |
| `POST` | `/api/v1/sequences/:id/enrollments` | Enroll a contact |
| `DELETE` | `/api/v1/sequences/:id/enrollments/:enrollmentId` | Unenroll a contact |
| `GET` | `/api/v1/sequences/unsubscribes` | List unsubscribed contacts |
| `POST` | `/api/v1/sequences/unsubscribes` | Add unsubscribes |

> [!NOTE]
>
> **Authentication**
>
> All Sequences API endpoints require a valid API key passed via the `Authorization: Bearer YOUR_API_KEY` header.
> Get your API key from [Settings → API keys](https://app.useorbitcrm.ai/settings/api-keys).

## Building sequences

Building needs the `sequences:manage` scope, a role that can edit, and a plan with sequences. Enrolling contacts stays on `sequences:write`, so a credential that may enroll can't change what a sequence sends. There is no endpoint that deletes a sequence.

**Create** with `POST /api/v1/sequences`: `{ "name", "description", "from_name", "from_email", "settings", "exit_criteria" }`, all optional. The sequence starts as a draft and sends nothing.

**Change** with `PATCH /api/v1/sequences/:id`. `settings` is merged into what is stored (only the keys you pass change, and only keys the editor knows are accepted); `exit_criteria` replaces the list. Status changes only through `/activate` and `/pause`.

**Steps.** `POST /api/v1/sequences/:id/steps` appends a step: `{ "step_type": "email" | "sms" | "task", "delay_days", "config": { ... } }`. `PATCH` on a step merges `config` the same way. `PUT /api/v1/sequences/:id/steps` with `{ "step_ids": [...] }` sets the order; pass every step once. A sequence holds at most 100 steps. Step HTML is sanitized: scripts and event handlers are removed.

| Step type | `config` keys |
| - | - |
| `email` | `subject`, `body_html`, `body_text`, `delay_unit`; `variants` (A/B test: up to two of `{ "key": "B" \| "C", "subject", "body_html" }`, the step itself is A), `winner_variant` (`"A"`, `"B"`, `"C"` or `null`: only the winner goes out), `cc`, `bcc` (address lists added to the sequence's) |
| `sms` | `message`, `delay_unit`, `from_number_id` |
| `task` | `task_kind` (`call`, `linkedin` or `todo`), `title` and `notes` (merge fields work), `priority` (`low`, `normal`, `high`), `due_days` (business days after the step runs, 0 to 30), `delay_unit` |

A task step makes a task for the contact's owner (else the enrollment's sender, else whoever enrolled them), linked to the contact and their open deal, and the enrollment waits until the task is done; completing it from anywhere (the app, `PATCH /api/v1/tasks/:id` with `"status": "done"`, MCP) moves the sequence on, and deleting it skips the step. If the sequence ends first (a reply, an unsubscribe, a booked meeting, removal), the open task moves to Recently deleted.

**Settings** also take `cc` and `bcc`: addresses copied on every email of the sequence (at most 10 each). Copies go out as their own email (the contact doesn't see them; no unsubscribe link). Only the contact is the sequence's recipient: copies are never checked against or added to the unsubscribe list, never end the enrollment by replying, and don't count in opens, clicks or bounces.

**Enrolling** (`POST /api/v1/sequences/:id/enrollments`, `sequences:write`) takes `contact_ids` (up to 100), `sender_email_account_id` and `send_as_sender`. With `send_as_sender: true` the emails go out as that account's person, with their name, their address on your verified sending domain and their signature, and replies reach their Orbit Inbox. Admins may send as anyone; others only as themselves (403 otherwise). Each result carries `reason` when the contact was skipped: `already_enrolled`, `already_completed`, `wait_period`, `unsubscribed`, `no_email`, `automated_address` (a no-reply, notifications or receipts address nobody reads), `meeting_booked`, `not_found`, `sender_unavailable`, and `no_access` for a contact outside your record access (the key's owner's, as in the dashboard). `GET` lists each enrollment's `send_as_sender`, `recipient_time_zone` (the zone its last step was timed in) and `waiting_on_task_id`.

**Time zones.** Each step's send window and business days are read in the contact's time zone when Orbit knows it: the contact's `time_zone` (set it with `PATCH /api/v1/contacts/:id`), else the country of their phone number when that country has one time zone, else a time zone they gave on a form or booking page, else the sequence's `settings.timezone`.

**Daily sending limits.** A workspace can cap how many sequence emails each sending account sends a day (Settings > Sending Domain). An email over the cap is not skipped: it waits for the sender's next day and goes out in the contact's send window.

**Analytics** (`GET /api/v1/sequences/:id/analytics`) adds a `variants` list to every step that tests variants: each one's `sent`, `opened`, `clicked`, `replied`, `bounced`, their rates, and whether it is still `active` or the `winner`.

**Activate** with `POST /api/v1/sequences/:id/activate`. It runs the editor's publish checks: every step has content, merge fields are ones Orbit knows, `from_email` is on one of the workspace's verified sending domains, SMS steps have a connected Salesmsg sender, and the workspace can send. It then sets the sequence active and publishes every step, and the sequence emails and texts the contacts enrolled in it. Call it again to publish later edits to an active sequence; on an active sequence, a step added since the last publish can go out as soon as it is saved.

**Pause** with `POST /api/v1/sequences/:id/pause`: the sequence stops sending until it is activated again.

> [card] [Sequences Guide](https://docs.useorbitcrm.ai/guides/sequences.md)
>
> Learn how sequences work

> [card] [Rate Limits](https://docs.useorbitcrm.ai/developers/api/rate-limits.md)
>
> API rate limit details


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.