campaign_action · Documentation d’Escouade Mail

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

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

{
  "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.

`campaign_action`