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

# Contacts et audiences

> 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](https://subagent.fr/docs/desinscription.md)).

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](https://subagent.fr/docs/reference/list_contacts.md)

### `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](https://subagent.fr/docs/reference/get_contact.md)

### `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](https://subagent.fr/docs/reference/save_contact.md)

### `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](https://subagent.fr/docs/reference/set_contact_audiences.md)

### `list_audiences`

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

[Référence complète](https://subagent.fr/docs/reference/list_audiences.md)

### `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](https://subagent.fr/docs/reference/get_audience.md)

### `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](https://subagent.fr/docs/reference/save_audience.md)

### `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](https://subagent.fr/docs/reference/import_contacts.md)

### `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](https://subagent.fr/docs/reference/remove_audience_contact.md)