> Pour un agent : la carte du site est sur https://subagent.fr/llms.txt ; chaque page existe en Markdown, à la même adresse suffixée `.md`. # Campagnes > Une campagne envoie une séquence de messages à une audience, depuis une de vos boîtes. Votre agent la prépare, la relit avec l'aperçu, puis la lance : les envois partent dans le créneau de l'espace, au rythme des quotas de la boîte. ## Ce qu'est une campagne - **Une boîte** expéditrice (son adresse principale ou un de ses alias) et, si vous voulez, une adresse de réponse. - **Une audience** : la liste de contacts qui recevra la campagne (voir [Contacts et audiences](https://subagent.fr/docs/contacts.md)). - **Une séquence de 1 à 4 étapes** : le premier message, puis jusqu'à trois relances, chacune un nombre de jours après la précédente. - **De 1 à 3 variantes par étape** : avec deux variantes ou plus, c'est un test A/B. Chaque contact reçoit une seule variante, attribuée au hasard, et les performances les comparent. Le test se règle étape par étape. Les champs `{{prenom}}`, `{{societe}}`… viennent des contacts de l'audience. Un champ vide pour un contact bloque son envoi : l'aperçu le signale avant le lancement. Seul `{{unsubscribe_url}}` est remplacé au départ, par le lien de désinscription en un clic. ## Le parcours 1. `save_campaign` enregistre un brouillon de campagne. Tant qu'elle n'est pas lancée, elle se corrige autant de fois que nécessaire. 2. `preview_campaign` relit la campagne sans rien envoyer : destinataires, blocages, doublons, champs manquants de chaque variante, et un aperçu personnalisé de chaque étape. Il rend une `revision`. 3. `campaign_action` avec `action` = `start`, `confirm` = `true` et cette `revision` lance la campagne. Si la campagne ou son audience a changé depuis l'aperçu, le lancement est refusé (`campaign_changed`) : on relit, puis on relance. 4. Ensuite, `pause` retient les envois en file, `resume` les reprend, `stop` annule ceux qui ne sont pas déjà partis. `archive`, `restore` et `duplicate` rangent ou copient une campagne. Une réponse d'un contact arrête ses relances, et celles des autres contacts identifiés de la même société. Les règles de l'espace s'appliquent à chaque envoi : créneau, quota du jour de la boîte, étalement, liste de blocage (voir [Règles d'envoi](https://subagent.fr/docs/regles-envoi.md)). ## Les modèles Un modèle garde un objet, un texte et un HTML facultatif, réutilisables d'une campagne à l'autre : `list_campaign_templates` les liste, `save_campaign_template` en crée ou en modifie un. Dans l'application, un modèle se pose sur une variante d'un geste. ## Les performances et l'historique `campaign_metrics` donne les envois, les remises confirmées, les rebonds, les réponses, les erreurs et les attentes, par étape et par variante. Un SMTP accepté n'est pas compté comme une livraison. `campaign_history` liste les envois d'une campagne reprise d'un autre outil (Prescriptio) : ses ouvertures et ses clics restent à part, et un historique repris ne repart jamais. ## Revenir à la version d'avant Quand quelqu'un change les étapes d'un brouillon de campagne ou le contenu d'un modèle, la version remplacée est gardée, avec son auteur et son heure : `get_campaign` et `list_campaign_templates` la rendent dans `previous`. L'application propose alors « Revenir » ; enregistrer `previous.steps` (ou le contenu du modèle) la rétablit, et la version courante devient à son tour la précédente. Voir [La main courante](https://subagent.fr/docs/main-courante.md). ## Les outils ### `list_campaigns` Campagnes de l’espace, natives ou reprises de Prescriptio. Accès : `read`. | Paramètre | Type | Obligatoire | Description | |---|---|---|---| | `offset` | entier | non | Le rang du premier élément rendu, de 0 à 100 000 : la valeur `next_offset` de l’appel précédent. | | `archived` | booléen | non | Afficher les archives. | [Référence complète](https://subagent.fr/docs/reference/list_campaigns.md) ### `get_campaign` Contenu, audience, étapes, état, performances et première page d’historique d’une campagne accessible à cette clé. Accès : `read`. | Paramètre | Type | Obligatoire | Description | |---|---|---|---| | `campaign_id` | identifiant `cmp_…` | oui | Campagne. | | `offset` | entier | non | Le rang du premier élément rendu, de 0 à 100 000 : la valeur `next_offset` de l’appel précédent. | [Référence complète](https://subagent.fr/docs/reference/get_campaign.md) ### `save_campaign` 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. Accès : `send`. | Paramètre | Type | Obligatoire | Description | |---|---|---|---| | `campaign_id` | identifiant `cmp_…` | non | Brouillon à modifier, facultatif. | | `name` | texte | oui | Nom. | | `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 | Les étapes, de 1 à 4 : `delay_days` (0 à 90 jours après l’étape d’avant) et de 1 à 3 variantes, chacune avec `subject`, `text` et `html` facultatif. | [Référence complète](https://subagent.fr/docs/reference/save_campaign.md) ### `preview_campaign` Contrôle les destinataires, les blocages, les doublons et tous les champs de chaque variante. Accès : `read`. | Paramètre | Type | Obligatoire | Description | |---|---|---|---| | `campaign_id` | identifiant `cmp_…` | oui | Campagne. | | `offset` | entier | non | Le rang du premier élément rendu, de 0 à 100 000 : la valeur `next_offset` de l’appel précédent. | [Référence complète](https://subagent.fr/docs/reference/preview_campaign.md) ### `campaign_action` Actions : start (confirm=true après relecture, starts_at facultatif), pause, resume, stop, archive, restore, duplicate. Accès : `send`. | 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. | [Référence complète](https://subagent.fr/docs/reference/campaign_action.md) ### `campaign_metrics` Envois, remises confirmées, rebonds, réponses, erreurs, attentes ; ouvertures et clics historiques séparés. Accès : `read`. | Paramètre | Type | Obligatoire | Description | |---|---|---|---| | `campaign_id` | identifiant `cmp_…` | oui | Campagne. | | `offset` | entier | non | Le rang du premier élément rendu, de 0 à 100 000 : la valeur `next_offset` de l’appel précédent. | [Référence complète](https://subagent.fr/docs/reference/campaign_metrics.md) ### `campaign_history` Envois repris de la source, leurs dates, états et détails, sans remettre de messages en file. Accès : `read`. | Paramètre | Type | Obligatoire | Description | |---|---|---|---| | `campaign_id` | identifiant `cmp_…` | oui | Campagne. | | `offset` | entier | non | Le rang du premier élément rendu, de 0 à 100 000 : la valeur `next_offset` de l’appel précédent. | [Référence complète](https://subagent.fr/docs/reference/campaign_history.md) ### `list_campaign_templates` Modèles de l’espace, dont ceux repris de Prescriptio. Accès : `read`. [Référence complète](https://subagent.fr/docs/reference/list_campaign_templates.md) ### `save_campaign_template` Crée ou modifie un modèle réutilisable de l’espace : objet, texte et HTML facultatif. Accès : `send`. | Paramètre | Type | Obligatoire | Description | |---|---|---|---| | `template_id` | texte | non | Identifiant du modèle existant. | | `name` | texte | oui | Nom. | | `subject` | texte | oui | Objet. | | `text` | texte | oui | Texte. | | `html` | texte | non | HTML facultatif. | [Référence complète](https://subagent.fr/docs/reference/save_campaign_template.md)