Contacts et audiences · Documentation Subagent

Un contact est une fiche par adresse : son nom, ses champs, ses tags, et ce qui le bloque. Une audience est une liste de contacts, celle qu’une campagne reçoit. Votre agent les tient à jour ; rien ici n’envoie un e-mail.

Le répertoire

Chaque adresse a une fiche globale dans l’espace : un nom, des champs libres (fields, des valeurs texte comme prenom ou societe) et des tags (labels). list_contacts cherche dans le répertoire (adresse, nom, champs), filtre par tag, par audience ou par état d’inscription. get_contact lit une fiche, ses audiences et son blocage effectif.

L’état d’inscription dit ce que l’espace sait : subscribed (aucun blocage connu, ce n’est pas une preuve de consentement), unsubscribed (désinscription) ou blocked (autre blocage effectif : rebond, plainte, blocage manuel). Une adresse bloquée ne reçoit plus rien, depuis aucune boîte (voir Désinscription).

Le répertoire et les audiences demandent une clé qui accède à toutes les boîtes de l’espace : une clé limitée à certaines boîtes est refusée (contact_scope, audience_scope).

Les audiences

save_audience crée une audience ou la renomme ; import_contacts y ajoute ou actualise de 1 à 500 contacts à la fois (un lot qui contient une erreur est refusé en entier) ; remove_audience_contact en retire une adresse. Une adresse ne figure qu’une fois par audience.

Une audience garde sa propre copie des champs de chaque contact : modifier la fiche globale (save_contact) ne réécrit ni les audiences ni les campagnes déjà programmées. set_contact_audiences choisit d’un coup toutes les audiences d’une fiche : une nouvelle appartenance copie la fiche globale, celles qui restent gardent leurs champs.

Retirer un contact d’une audience ne touche pas une campagne déjà programmée. Pour arrêter tout envoi à une adresse, on la bloque (add_suppression).

Les outils

`list_contacts`

Répertoire global de l’espace, indépendant des audiences : recherche, tags, appartenance et désinscription ou autre blocage effectif. Accès : read.

Paramètre	Type	Obligatoire	Description
`query`	texte	non	Recherche dans l’adresse, le nom et les champs.
`label`	texte	non	Tag exact.
`audience_id`	identifiant `aud_…`	non	Limiter à une audience de l’espace.
`subscription`	texte	non	subscribed : aucun blocage connu (pas une preuve de consentement). unsubscribed : désinscription. blocked : autre blocage effectif.
`offset`	entier	non	Le rang du premier élément rendu, de 0 à 100 000 : la valeur `next_offset` de l’appel précédent.
`limit`	entier	non	Le nombre de fiches rendues, de 1 à 200. 100 par défaut.

Référence complète

`get_contact`

Fiche globale, audiences et blocage effectif. Accès : read.

Paramètre	Type	Obligatoire	Description
`email`	texte	oui	Adresse exacte du contact.

Référence complète

`save_contact`

Crée ou modifie la fiche globale : les propriétés absentes restent conservées. Accès : send.

Paramètre	Type	Obligatoire	Description
`email`	texte	oui	Adresse unique : crée la fiche si elle n’existe pas.
`name`	texte	non	Nom. Absent : conservé ; vide : effacé.
`fields`	objet	non	Remplace les champs globaux si fourni ; les champs propres aux audiences restent inchangés.
`labels`	liste	non	Remplace les tags globaux si fourni.

Référence complète

`set_contact_audiences`

Remplace toutes les appartenances du contact par audience_ids (vide : aucune). Accès : send.

Paramètre	Type	Obligatoire	Description
`email`	texte	oui	Adresse exacte de la fiche existante.
`audience_ids`	liste	oui	Toutes les audiences de la fiche, 200 au plus. Une liste vide la retire de toutes.

Référence complète

`list_audiences`

Audiences de l’espace, provenance et nombre de contacts. Accès : read.

Référence complète

`get_audience`

Contacts d’une audience, 200 par page ; reprendre à next_offset. Accès : read.

Paramètre	Type	Obligatoire	Description
`audience_id`	identifiant `aud_…`	oui	Audience.
`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_audience`

Crée une audience, ou renomme celle indiquée par audience_id. Accès : send.

Paramètre	Type	Obligatoire	Description
`audience_id`	identifiant `aud_…`	non	Audience à renommer, facultative.
`name`	texte	oui	Nom de l’audience.

Référence complète

`import_contacts`

Ajoute ou actualise de 1 à 500 contacts. Accès : send.

Paramètre	Type	Obligatoire	Description
`audience_id`	identifiant `aud_…`	oui	Audience de destination.
`contacts`	liste	oui	De 1 à 500 contacts : `email` (obligatoire), `name`, `fields` (valeurs texte) et `labels`. Un lot invalide est refusé en entier.

Référence complète

`remove_audience_contact`

Retire l’adresse d’une audience. Accès : send.

Paramètre	Type	Obligatoire	Description
`audience_id`	identifiant `aud_…`	oui	Audience.
`email`	texte	oui	Adresse exacte.

Référence complète