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

# Run campaigns

> Write a sequence of emails, check it, launch it to your lists, then work its leads and its send queue.

A campaign writes to the people on your lists, one step at a time: a first email, a follow-up a few days later, and so on. You write the steps yourself or let AI write them, check how they read, and launch. From then on, the campaign queues each person's messages and sends them from your mailboxes, until you stop them or the steps run out.

Every campaign call is free. Before you start, you need:

* **A people list** whose people have a work email. See [Build lists](https://docs.outbound.dev/guides/build-lists.md) and [Enrich people](https://docs.outbound.dev/guides/enrich-people.md).
* **A connected mailbox** to send from. See [Connect sending accounts](https://docs.outbound.dev/guides/connect-sending-accounts.md).
* **A key** with the campaigns scope that can write.

> [!NOTE]
>
> Every campaign route shares one rate limit of 30 calls a minute and 1,000 a day for the whole organization. That includes the routes for steps, templates, knowledge hubs and writing styles. Building one campaign takes a dozen calls, so pace your scripts. Poll a campaign, its leads or its queue every 10 seconds or slower, and when a call answers `429`, wait the seconds in `Retry-After`.

## Create a campaign

A new campaign is a draft. It writes to the people on up to 10 of your people lists, and sends nothing until you launch it.

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Portugal freight ops", "listIds": ["6a1f0c2b9d4e8a7f3c5b2e20"], "timezone": "Europe/Lisbon", "emailDays": ["Monday", "Tuesday", "Wednesday", "Thursday"]}'
```

```json theme={null}
{ "id": "6a1f0c2b9d4e8a7f3c5b2e30", "status": "initializing" }
```

A campaign's `status` says where it is:

| `status` | Meaning |
| - | - |
| `initializing` | A draft. Nothing is sent until you launch it. |
| `active` | Launched, and sending. |
| `stopped` | Paused. Its queued messages wait until you launch it again. |
| `completed` | Running, with nothing left to send. |

* **It starts with one empty step** for each of its `channels`, `["email"]` when left out. You write them next.
* **It sends from 9:00 to 17:00** in `timezone` (UTC when left out), on `emailDays` (Monday to Friday when left out).
* **Tracking is off** until you turn it on: `openRateTrackingEnabledAt` and `clickTrackingEnabledAt` take the date-time it starts from. With click tracking on, links go through your [tracking domain](#tracking-domain) once you have an active one.
* **People can be left out** with `excludeLists`, `excludeCompanyLists`, `excludeContacted` and `excludeEngagedContacts`. Every field is in [Create a campaign](https://docs.outbound.dev/api-reference/campaigns/create-a-campaign.md). To leave a list out of every campaign at once, use an [exclusion](#exclusions).

### Let AI write the steps

With `"type": "ai-generated"` and a `prompt` that says what you offer and to whom, the steps are written for you, in the background:

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Portugal freight ops, AI", "type": "ai-generated", "listIds": ["6a1f0c2b9d4e8a7f3c5b2e20"], "prompt": "We sell route planning software to freight companies. Write to heads of operations about cutting empty miles."}'
```

Read the campaign with `GET /v1/campaigns/{campaignId}` until its `initializationStatus` is `completed` or `failed`. The steps draw on your default [knowledge hub](#knowledge-hubs) and follow your default [writing style](#writing-styles), unless you name others with `knowledgeHubId` and `writingStyleId`. A manual campaign's `initializationStatus` is `completed` from the start.

`POST /v1/campaigns/{campaignId}/steps/regenerate` writes the topics of a campaign's AI steps again, from its knowledge hub. Messages already queued keep what they say.

### Start from a template

`templateId` copies a saved template's steps into the new campaign. They decide its channels, so send no `channels` with it. See [Templates](#templates).

## Write the steps

### Write the first email

Read the new campaign's steps to find the empty one:

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/steps \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{
  "steps": [
    { "id": "6a1f0c2b9d4e8a7f3c5b2e31", "channel": "email", "type": "manual", "sequenceNumber": 0, "daysBetween": 0, "cc": [] }
  ]
}
```

Write it with a `subject` and a `body`, sent together: the two replace the step's whole message, and one without the other answers `422`. The body is HTML, and the [variables](#template-variables) in it are filled in for each person:

```bash theme={null}
curl -X PATCH https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/steps/6a1f0c2b9d4e8a7f3c5b2e31 \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Your Lisbon fleet", "body": "<p>Hi {Contact First Name},</p><p>Saw {Contact Company} runs trucks out of Lisbon. Worth a short call?</p><p>{Sender Signature}</p>"}'
```

```json theme={null}
{ "id": "6a1f0c2b9d4e8a7f3c5b2e31" }
```

The answer is only the step's id. Read the steps again to see the step as written.

### Add a follow-up

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/steps \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "email", "sequenceNumber": 1, "daysBetween": 3, "subject": "Re: your Lisbon fleet", "body": "<p>Hi {Contact First Name}, is a short call this week worth it?</p><p>{Sender Signature}</p>"}'
```

It answers `201` with the new step, as the steps list shows it.

* **`daysBetween` is the wait:** how many days after the step before this one goes out, 0 to 90. The first step counts from the start. There is no separate wait step.
* **`sequenceNumber` is the step's place**, from 0. Send the number of steps already there to add it at the end. A place another step holds answers `409` `step_position_taken`.
* **Other kinds of step:** `channel` also takes `linkedin_connection`, `linkedin_message`, `linkedin_visit`, `linkedin_like` and `inmail`, which send from a connected LinkedIn seat. A step of `"type": "ai_generated"` writes each person's message itself, and one of `"type": "ai_reply"` drafts a reply from your `topic` that waits for your approval. An `ai_generated` step answers once its topic is written, which can take a minute: allow two minutes.
* **Delete a step** with `DELETE /v1/campaigns/{campaignId}/steps/{stepId}`, which answers `204`.

### Test two versions with an A/B split

An A/B split sends each person down one of two variants, `a` or `b`, so you can see which does better. It is a step with `"channel": "condition"`, `"conditionType": "ab_split"` and `"daysBetween": 0`: a split waits for nothing, and any other `daysBetween` is refused. A split closes the sequence: the steps after it go in its variants.

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/steps \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "condition", "conditionType": "ab_split", "sequenceNumber": 2, "daysBetween": 0, "splitArms": [{"key": "a", "label": "Short", "weight": 50}, {"key": "b", "label": "Question", "weight": 50}]}'
```

```json theme={null}
{
  "id": "6a1f0c2b9d4e8a7f3c5b2e32",
  "channel": "condition",
  "type": "manual",
  "sequenceNumber": 2,
  "daysBetween": 0,
  "cc": [],
  "conditionType": "ab_split",
  "splitArms": [
    { "key": "a", "label": "Short", "weight": 50 },
    { "key": "b", "label": "Question", "weight": 50 }
  ]
}
```

`splitArms` gives each variant a label and the whole percent of people it gets. Left out, each gets 50.

Then write variant `a`: a step whose `parentStepId` is the split and whose `branchKey` is `a`. Its `sequenceNumber` is its place in the variant, so the first one is 0:

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/steps \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "email", "parentStepId": "6a1f0c2b9d4e8a7f3c5b2e32", "branchKey": "a", "sequenceNumber": 0, "daysBetween": 2, "subject": "Empty miles", "body": "<p>{Contact First Name}, one question: how many of your trucks drive back empty?</p><p>{Sender Signature}</p>"}'
```

Copy variant `a` into `b`, then change one thing in `b`:

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/steps/6a1f0c2b9d4e8a7f3c5b2e32/copy-variant \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fromBranchKey": "a", "toBranchKey": "b"}'
```

```json theme={null}
{ "stepId": "6a1f0c2b9d4e8a7f3c5b2e32", "copiedStepCount": 1 }
```

The copies replace the steps `b` had. In `GET /v1/campaigns/{campaignId}/steps` they are the steps whose `parentStepId` is the split and whose `branchKey` is `b`: edit them with `PATCH`. In that list, `sequenceNumber` counts every step in the order it runs, variants included, so a variant's steps carry higher numbers than their place in the variant.

Change the weights at any time, with both variants adding up to 100. People not yet written to follow the new weights:

```bash theme={null}
curl -X PATCH https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/steps/6a1f0c2b9d4e8a7f3c5b2e32 \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"splitArms": [{"key": "a", "label": "Short", "weight": 70}, {"key": "b", "label": "Question", "weight": 30}]}'
```

* **Add conditions before you launch.** Once people move through a branched sequence, its steps can no longer be added, removed or moved: `409` `sequence_structure_locked`. Duplicate the campaign to change its shape.
* **Two other conditions wait for a signal**, then send each person down the steps under `yes` or under `no`, as their `branchKey`: `invite_accepted` waits for a LinkedIn invitation to be accepted, and `clicked_link` for a click in an email, which needs click tracking on. Their `daysBetween` is how long they wait, 1 to 30 days.
* **A/B splits may not be on for your organization yet.** Adding one then answers `422` `ab_split_disabled`.

### Template variables

Variables are written in single braces, with these exact names. Each is filled in for the person a message is written for:

| Variable | Filled in with |
| - | - |
| `{Contact First Name}` | The person's first name |
| `{Contact Last Name}` | The person's last name |
| `{Contact Full Name}` | The person's full name |
| `{Contact Company}` | The person's company |
| `{Contact Job Title}` | The person's job title |
| `{Contact Industry}` | The industry of the person's company |
| `{Sender First Name}` | The first name of the account that sends |
| `{Sender Last Name}` | The last name of the account that sends |
| `{Sender Full Name}` | The full name of the account that sends |
| `{Sender Signature}` | The sending account's `signature` |
| `{CTA Link}` | The link the campaign's `ctaLink` names |

> [!WARNING]
>
> Write the names exactly as they are here. `{First Name}`, for one, is not a variable: it is sent as written, braces and all. Preview each step before you launch, and check that every variable was filled in.

A list's own columns are variables too, by the column's name in single braces, such as `{Fit notes}`. `GET /v1/campaigns/{campaignId}/variables` lists every variable a campaign can use, each with its `token`: the ones above first, then each column with the list it is on. A mailbox's signature is set with `PATCH /v1/accounts/email/{accountId}`: see [Connect sending accounts](https://docs.outbound.dev/guides/connect-sending-accounts.md#set-its-daily-capacity-and-signature).

### Preview a step

A preview writes a step for the first person on the campaign's lists, as they would get it:

```bash theme={null}
curl -X POST https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/steps/6a1f0c2b9d4e8a7f3c5b2e31/preview \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{
  "stepId": "6a1f0c2b9d4e8a7f3c5b2e31",
  "subject": "Your Lisbon fleet",
  "body": "<p>Hi Ana,</p><p>Saw Northwind Freight runs trucks out of Lisbon. Worth a short call?</p><p>Maya Fern<br>Fernway</p>",
  "channel": "email",
  "type": "manual",
  "person": { "id": "6a1f0c2b9d4e8a7f3c5b2e22", "name": "Ana Costa", "jobTitle": "Head of Operations", "companyName": "Northwind Freight" }
}
```

Nothing is saved or sent, and read-only keys may call it. A word still in braces is not a variable, and would go out as written. Writing an AI step can take a minute: allow two minutes. Previews have their own limit too: 20 a minute and 300 a day.

### Send a test email

A test email writes an email step for one person and sends it to any address, such as your own:

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/steps/6a1f0c2b9d4e8a7f3c5b2e31/test-email \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"toEmail": "maya@fernway.co", "personId": "6a1f0c2b9d4e8a7f3c5b2e22"}'
```

```json theme={null}
{ "toEmail": "maya@fernway.co", "fromEmail": "maya@fernway.co", "subject": "Your Lisbon fleet" }
```

* **It is a real email, and it goes at once.** Every call sends one, and uses one of the sending mailbox's emails for the day, its `availableCapacity`. To retry one safely, send an [`Idempotency-Key`](https://docs.outbound.dev/idempotency).
* **`personId`** is who the step is written for: someone on one of the campaign's lists. Left out, the first person of its first list.
* **`fromEmail`** is the mailbox it goes from. Left out, the first active one. A mailbox that is not active and connected answers `422` `email_account_not_available`.
* **A test email carries no unsubscribe link and no tracking.**
* Test emails have their own limit: 10 a minute and 100 a day.

### Check it is ready

Readiness runs the launch checks without launching:

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/readiness \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{ "ready": true, "people": { "total": 42, "withEmail": 30, "withoutEmail": 12, "withLinkedin": 40 } }
```

When `ready` is false, `reason` is the code a launch would answer with, such as `no_active_email_accounts` (connect or resume a mailbox) or `step_body_missing` (a step has no body yet). `people` counts the people on the campaign's lists. An email-only campaign skips those without a work email.

## Launch

```bash theme={null}
curl -X POST https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/launch \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{ "id": "6a1f0c2b9d4e8a7f3c5b2e30", "status": "active" }
```

Launching is the only call that makes a campaign send. It runs the readiness checks first, and refuses with the first that fails, as `422` and its code. Then it answers `202` and enrolls the people on the campaign's lists in the background: each one becomes a lead, and their first message is queued, as `scheduled` for a step you wrote. Follow the enrolling with the [leads](#follow-the-leads) and the [queue](#work-the-send-queue).

* **Campaign email leaves on the half hour,** at :05 and :35 past each hour, so a message can go out up to 30 minutes after its `scheduledAt`. Test emails, direct messages and replies go at once.
* **Launching a running campaign changes nothing.** Launching a paused one starts it again with the messages it had queued. It may first write its older AI messages again, so allow two minutes.

## Pause

```bash theme={null}
curl -X POST https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/pause \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{ "id": "6a1f0c2b9d4e8a7f3c5b2e30", "status": "stopped" }
```

A paused campaign sends nothing, and its queued messages wait. Launch it again to send them. While a launch or a pause of the same campaign is still running, another one answers `409` `campaign_busy`: try again in a few seconds.

## Add people to a running campaign

### Add a list

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/lists \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listId": "6a1f0c2b9d4e8a7f3c5b2e25"}'
```

```json theme={null}
{
  "id": "6a1f0c2b9d4e8a7f3c5b2e30",
  "listIds": ["6a1f0c2b9d4e8a7f3c5b2e20", "6a1f0c2b9d4e8a7f3c5b2e25"],
  "alreadyPresent": false,
  "enrollmentStarted": true
}
```

In a running campaign, the list's people are enrolled in the background (`enrollmentStarted`). In a draft, they are enrolled at launch. A campaign holds up to 10 lists. Changing `listIds` with `PATCH /v1/campaigns/{campaignId}` replaces the lists but enrolls nobody in a running campaign, so add lists this way. Adding lists has its own limit too: 500 a day.

### Add people by id

To enroll a few people without adding them to a list, send their ids, 1 to 60 a call:

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/people \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"personIds": ["6a1f0c2b9d4e8a7f3c5b2e22", "6a1f0c2b9d4e8a7f3c5b2e23"]}'
```

```json theme={null}
{
  "addedCount": 1,
  "activationStarted": true,
  "people": [
    { "personId": "6a1f0c2b9d4e8a7f3c5b2e22", "outcome": "added", "leadId": "6a1f0c2b9d4e8a7f3c5b2e33", "name": "Ana Costa" },
    { "personId": "6a1f0c2b9d4e8a7f3c5b2e23", "outcome": "missing_valid_email", "name": "Rui Matos" }
  ]
}
```

* **Each person comes back with an `outcome`:** `added`, `already_in_campaign`, `missing_valid_email`, `missing_linkedin`, `person_not_found` or `enrollment_failed`. Sending the call again enrolls nobody twice.
* **Nothing is looked up here.** Find missing emails first with [enrichment](https://docs.outbound.dev/guides/enrich-people.md).
* **Only a running campaign takes people this way.** A draft or a paused one answers `409` `campaign_not_active`: add a list to it instead.
* Adding people has its own limit too: 10 a minute and 500 a day.

## Follow the leads

Each person enrolled is a lead:

```bash theme={null}
curl "https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/leads?pageSize=25" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "6a1f0c2b9d4e8a7f3c5b2e33",
      "personId": "6a1f0c2b9d4e8a7f3c5b2e22",
      "name": "Ana Costa",
      "email": "ana.costa@example.com",
      "companyName": "Northwind Freight",
      "status": "active",
      "sentSteps": 1,
      "totalSteps": 3,
      "openCount": 2,
      "clickCount": 0,
      "hasOpened": true,
      "hasClicked": false,
      "hasReplied": false,
      "hasConnected": false,
      "firstSentBy": { "name": "Maya Fern", "email": "maya@fernway.co", "channel": "email" },
      "arms": []
    }
  ],
  "pagination": { "pageSize": 25, "nextCursor": "MjoyNQ", "total": 42 }
}
```

A lead shows where the person is in the sequence (`sentSteps` of `totalSteps`), what they did, the variants they were given and the account that first wrote to them. `search` finds a name or a company. Page through with `cursor`: see [Pagination](https://docs.outbound.dev/pagination.md#campaigns-leads-the-queue-and-conversations).

### Stop and resume a lead

Stopping a lead sends them nothing more from the campaign. Use the lead's `id`, not its `personId`:

```bash theme={null}
curl -X POST https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/leads/6a1f0c2b9d4e8a7f3c5b2e33/stop \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

