Campagnes · Documentation Subagent

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).
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

save_campaign enregistre un brouillon de campagne. Tant qu’elle n’est pas lancée, elle se corrige autant de fois que nécessaire.
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.
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.
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).

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.

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

`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

`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

`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

`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

`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

`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

`list_campaign_templates`

Modèles de l’espace, dont ceux repris de Prescriptio. Accès : read.

Référence complète

`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