# Authentifier un domaine d'envoi

Un email envoyé depuis un domaine sans SPF ni DMARC finit dans les indésirables, quel que
soit son contenu. C'est le premier point à régler, avant d'écrire quoi que ce soit.

## Déclarer

```
POST /api/v1/domains
{ "domain": "exemple.fr" }
```

La réponse contient l'état actuel de l'authentification et les enregistrements à publier :

```json
{
  "domain": "exemple.fr",
  "authentication": { "spf": {...}, "dkim": {...}, "dmarc": {...}, "ok": false },
  "dns_records": [
    {
      "type": "TXT",
      "host": "@",
      "value": "v=spf1 ...",
      "role": "SPF, autorise notre serveur à envoyer pour ce domaine.",
      "publishable": true,
      "missing_values": []
    }
  ],
  "dns_ready": true,
  "dns_note": null,
  "next_step": "Poser les enregistrements DNS, puis rappeler POST /api/v1/domains/verify."
}
```

L'appel est idempotent : redéclarer le même domaine ne crée pas de doublon et renvoie son
état.

## Le champ `publishable`

Certaines valeurs dépendent de la configuration du serveur d'envoi et ne sont pas connues
au moment de la réponse. L'enregistrement porte alors `publishable: false` et
`missing_values` nomme ce qui manque.

Publier un enregistrement dans cet état casserait l'authentification du domaine, sans
message d'erreur nulle part : le domaine paraîtrait configuré et les emails partiraient
mal. Un agent doit signaler ces valeurs et attendre, pas les publier.

`dns_ready` résume : vrai quand tous les enregistrements sont publiables en l'état.

## Publier, puis vérifier

Publier se fait chez le registrar du domaine. C'est une étape humaine.

Ensuite :

```
POST /api/v1/domains/verify
{ "domain": "exemple.fr" }
```

La vérification lit le DNS public en direct, elle ne consulte pas un état enregistré chez
nous. Comptez de quelques minutes à quelques heures de propagation.

## Les trois enregistrements

- **SPF** dit quels serveurs ont le droit d'envoyer pour le domaine. Sans lui, un
  fournisseur ne peut pas distinguer votre envoi d'une usurpation.
- **DKIM** signe chaque message. La signature survit au transit, ce qui prouve que le
  message n'a pas été modifié en route.
- **DMARC** dit au fournisseur quoi faire quand SPF et DKIM échouent, et où envoyer les
  rapports. Commencer en `p=none` : on observe avant de durcir.

`ok` vaut vrai dès que SPF et DMARC sont présents. DKIM dépend du sélecteur, et
n'est vérifié que si un sélecteur a été déclaré.