It answers `204`, and so does stopping a lead that is already stopped. Resuming starts the lead again from where it stopped, and answers with its next message, queued at once:

```bash theme={null}
curl -X POST https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/leads/6a1f0c2b9d4e8a7f3c5b2e33/resume \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{
  "id": "6a1f0c2b9d4e8a7f3c5b2e33",
  "nextSend": { "id": "6a1f0c2b9d4e8a7f3c5b2e34", "status": "scheduled", "channel": "email", "scheduledAt": "2026-11-18T09:12:00.000Z" }
}
```

To stop one person in several campaigns at once, such as when they answer you elsewhere, use their `personId`:

```bash theme={null}
curl https://api.outbound.dev/v1/people/6a1f0c2b9d4e8a7f3c5b2e22/stop-campaigns \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"campaignIds": ["6a1f0c2b9d4e8a7f3c5b2e30"]}'
```

It answers `204`. A person in none of the campaigns answers `404` `person_not_in_campaign`, and nothing is stopped.

## Work the send queue

Every message a campaign writes waits in its queue until it goes out. List the messages in one state with `status`, which is required:

```bash theme={null}
curl "https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/queue?status=scheduled" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "6a1f0c2b9d4e8a7f3c5b2e34",
      "campaignId": "6a1f0c2b9d4e8a7f3c5b2e30",
      "status": "scheduled",
      "channel": "email",
      "type": "manual",
      "subject": "Your Lisbon fleet",
      "body": "<p>Hi Ana,</p><p>Saw Northwind Freight runs trucks out of Lisbon. Worth a short call?</p>",
      "scheduledAt": "2026-11-17T09:12:00.000Z",
      "fromEmail": "maya@fernway.co",
      "cc": [],
      "bcc": [],
      "person": { "id": "6a1f0c2b9d4e8a7f3c5b2e22", "name": "Ana Costa", "email": "ana.costa@example.com" }
    }
  ],
  "pagination": { "pageSize": 25, "total": 1 }
}
```

