# Domaines

> Une boîte vit sur un domaine. Pour essayer, c'est le domaine commun `subagentmail.fr`. Pour aller plus loin, vous enregistrez le vôtre : vos boîtes portent votre nom et sortent des limites d'essai.

## Le domaine commun d'essai

`sign_up` ouvre une boîte `nom@subagentmail.fr`. Ce domaine est partagé par tous les espaces à l'essai, et ne sert qu'à l'essai.

- Ses boîtes envoient avec des [limites d'essai](https://subagent.fr/docs/regles-envoi.md#limites-essai) : au plus 3 destinataires distincts la première heure, 5 le premier jour, 10 la première semaine, puis 10 par semaine glissante.
- Les noms de service (`support`, `contact`, `admin`, `postmaster`…) et ceux qui commencent par `subagent` y sont réservés.
- Il ne demande aucun réglage DNS de votre côté.

## 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. Leurs envois ne comptent pas dans les limites d'essai. 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 Subagent.
- **Un domaine n'appartient qu'à un espace.** Un domaine déjà enregistré par un autre espace 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`.
- 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é.

| 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 tout est en place :

```text
Domaine exemple.fr vérifié : preuve de propriété, DKIM, SPF et MX sont en place. Vous pouvez y créer des boîtes (create_inbox avec ce domaine) : leurs envois ne comptent pas dans les limites d’essai, et chaque boîte démarre en réchauffage. DMARC n’est pas publié : il est conseillé.
```

Les deux réponses sont suivies 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`). 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. |

## 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é avant un envoi, quand son dernier contrôle a plus de 24 heures. 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, puis rappelez `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`. |