> For an agent: the map of this documentation is at https://escouade.io/en/mail/docs/llms.txt; every page exists in Markdown, at the same address with `.md` appended.

# Campaigns

> A campaign sends a sequence of messages to an audience, from one of your inboxes. Your agent prepares it, reviews it with the preview, then starts it: the sends leave within the space's sending window, at the pace of the inbox's quotas.

## What a campaign is

- **A sending inbox** (its main address or one of its aliases) and, if you wish, a reply-to address.
- **An audience**: the list of contacts that will receive the campaign (see [Contacts and audiences](https://escouade.io/en/mail/docs/contacts.md)).
- **A sequence of 1 to 4 steps**: the first message, then up to three follow-ups, each a number of days after the previous one.
- **1 to 3 variants per step**: with two variants or more, it is an A/B test. Each contact receives a single variant, assigned at random, and performance compares them. The test is set step by step.

Fields such as `{{prenom}}` and `{{societe}}` come from the audience's contacts. An empty field for a contact blocks their send: the preview points it out before the start. Only `{{unsubscribe_url}}` is filled in at departure, with the one-click unsubscribe link.

## The path

1. `save_campaign` saves a campaign draft. As long as it has not started, it can be corrected as many times as needed.
2. `preview_campaign` reviews the campaign without sending anything: recipients, blocks, duplicates, missing fields of each variant, and a personalised preview of each step. It returns a `revision`.
3. `campaign_action` with `action` = `start`, `confirm` = `true` and that `revision` starts the campaign. If the campaign or its audience has changed since the preview, the start is refused (`campaign_changed`): review again, then start again.
4. After that, `pause` holds the queued sends, `resume` picks them up again, `stop` cancels those that have not already left. `archive`, `restore` and `duplicate` file away or copy a campaign.

A reply from a contact stops their follow-ups, and those of the other identified contacts from the same company. The space's rules apply to every send: sending window, the inbox's daily quota, spacing, block list (see [Sending rules](https://escouade.io/en/mail/docs/regles-envoi.md)).

## Templates

A template keeps a subject, a text and an optional HTML, reusable from one campaign to the next: `list_campaign_templates` lists them, `save_campaign_template` creates or updates one. In the app, a template is applied to a variant in one gesture.

## Performance and history

`campaign_metrics` gives sends, confirmed deliveries, bounces, replies, errors and pending sends, by step and by variant. An accepted SMTP hand-off is not counted as a delivery. `campaign_history` lists the sends of a campaign taken over from another tool (Prescriptio): its opens and clicks stay apart, and imported history never starts again.

## Going back to the previous version

When someone changes the steps of a campaign draft or the content of a template, the replaced version is kept, with its author and its time: `get_campaign` and `list_campaign_templates` return it in `previous`. The app then offers “Revenir” (go back); saving `previous.steps` (or the template's content) restores it, and the current version becomes the previous one in turn. See [The activity log](https://escouade.io/en/mail/docs/main-courante.md).

## The tools

### `list_campaigns`

The space's campaigns, native or taken over from Prescriptio. Access: `read`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `offset` | integer | no | The rank of the first item returned, from 0 to 100,000: the `next_offset` value from the previous call. |
| `archived` | boolean | no | Show archives. |

[Full reference](https://escouade.io/en/mail/docs/reference/list_campaigns.md)

### `get_campaign`

Content, audience, steps, state, performance and first page of history of a campaign this key can reach. Access: `read`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `campaign_id` | `cmp_…` identifier | yes | Campaign. |
| `offset` | integer | no | The rank of the first item returned, from 0 to 100,000: the `next_offset` value from the previous call. |

[Full reference](https://escouade.io/en/mail/docs/reference/get_campaign.md)

### `save_campaign`

Creates or updates a draft: one inbox, one audience and a sequence of 1 to 4 steps, with 1 to 3 variants per step. Access: `send`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `campaign_id` | `cmp_…` identifier | no | Draft to update, optional. |
| `name` | text | yes | Name. |
| `inbox_id` | `inb_…` identifier | yes | Sending inbox. |
| `from_address` | text | no | This inbox's main address or an alias. |
| `audience_id` | `aud_…` identifier | no | Audience. |
| `reply_to` | text | no | Optional reply-to address. |
| `steps` | list | yes | The steps, 1 to 4: `delay_days` (0 to 90 days after the previous step) and 1 to 3 variants, each with `subject`, `text` and optional `html`. |

[Full reference](https://escouade.io/en/mail/docs/reference/save_campaign.md)

### `preview_campaign`

Checks the recipients, the blocks, the duplicates and every field of each variant. Access: `read`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `campaign_id` | `cmp_…` identifier | yes | Campaign. |
| `offset` | integer | no | The rank of the first item returned, from 0 to 100,000: the `next_offset` value from the previous call. |

[Full reference](https://escouade.io/en/mail/docs/reference/preview_campaign.md)

### `campaign_action`

Actions: start (confirm=true after review, optional starts_at), pause, resume, stop, archive, restore, duplicate. Access: `send`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `campaign_id` | `cmp_…` identifier | yes | Campaign. |
| `action` | text | yes | Values: `start`, `pause`, `resume`, `stop`, `archive`, `restore`, `duplicate`. |
| `starts_at` | date | no | Earliest first departure; the sending window applies afterwards. |
| `confirm` | boolean | no | Start reviewed and confirmed. |
| `revision` | text | no | Fingerprint returned by preview_campaign, required for start. |

[Full reference](https://escouade.io/en/mail/docs/reference/campaign_action.md)

### `campaign_metrics`

Sends, confirmed deliveries, bounces, replies, errors, pending; historical opens and clicks kept apart. Access: `read`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `campaign_id` | `cmp_…` identifier | yes | Campaign. |
| `offset` | integer | no | The rank of the first item returned, from 0 to 100,000: the `next_offset` value from the previous call. |

[Full reference](https://escouade.io/en/mail/docs/reference/campaign_metrics.md)

### `campaign_history`

Sends taken over from the source, their dates, states and details, without putting any message back in the queue. Access: `read`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `campaign_id` | `cmp_…` identifier | yes | Campaign. |
| `offset` | integer | no | The rank of the first item returned, from 0 to 100,000: the `next_offset` value from the previous call. |

[Full reference](https://escouade.io/en/mail/docs/reference/campaign_history.md)

### `list_campaign_templates`

The space's templates, including those taken over from Prescriptio. Access: `read`.

[Full reference](https://escouade.io/en/mail/docs/reference/list_campaign_templates.md)

### `save_campaign_template`

Creates or updates a reusable template of the space: subject, text and optional HTML. Access: `send`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `template_id` | text | no | Identifier of the existing template. |
| `name` | text | yes | Name. |
| `subject` | text | yes | Subject. |
| `text` | text | yes | Text. |
| `html` | text | no | Optional HTML. |

[Full reference](https://escouade.io/en/mail/docs/reference/save_campaign_template.md)