| `status` | The messages |
| - | - |
| `approval_required` | Written by AI, and waiting for your approval. |
| `scheduled` | Going out at `scheduledAt`. |
| `sent` | Sent. |
| `skipped` | Skipped, so never sent. |
| `stopped` | Declined, or their lead was stopped. |
| `overwritten` | Replaced by an edit. |

### Edit a message

Change a message that is still waiting to go out: its `subject`, its `body`, or when it goes (`scheduledAt`, in UTC).

```bash theme={null}
curl -X PATCH https://api.outbound.dev/v1/sends/6a1f0c2b9d4e8a7f3c5b2e34 \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Your Lisbon fleet, briefly", "scheduledAt": "2026-11-17T10:00:00.000Z"}'
```

```json theme={null}
{
  "id": "6a1f0c2b9d4e8a7f3c5b2e35",
  "replacedSendId": "6a1f0c2b9d4e8a7f3c5b2e34",
  "status": "scheduled",
  "subject": "Your Lisbon fleet, briefly",
  "scheduledAt": "2026-11-17T10:00:00.000Z"
}
```

An edit makes a new message: the answer's `id` is the new one, and the message you edited becomes `overwritten`. Use the new `id` from then on. Editing the old one, or a message that already went out, was skipped or was declined, answers `409` `send_not_editable`.

