# Désinscription et blocages

> Chaque e-mail porte un lien de désinscription en un clic. Une personne qui se désinscrit, répond « STOP » ou signale un message ne reçoit plus rien de l'espace. Un agent ne peut pas lever ce blocage.

## Comment une personne se désinscrit

- **Par le lien en un clic.** Chaque message sortant porte les en-têtes `List-Unsubscribe` et `List-Unsubscribe-Post` (RFC 8058) : la messagerie du destinataire affiche son propre bouton de désinscription. Le lien est unique par message.
- **Par la page du lien.** Ouvrir le lien affiche une page qui demande confirmation. Un simple chargement de la page ne désinscrit pas : il faut le bouton, ou le clic de la messagerie.
- **Par une réponse.** « STOP », « désinscrivez-moi », « merci de me désabonner », « unsubscribe », « retirez-moi de votre liste », « je souhaite ne plus recevoir vos messages » : dans le texte nouveau d'une réponse, ces demandes valent désinscription. Le texte cité et les réponses automatiques ne comptent pas.

Tant que le correspondant n'a pas écrit dans le fil, le serveur ajoute en pied du message une mention « Pour ne plus recevoir nos messages », suivie du lien. Pour placer le lien vous-même, écrivez `{{unsubscribe_url}}` dans le texte. Dès que le correspondant a écrit, c'est une conversation : plus de pied visible, le lien reste dans les en-têtes.

Le lien d'un envoi de test (`test`) ne désinscrit personne.

## Ce que fait une désinscription

- L'adresse entre dans la liste de blocage de l'espace : plus aucune boîte de l'espace ne lui écrit.
- Les messages qui attendaient de partir vers elle sont annulés.
- Le fil passe au statut `unsubscribed`.
- Tout nouvel envoi vers elle est refusé avec le code `recipient_suppressed`.

## La liste de blocage

| Raison | Origine | Portée | Se lève |
|---|---|---|---|
| `unsubscribe` | Lien en un clic, page de désinscription, réponse « STOP ». | L'espace | Par un administrateur de Subagent, à la demande écrite de la personne. |
| `complaint` | La personne a signalé un message comme indésirable. | L'espace | Par un administrateur de Subagent, à la demande écrite de la personne. |
| `hard_bounce` | Adresse morte : un rebond définitif. | Toute la plateforme | Elle reste bloquée. |
| `manual` | Ajout par `add_suppression`. | L'espace | Par `remove_suppression`, avec la permission `approve`. |

Une entrée bloque une adresse, ou un domaine entier.

## `add_suppression`

Ajoute une adresse ou un domaine à la liste de blocage de l'espace : plus rien ne leur sera envoyé, et ce qui attendait de partir vers eux est annulé. À appeler dès qu'un correspondant demande à ne plus être contacté. Permission : `send` ou `approve`.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `address` | texte | oui | Une adresse (`marie@exemple.com`) ou un domaine entier (`@exemple.com`). |
| `note` | texte | non | La raison, pour le journal. 300 caractères au plus. |

```text
Bloqué julien.roux@exemple.com : plus aucun envoi de l’espace. 1 message(s) en attente annulé(s).
```

Une messagerie publique ne se bloque pas en entier : un domaine comme `gmail.com` est refusé avec le code `public_mail_domain`. Bloquez les adresses une à une.

## `remove_suppression`

Retire de la liste une entrée ajoutée à la main. Permission : `approve`.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `address` | texte | oui | L'adresse ou le domaine (`@exemple.com`) à débloquer. |

Une désinscription, une plainte ou une adresse morte ne se lèvent pas par cet outil : l'appel est refusé avec le code `suppression_protected`.

## `list_suppressions`

Liste les adresses et les domaines bloqués pour l'espace, les plus récents d'abord. Permission : `read`.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `query` | texte | non | Une partie d'adresse ou de domaine. Avec `query`, la recherche porte aussi sur les adresses mortes communes à la plateforme. |
| `cursor` | texte | non | Le curseur de la page suivante : la valeur `next_cursor` de l'appel précédent. |
| `limit` | entier | non | Le nombre d'éléments rendus, de 1 à 100. 20 par défaut. |

Chaque entrée porte `value`, `kind` (`address` ou `domain`), `reason`, `scope` (`tenant` pour l'espace, `global` pour la plateforme) et `created_at`.

## Pour un agent

- Un refus `recipient_suppressed` ne se contourne pas : n'écrivez plus à cette adresse, depuis aucune boîte.
- Un correspondant qui demande, même poliment, à ne plus être contacté se bloque avec `add_suppression`.
- Dans un fil `unsubscribed`, tout envoi est refusé. Un fil `bounced` signale une adresse en échec.