save_campaign · Documentation d’Escouade Mail

Crée ou modifie un brouillon : une boîte, une audience et une séquence de 1 à 4 étapes, avec 1 à 3 variantes par étape.

En bref

Propriété	Valeur
Titre	Préparer une campagne
Outil MCP	`save_campaign`, sur `https://api.subagent.fr/mcp`
Appelé par	l’assistant et la vue
Appel HTTP	`POST https://api.subagent.fr/v1/save_campaign`
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 :

Crée ou modifie un brouillon : une boîte, une audience et une séquence de 1 à 4 étapes, avec 1 à 3 variantes par étape. Les champs {{prenom}}, {{societe}}… viennent des contacts. Un champ vide bloque l’envoi. Seul {{unsubscribe_url}} est remplacé au départ.

Paramètres

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

Paramètre	Type	Obligatoire	Description
`campaign_id`	identifiant `cmp_…`	non	Brouillon à modifier, facultatif.
`name`	texte	oui	Nom. 160 caractères au plus.
`inbox_id`	identifiant `inb_…`	oui	Boîte expéditrice.
`from_address`	texte	non	Adresse principale ou alias de cette boîte.
`audience_id`	identifiant `aud_…`	non	Audience.
`reply_to`	texte	non	Adresse de réponse facultative.
`steps`	liste	oui

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/save_campaign \
  -H "Authorization: Bearer $SUBAGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Rentrée",
  "inbox_id": "inb_3f9c2a7e5b1d4c8e9a0f6b2d7c4e1a95",
  "audience_id": "aud_3c8f1a5e9d2b47c6a0e4f81b7d5c9e26",
  "steps": [
    {
      "variants": [
        {
          "subject": "Vos chantiers de la rentrée",
          "text": "Bonjour {{prenom}},\n\nUn mot sur vos chantiers.\n\n{{unsubscribe_url}}"
        }
      ]
    }
  ]
}'

MCP · tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "save_campaign",
    "arguments": {
      "name": "Rentrée",
      "inbox_id": "inb_3f9c2a7e5b1d4c8e9a0f6b2d7c4e1a95",
      "audience_id": "aud_3c8f1a5e9d2b47c6a0e4f81b7d5c9e26",
      "steps": [
        {
          "variants": [
            {
              "subject": "Vos chantiers de la rentrée",
              "text": "Bonjour {{prenom}},\n\nUn mot sur vos chantiers.\n\n{{unsubscribe_url}}"
            }
          ]
        }
      ]
    }
  }
}

Refus possibles

Code	HTTP	Ce qui s’est passé	Que faire
`campaign_not_editable`	409	La campagne n’est plus un brouillon (lancée, terminée, arrêtée) ou vient d’un autre outil : elle ne se modifie plus.	La dupliquer avec `campaign_action` (`duplicate`), puis corriger la copie.
`audience_scope`	403	Les audiences demandent un accès à toutes les boîtes de l’espace ; cette clé est limitée à certaines.	Passer par une clé qui accède à tout l’espace, ou par l’assistant de l’humain.
`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.

`save_campaign`