### Skip a message

```bash theme={null}
curl -X POST https://api.outbound.dev/v1/sends/6a1f0c2b9d4e8a7f3c5b2e35/skip \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{ "id": "6a1f0c2b9d4e8a7f3c5b2e35", "status": "skipped" }
```

The message is not sent, and its person moves on to their next step. Skipping a message that is already skipped changes nothing.

### Approve or decline messages

Messages written by AI can wait for your approval, as `approval_required`. Approve up to 100 at a time, and they become `scheduled`:

```bash theme={null}
curl https://api.outbound.dev/v1/sends/approve \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sendIds": ["6a1f0c2b9d4e8a7f3c5b2e41"]}'
```

```json theme={null}
{ "approved": ["6a1f0c2b9d4e8a7f3c5b2e41"], "ignored": [], "notFound": [] }
```

`POST /v1/sends/decline` takes the same body. Declined messages become `stopped`, and their people's sequences in the campaign end. In both answers, `notFound` holds the ids your organization does not have, and `ignored` the messages that could not change: approving takes only messages waiting for approval, and declining only messages that have not gone out.

## Read the results

```bash theme={null}
curl "https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/stats?since=2026-11-01T00:00:00.000Z" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{ "totalSent": 60, "totalOpened": 21, "totalClicked": 3, "totalReplied": 6 }
```

