> Pour un agent : la carte de la documentation d'Escouade Mail est sur https://escouade.io/mail/docs/llms.txt ; chaque page existe en Markdown, à la même adresse suffixée `.md`.

# Domaines

> Une boîte vit sur un domaine. La première est sur le domaine commun, `subagentmail.fr` : elle reçoit et répond. Pour écrire le premier à quelqu'un, vous enregistrez votre domaine : vos boîtes portent votre nom.

## Le domaine commun

`sign_up` ouvre une boîte `nom@subagentmail.fr`. Ce domaine est partagé par tous les espaces.

- **Ses boîtes reçoivent**, dès leur création.
- **Avant le paiement**, elles préparent des brouillons et n'écrivent qu'à l'humain de l'espace.
- **Une fois le forfait payé, elles ne font que répondre** à qui leur a écrit. Un premier message, ou une relance sans réponse, est refusé avec le code `own_domain_required`.
- Les noms de service (`support`, `contact`, `admin`, `postmaster`…) et ceux qui contiennent `subagent` y sont réservés.
- Il ne demande aucun réglage DNS de votre côté.

Voir [Prix et paiement](https://escouade.io/offre).

## Votre domaine, en trois temps

1. **Enregistrer.** `add_domain` enregistre le domaine et rend la liste exacte des enregistrements DNS à publier.
2. **Publier.** Vous publiez ces enregistrements chez l'hébergeur DNS du domaine. C'est le seul geste qui se fait hors de l'assistant.
3. **Vérifier.** `verify_domain` contrôle chaque enregistrement dans le DNS. Quand la preuve de propriété, les deux clés DKIM, le SPF et le MX sont en place, le domaine est vérifié.

Ensuite, `create_inbox` crée des boîtes sur ce domaine. C'est d'elles que part un premier message à un destinataire. La montée progressive s'applique à chaque boîte : 5 e-mails par jour la première semaine, puis 10, 15 et 20.

À savoir avant de commencer :

- **Un sous-domaine suffit**, par exemple `agents.exemple.fr`. C'est le bon choix si votre domaine reçoit déjà du courrier ailleurs : l'enregistrement MX fait arriver tout le courrier du domaine enregistré dans vos boîtes Escouade Mail.
- **Un domaine vérifié n'appartient qu'à un espace.** Enregistrer un domaine ne le réserve pas : il revient au premier espace qui publie sa preuve de propriété. Un domaine dont un autre espace a déjà prouvé la propriété est refusé : `domain_taken`.
- **Cinq domaines au plus par espace** : au-delà, `domain_limit`.
- **Une messagerie publique** (`gmail.com`…) ne s'enregistre pas : `public_mail_domain`.
- **Il faut un forfait en cours.** Avant le paiement, `add_domain` est refusé avec le code `payment_required`.
- L'espace doit être vérifié, et la clé porter `manage_inboxes`.

## Les enregistrements DNS

`add_domain` rend six enregistrements. Cinq sont exigés ; DMARC est conseillé.

| Rôle | Type | Nom | Valeur | Exigé |
|---|---|---|---|---|
| Preuve de propriété | TXT | `_subagent.exemple.fr` | `subagent-verification=…` | oui |
| DKIM (RSA) | TXT | `sa-rsa-20261013._domainkey.exemple.fr` | `v=DKIM1; k=rsa; p=…` | oui |
| DKIM (Ed25519) | TXT | `sa-ed-20261013._domainkey.exemple.fr` | `v=DKIM1; k=ed25519; p=…` | oui |
| SPF | TXT | `exemple.fr` | `v=spf1 include:spf.subagent.fr -all` | oui |
| MX | MX | `exemple.fr` | `10 mx1.subagent.fr.` | oui |
| DMARC | TXT | `_dmarc.exemple.fr` | `v=DMARC1; p=none` | non |

Les valeurs exactes, avec votre jeton de preuve et vos clés, sont celles que rend `add_domain` : copiez-les telles quelles. Les noms des clés DKIM portent la date de l'enregistrement.

- **SPF** : un domaine n'a qu'un enregistrement SPF. S'il en a déjà un, ajoutez-y l'`include` donné par `add_domain` au lieu d'en créer un second.
- **DKIM** : la clé RSA est longue. Si votre hébergeur DNS limite une chaîne à 255 caractères, il la découpe en plusieurs chaînes d'un même enregistrement.
- **DMARC** : commencez par `p=none`, puis durcissez (`p=quarantine`, puis `p=reject`) une fois vos envois alignés.

## `add_domain`

Enregistre un domaine et rend ses enregistrements DNS. Rien ne change tant que `verify_domain` ne les a pas trouvés. Appelé de nouveau pour un domaine déjà enregistré par l'espace, il redonne ses enregistrements. Permission : `manage_inboxes`. L'espace doit être vérifié, et avoir un forfait en cours.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `domain` | texte | oui | Le nom de domaine seul, par exemple `exemple.fr` ou `agents.exemple.fr`. Sans `http://`, sans `@`. |

```text
Domaine exemple.fr enregistré (dom_4a7c1e9b2f6d48a3b5c0e8d1f2a6b9c7), en attente de vérification. Publiez ces enregistrements chez l’hébergeur DNS du domaine, puis appelez verify_domain. Tant qu’il n’est pas vérifié, aucune boîte ne s’y crée.

1. Preuve de propriété — TXT
   Nom    : _subagent.exemple.fr
   Valeur : subagent-verification=…
2. DKIM (RSA) — TXT
   Nom    : sa-rsa-20261013._domainkey.exemple.fr
   Valeur : v=DKIM1; k=rsa; p=…
   Note   : Valeur longue : si votre hébergeur DNS limite une chaîne à 255 caractères, il la découpe en plusieurs chaînes d’un même enregistrement.
3. DKIM (Ed25519) — TXT
   Nom    : sa-ed-20261013._domainkey.exemple.fr
   Valeur : v=DKIM1; k=ed25519; p=…
4. SPF — TXT
   Nom    : exemple.fr
   Valeur : v=spf1 include:spf.subagent.fr -all
   Note   : Un domaine n’a qu’un enregistrement SPF : s’il en a déjà un, ajoutez-y include:spf.subagent.fr au lieu d’en créer un second.
5. MX — MX
   Nom    : exemple.fr
   Valeur : 10 mx1.subagent.fr.
   Note   : Tout le courrier de exemple.fr arrive alors dans vos boîtes Subagent. Si ce domaine reçoit déjà du courrier ailleurs, enregistrez plutôt un sous-domaine, par exemple agents.exemple.fr.
6. DMARC (conseillé) — TXT
   Nom    : _dmarc.exemple.fr
   Valeur : v=DMARC1; p=none
   Note   : Conseillé, non exigé. À durcir ensuite (p=quarantine, puis p=reject) une fois vos envois alignés ; ajoutez rua=mailto:… vers une adresse que vous relevez pour recevoir les rapports.
```

## `verify_domain`

Contrôle dans le DNS les enregistrements du domaine, et rend l'état de chacun : trouvé, absent, ou valeur différente, avec la valeur vue. Un changement de DNS met parfois quelques minutes à se voir : corrigez, puis rappelez. Permission : `manage_inboxes`. L'espace doit être vérifié.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `domain` | texte | oui | Le domaine à contrôler (voir `list_domains`). |

Tant qu'un enregistrement exigé manque, la réponse dit lequel :

```text
Domaine exemple.fr pas encore vérifié : 4 enregistrements exigés sur 5 sont en place ; à corriger : SPF (valeur différente). Un changement de DNS met parfois quelques minutes à se voir : corrigez, puis rappelez verify_domain.
```

Quand la preuve de propriété, les deux clés DKIM, le SPF et le MX sont en place, la réponse dit que le domaine est vérifié et que des boîtes peuvent y être créées. Elle signale aussi un DMARC absent : il est conseillé, non exigé.

Chaque réponse est suivie de la liste des enregistrements, chacun avec son état. Si la résolution DNS elle-même échoue, rien n'est contrôlé et l'état du domaine ne change pas : code `dns_unavailable`.

## `list_domains`

Liste les domaines enregistrés par l'espace, avec leur état, leurs enregistrements DNS et ce qui a été vu au dernier contrôle. Il ne prend aucun paramètre. Permission : `manage_inboxes` ou `read`.

## `remove_domain`

Retire un domaine de l'espace : plus aucune boîte ne s'y crée, et le serveur de messagerie cesse de recevoir son courrier. Refusé tant qu'une boîte de l'espace vit sur ce domaine : supprimez-les d'abord (`domain_in_use`). À faire avant de pointer le MX du domaine ailleurs. Pensez ensuite à retirer ses enregistrements de votre DNS. Irréversible : le réenregistrer donnera de nouvelles clés DKIM. Permission : `manage_inboxes`. L'espace doit être vérifié.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `domain` | texte | oui | Le domaine à retirer (voir `list_domains`). |
| `confirm` | booléen | oui | Doit valoir `true` : le retrait est irréversible. |

## La qualité d'un domaine

Sur 7 ou 30 jours, `domain_quality` dit ce que les boîtes d'un domaine ont envoyé et ce qu'il en est advenu : envois acceptés, remises confirmées, rebonds, plaintes, leurs taux, l'état du DNS, et les quotas et protections de chaque boîte. Ce n'est pas un score de réputation : ce sont les envois d'Escouade Mail, l'historique repris d'un autre outil en est exclu. `inspect_domain` regarde, avant tout enregistrement, où le domaine reçoit déjà son courrier (MX) et ce que dit son SPF, et propose un sous-domaine d'envoi quand le domaine reçoit ailleurs.

## `inspect_domain`

Contrôle les MX et le SPF actuels avant l’enregistrement. Accès : `manage_inboxes`.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `domain` | texte | oui | Nom de domaine sans adresse mail ni URL. |

[Référence complète](https://escouade.io/mail/docs/reference/inspect_domain.md)

## `domain_quality`

Affiche dans Domaines la qualité d’envoi d’un domaine appartenant à cet espace sur 7 ou 30 jours : configuration DNS connue, envois Escouade Mail, livraisons confirmées, rebonds, plaintes, quotas et protections de ses boîtes accessibles. Accès : `read` ou `manage_inboxes`.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `domain` | texte | oui | Domaine enregistré dans cet espace (list_domains). |
| `days` | entier | non | Période en jours civils de Paris, aujourd’hui inclus. |

[Référence complète](https://escouade.io/mail/docs/reference/domain_quality.md)

## Les états d'un domaine

| État | Sens |
|---|---|
| `pending` | En attente de vérification : DNS à publier. Aucune boîte ne s'y crée. |
| `verified` | Vérifié : on y crée des boîtes, et elles envoient. |
| `suspended` | Suspendu : un enregistrement exigé a disparu du DNS. Ses boîtes n'envoient plus. |

Un domaine vérifié est recontrôlé chaque jour. Si un enregistrement exigé a disparu, le domaine est suspendu : ses messages attendent, et tout nouvel envoi est refusé avec le code `domain_suspended`. Remettez les enregistrements en place : un domaine suspendu est recontrôlé toutes les heures et se relève de lui-même, ou tout de suite par `verify_domain`.

## Les champs d'un domaine

| Champ | Contenu |
|---|---|
| `id` | L'identifiant du domaine, `dom_…`. |
| `domain` | Le nom de domaine. |
| `status`, `status_reason` | L'état, et la raison d'une suspension. |
| `created_at`, `verified_at`, `last_checked_at` | Les dates, en ISO 8601. |
| `records` | Les enregistrements : `role` (`ownership`, `dkim`, `spf`, `mx`, `dmarc`), `label`, `type` (`TXT` ou `MX`), `name`, `value`, `required`, `note`, et au dernier contrôle `state` (`found`, `missing`, `different`) et `seen`. |