> Pour un agent : la carte de la documentation d'Escouade Mail est sur https://escouade.io/mail/docs/llms.txt ; chaque page existe en Markdown, à la même adresse suffixée `.md`.

# `campaign_action`

> Actions : start (confirm=`true` après relecture, `starts_at` facultatif), pause, resume, stop, archive, restore, duplicate.

## En bref

| Propriété | Valeur |
|---|---|
| Titre | Piloter une campagne |
| Outil MCP | `campaign_action`, sur `https://api.subagent.fr/mcp` |
| Appelé par | l’assistant et la vue |
| Appel HTTP | `POST https://api.subagent.fr/v1/campaign_action` |
| Accès | permission `send` |
| État de l'espace | vérifié : sinon, refus `space_unverified` |
| Effet | écriture |
| Vue dans l'assistant | non |

## Ce que fait l'outil

Le serveur décrit l'outil ainsi à l'agent qui se branche :

> Actions : start (confirm=`true` après relecture, `starts_at` facultatif), pause, resume, stop, archive, restore, duplicate. Une pause retient les envois en file ; stop annule ceux qui ne sont pas déjà partis. L’historique importé peut être archivé ou dupliqué, jamais relancé.

## Paramètres

`campaign_action` accepte ces paramètres. Un paramètre inconnu est refusé avec le code `invalid_argument`.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `campaign_id` | identifiant `cmp_…` | oui | Campagne. |
| `action` | texte | oui | Valeurs : `start`, `pause`, `resume`, `stop`, `archive`, `restore`, `duplicate`. |
| `starts_at` | date | non | Premier départ au plus tôt, ensuite le créneau s’applique. |
| `confirm` | booléen | non | Lancement relu et confirmé. |
| `revision` | texte | non | Empreinte rendue par `preview_campaign`, obligatoire pour start. 64 caractères au plus. |

## Résultat

L'outil rend un texte lisible en français et un objet structuré (`structuredContent`). En HTTP, la réponse est cet objet.

| Champ | Type | Contenu |
|---|---|---|
| `campaign` | objet | Une campagne : id (cmp_…), name, status (draft, scheduled, running, paused, completed, stopped), archived, `inbox_id`, `from_address`, `audience_id`, `reply_to`, steps (de 1 à 4 étapes : `delay_days` et variants, chacune avec subject, text, html), `starts_at`, `status_reason`, source, previous (dans `get_campaign` : les étapes qu’une correction a remplacées, avec l’auteur et l’heure de la correction), `created_at`, `updated_at`. |

## Exemple d'appel

Les valeurs sont fictives.

HTTP :

```sh
curl -X POST https://api.subagent.fr/v1/campaign_action \
  -H "Authorization: Bearer $SUBAGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "campaign_id": "cmp_6b2d9e41c7a84f03b5e1d28a90c4f7e3",
  "action": "pause"
}'
```

MCP (`tools/call`) :

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "campaign_action",
    "arguments": {
      "campaign_id": "cmp_6b2d9e41c7a84f03b5e1d28a90c4f7e3",
      "action": "pause"
    }
  }
}
```

## Refus possibles

| Code | HTTP | Ce qui s'est passé | Que faire |
|---|---|---|---|
| `campaign_not_ready` | 422 | L'aperçu signale des destinataires ou des champs bloquants : la campagne ne peut pas partir. | Relire `preview_campaign`, corriger l'audience ou les messages, puis relancer. |
| `campaign_changed` | 409 | La campagne ou son audience a changé depuis l'aperçu dont la `revision` est donnée. | Relire `preview_campaign` et lancer avec sa nouvelle `revision`. |
| `campaign_transition` | 409 | L'action demandée ne s'applique pas à une campagne dans cet état (par exemple reprendre une campagne qui n'est pas en pause). | Lire son état avec `get_campaign`, puis choisir l'action qui convient. |
| `client_domain_required` | 422 | Une application de la famille n'écrit un premier message, ne prépare et ne lance une campagne que depuis une boîte et une adresse d'un domaine vérifié de l'espace. Le domaine commun et celui de la marque restent aux agents et aux humains de l'espace. | Choisir une boîte d'un domaine que l'espace a prouvé : `list_domains`, puis `list_inboxes`. |

S'y ajoutent les refus communs à tous les outils (`unauthorized`, `forbidden`, `invalid_argument`, `rate_limited`, `internal`) : voir [Erreurs](https://escouade.io/mail/docs/erreurs.md#acces).

## Voir aussi

- [Campagnes : campaign_action](https://escouade.io/mail/docs/campagnes.md#campaign_action)
- [`preview_campaign`](https://escouade.io/mail/docs/reference/preview_campaign.md)
- [`get_campaign`](https://escouade.io/mail/docs/reference/get_campaign.md)
- [Tous les outils](https://escouade.io/mail/docs/reference/index.md)