* **`GET /v1/campaigns/{campaignId}/stats`** counts the messages sent, the people who opened and clicked, and the replies, since `since` (12 months ago when left out). Opens and clicks are counted only while tracking is on.
* **`GET /v1/campaigns`** lists every campaign with the same counts and their rates. Narrow it with `status`, `type` or `search`.
* **`GET /v1/campaigns/{campaignId}/ab-results`** shows each A/B split: its variants and their weights, and how each variant did, in all and since the weights last changed: the people it reached, replies, positive replies, meetings, bounces and unsubscribes. `isSmallSample` is true while there are too few people to tell the variants apart.

## Change a campaign

`PATCH /v1/campaigns/{campaignId}` changes a campaign's settings: its name, start, sending days and time zone, lists and exclusions, tracking, daily limits and `ctaLink`.

```bash theme={null}
curl -X PATCH https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30 \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dailyEmailLimit": 25, "clickTrackingEnabledAt": "2026-11-17T09:00:00.000Z"}'
```

* **It answers the campaign** as `GET /v1/campaigns/{campaignId}` does: its name, type, status, lists and daily limits, and the settings it holds, under the names you set them with: `startDate`, `timezone`, `emailDays`, `isDynamic`, the four exclusions, `addUnsubscribeLink`, `openRateTrackingEnabledAt`, `clickTrackingEnabledAt` and `ctaLink`. A setting with no value is left out.
* **Click tracking stays on** while a step waits for a click: turning it off answers `409` `click_tracking_required_by_condition`.
* **`POST /v1/campaigns/{campaignId}/duplicate`** copies a campaign, with its settings and steps, into a new draft named `Copy of` and the original's name.

