# Sequence API

> Create, populate, and control multichannel outreach sequences — email, LinkedIn, and calls in one campaign object.

- **Category:** Outreach
- **Base URL:** `https://api.reply.io/v3`
- **Official reference:** https://docs.reply.io/api-reference/sequences/list-all-sequences
- **OpenAPI:** https://headless-jason-ai-sdr-7ajjk.ondigitalocean.app/apis/sequences.openapi.yaml
- **HTML version:** https://headless-jason-ai-sdr-7ajjk.ondigitalocean.app/apis/sequences

## What it does

The Sequence API is the outreach engine. A sequence is a multichannel campaign object: an ordered series of steps (automated email, LinkedIn action, call task) with delays, sending schedules, and A/B message variants. The API covers the full lifecycle — create a sequence (from scratch or a template), define its steps and variants, assign sending mailboxes and LinkedIn accounts, add contacts in bulk, start, pause, archive, and read stats per sequence and per step.

## The problem it solves

Sending one email is easy; running outreach is not. Follow-up timing, channel mixing, reply detection (stop-on-reply), bounce handling, A/B testing, and sender rotation are months of infrastructure work. An agent that creates a sequence and adds contacts gets all of that from one API call surface — the machinery is Reply.io's, already running at production scale.

## How an agent starts using it

Create a sequence with `POST /v3/sequences`, add steps with the Sequence Steps endpoints, assign a mailbox with Sequence Email Accounts, add contacts with `POST /v3/sequences/{id}/contacts/bulk-add`-style Sequence Contacts operations, then `POST /v3/sequences/{id}/start`. Requires an API key with `sequences:write` and `sequences:operate` scopes. Reply detection, scheduling, and sending are handled by the platform from there.

## Typical agent tasks

- Create a sequence with email and LinkedIn steps for a new campaign
- Add a batch of qualified contacts to a running sequence
- Pause a sequence when reply rates drop below a threshold
- Read per-step stats and disable the losing A/B variant
- Save a winning sequence as a reusable template

## Inputs

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | Sequence name (create). |
| `steps` | SequenceStep[] | no | Steps with channel, delay, and message variants — managed via the Sequence Steps endpoints. |
| `contactIds` | string[] | no | Contacts to add, via the Sequence Contacts endpoints (bulk add supported). |
| `emailAccountIds` | string[] | no | Sending mailboxes to assign, via the Sequence Email Accounts endpoints. |

## Outputs

| Name | Type | Description |
|------|------|-------------|
| `id` | string | Sequence identifier used by every other sequence endpoint. |
| `status` | string | Lifecycle state (draft, active, paused, archived). |
| `stats` | SequenceStats | Deliveries, opens, clicks, replies, bounces — per sequence and per step. |

## Authentication

API key as Bearer token. Send `Authorization: Bearer <API_KEY>` on every request. Required scopes: `sequences:read`, `sequences:write`, `sequences:operate`. Get an API key in the Reply.io app under **Settings → API Key** (https://docs.reply.io/api-reference/authentication).

## Rate limits

100 requests/minute and 3,000 requests/hour per user (shared across all of the user's API clients). The stats endpoints (/v3/sequences/{id}/stats, /v3/sequences/stats) may throttle earlier. On 429, honor the Retry-After header.

## Example

### Request — `POST /v3/sequences`

```bash
curl -X POST https://api.reply.io/v3/sequences \
  -H "Authorization: Bearer $REPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "SaaS founders - outbound July" }'
```

### Response — `201`

```json
{
  "id": 5417,
  "name": "SaaS founders - outbound July",
  "status": "draft",
  "createdAt": "2026-07-04T09:15:00Z"
}
```

### Error — `403`

```json
{
  "type": "https://docs.reply.io/api-reference/authentication",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key does not have the required scope: sequences:write."
}
```

## Related APIs

- [Contact Data API](https://headless-jason-ai-sdr-7ajjk.ondigitalocean.app/apis/contact-data.md) — The CRM-grade contact and account store — create, import, filter, and organize the people and companies your agent works.
- [Outreach Actions API](https://headless-jason-ai-sdr-7ajjk.ondigitalocean.app/apis/outreach-actions.md) — One-off sends outside a sequence — a single email, LinkedIn connection request, InMail, message, or voice message, on demand.
- [Conversations & Inbox API](https://headless-jason-ai-sdr-7ajjk.ondigitalocean.app/apis/conversations-inbox.md) — The unified inbox as an API — read threads across email and LinkedIn, classify replies with categories, detect meeting intent, and respond.
- [Analytics API](https://headless-jason-ai-sdr-7ajjk.ondigitalocean.app/apis/analytics.md) — Outcome data for optimizing agents — email, LinkedIn, call, and task overviews, activity feeds, team performance, channel efficiency, and the meetings list.
- [Templates & Schedules API](https://docs.reply.io/api-reference/email-templates/create-an-email-template) — Reusable email and sequence templates, variable rendering, sending schedules, and holiday calendars.

## FAQ

**Can one sequence mix email and LinkedIn steps?**

Yes. A sequence is a multichannel object — steps can be automated emails, LinkedIn actions, or call tasks, with per-step delays and A/B variants.

**How does an agent start and stop a sequence?**

POST /v3/sequences/{id}/start and /pause (scope sequences:operate). Bulk start/pause/archive endpoints exist for managing many sequences at once.

**Where do replies to a sequence show up?**

In the unified inbox. Use the Conversations & Inbox API to read threads, or subscribe to the email_replied webhook event to be pushed each reply.