## Unsubscribes

* **Every campaign email ends with a one-click unsubscribe link**, unless you create or change the campaign with `"addUnsubscribeLink": false`.
* **A send to someone who unsubscribed is refused.** A message, a reply or a test email to an address that unsubscribed from the mailbox's emails answers `422` `recipient_unsubscribed`, and nothing is sent.
* **Do not resume a lead who unsubscribed.** Resuming restarts a lead whatever stopped it, an unsubscribe included.

## Exclusions

An exclusion leaves one of your lists out of every campaign of your organization: the people on a people list, or the people at the companies on a company list. Use it for your customers, your competitors, or anyone campaigns should not write to.

```bash theme={null}
curl https://api.outbound.dev/v1/exclusions \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listId": "6a1f0c2b9d4e8a7f3c5b2e24"}'
```

```json theme={null}
{
  "id": "6a1f0c2b9d4e8a7f3c5b2e3d",
  "listId": "6a1f0c2b9d4e8a7f3c5b2e24",
  "listName": "Competitors",
  "listType": "company",
  "matchedPeopleCount": 0,
  "matchedCompanyCount": 0,
  "createdAt": "2026-11-17T09:00:00.000Z"
}
```

* **It works when a campaign enrolls people from its lists:** at launch, when you add a list to it, and, in a campaign with `isDynamic`, as people join its lists. People and companies you add to the excluded list later are left out too.
* **A company list covers the people linked to its companies.** A person is left out when the company their record is linked to is on the list. A company name alone does not match.
* **It does not stop anyone already enrolled,** and it does not cover people you add by id with `POST /v1/campaigns/{campaignId}/people`. To stop someone who is already in campaigns, see [Stop and resume a lead](#stop-and-resume-a-lead).
* **`GET /v1/exclusions`** lists your exclusions, oldest first. `matchedPeopleCount` counts the checks that left a person out, so it grows faster than the people left out: a campaign with `isDynamic` checks its lists again every 30 minutes.
* **`DELETE /v1/exclusions/{exclusionId}`** stops excluding the list and answers `204`. The list is kept. The people it left out are enrolled by the next enrollment: a running campaign with `isDynamic` takes them from its lists within 30 minutes.
* **One list, one exclusion.** A list you already exclude answers `409` `list_already_excluded`, and a list kept automatically, such as the list of people who unsubscribed, answers `422` `list_not_excludable`.
* Exclusion calls have their own limit, apart from the campaign routes': 30 a minute and 2,000 a day.

## Tracking domain

With click tracking on, each link in a campaign's emails goes through a link address, where a short redirect page counts the click and sends the person on. A tracking domain makes that address a hostname of your own, such as `go.fernway.co`, so the people you write to see your domain when they hover a link. Your organization has one at a time, and every campaign with click tracking on uses it once it is active.

```bash theme={null}
curl https://api.outbound.dev/v1/tracking-domains \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "go.fernway.co"}'
```

```json theme={null}
{
  "id": "6a1f0c2b9d4e8a7f3c5b2e3c",
  "hostname": "go.fernway.co",
  "status": "pending_dns",
  "dnsTarget": "d1x2y3z4abcdef.cloudfront.net",
  "createdAt": "2026-11-17T09:00:00.000Z"
}
```

Now add one CNAME record at your DNS provider: its name is the hostname, and its value is `dnsTarget`. The domain's `status` says where it is:

| `status` | Meaning |
| - | - |
| `pending_dns` | Waiting for the CNAME record, or for the domain's certificate. |
| `verifying` | The hostname is being set up. |
| `active` | Campaigns send their tracked links through it. |
| `failed` | It did not become active in about a day of checks. Check it again to start over. |

The domain is checked every 5 minutes for about a day. Once the record is found, it usually becomes `active` within half an hour, and it can pass through `pending_dns` and `verifying` more than once on the way.

* **Check it now** with `POST /v1/tracking-domains/{trackingDomainId}/verify` once the record is in place, instead of waiting for the next check. It answers the domain as the check left it.
* **Follow it** with `GET /v1/tracking-domains`, which lists your tracking domain. With `?activeOnly=true` it is listed only while it is active.
* **It takes a subdomain of at least three labels.** `fernway.co` answers `422` `invalid_tracking_hostname`. A hostname another organization holds answers `409` `tracking_hostname_already_claimed`, and a second tracking domain `409` `tracking_domain_limit_reached`.
* **It covers tracked links in campaign emails only.** A campaign with click tracking off sends its links as you wrote them. The open tracking image, the unsubscribe link, test emails and messages you send outside a campaign do not go through it.
* **`DELETE /v1/tracking-domains/{trackingDomainId}`** answers `204`, and new emails send their links through the shared link address again. Links in emails already sent keep working only while the CNAME record stays in place, so keep the record. While the domain is still being switched off the delete answers `409` `tracking_domain_removal_pending`: send it again in a minute or two.
* **Adding a hostname you deleted brings the same domain back,** with the id it had, if it was ever active.
* Tracking domain calls have their own limit, apart from the campaign routes': 30 a minute and 1,000 a day. Adding, checking and deleting one share a tighter one on top: 10 a minute and 200 a day.

## Templates

A template keeps a campaign's steps and schedule (sending days, hours, time zone and lists), to start new campaigns from:

```bash theme={null}
curl https://api.outbound.dev/v1/campaign-templates \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Freight intro", "campaignId": "6a1f0c2b9d4e8a7f3c5b2e30"}'
```

```json theme={null}
{ "id": "6a1f0c2b9d4e8a7f3c5b2e36" }
```

Start a campaign from it with `templateId` on `POST /v1/campaigns`. `GET /v1/campaign-templates` lists up to 100 templates with their steps, and `DELETE /v1/campaign-templates/{templateId}` deletes one. Campaigns made from it keep their steps.

## Knowledge hubs

AI steps write from your knowledge hub: pages about your company, its products, pricing, customers and competitors, built from your websites and notes. Your organization has one hub, its default. Create it once:

```bash theme={null}
curl https://api.outbound.dev/v1/knowledge-hubs \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"websites": [{"url": "https://fernway.co", "includeSubPages": true}], "notes": [{"text": "We win on onboarding speed.", "filename": "Positioning"}]}'
```

It answers `202` with the hub `processing` while its sites are read, which takes minutes. Read it with `GET /v1/knowledge-hubs/{hubId}` until its `status` is `complete`, or `draft` if building failed. Then read its pages with `GET /v1/knowledge-hubs/{hubId}/pages`.

* **Find it again** with `GET /v1/knowledge-hubs`, which lists your hubs, the default first.
* **Add to it** with `PATCH /v1/knowledge-hubs/{hubId}`: new websites and notes are read in the background, and nothing is removed. A second hub answers `409` `knowledge_hub_already_exists`.
* **Pages** are written in Markdown. Add your own with `POST /v1/knowledge-hubs/{hubId}/pages`, change one with `PATCH /v1/knowledge-hubs/{hubId}/pages/{pageId}`, or delete it with `DELETE` on the same path. `POST /v1/knowledge-hubs/{hubId}/pages/{pageId}/regenerate` writes a page again from its sources; a page you wrote yourself has none, and answers `409` `knowledge_page_not_regenerable`.
* **Read a website again** with `POST /v1/knowledge-hubs/{hubId}/refresh`, sending its `url`.
* **The default hub cannot be deleted:** `409` `knowledge_hub_default_undeletable`.

## Writing styles

`GET /v1/writing-styles` lists your organization's writing styles, the default first. An `ai-generated` campaign follows the style its `writingStyleId` names, or your default.

## Delete a campaign

```bash theme={null}
curl -X DELETE https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30 \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

It answers `204`, and nothing more is sent from the campaign. Its people and lists are kept. Deleting it again answers `404` `campaign_not_found`.

## Keys and limits

* **Keys.** Campaign calls need a key with the campaigns scope. Read-only keys can read campaigns, their steps, leads, queue and stats, templates, knowledge hubs, writing styles, exclusions and the tracking domain, and preview steps. Everything else needs a key that can write.
* **Rate limits.** Every campaign route shares one [rate limit](https://docs.outbound.dev/rate-limits.md): 30 calls a minute and 1,000 a day. Some routes have their own on top: adding lists (500 a day), adding people (10 a minute, 500 a day), previews (20 a minute, 300 a day), rewriting AI steps (10 a minute, 100 a day), copying variants (20 a minute, 300 a day) and test emails (10 a minute, 100 a day). Exclusions and the tracking domain do not draw on it: each has its own limit.


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