Domaines d'envoi

Envoyer depuis votre propre domaine coûte sept enregistrements DNS, publiés une seule fois. La boucle ci-dessous est conçue pour être pilotée par un script.

Configurer un domaine de bout en bout

Voici la boucle qu'exécute un agent. Rien ici n'a besoin d'un humain.
  1. Déclarez le domaine.
    bash
    curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"domain":"atelier-nord.fr"}' \
  "https://www.agentsmail.io/api/v1/domains"
  2. Lisez les enregistrements à publier. GET /api/v1/domains les renvoie. Sept en pratique : un TXT pour la preuve de propriété, trois CNAME DKIM, un MX et un TXT pour le MAIL FROM personnalisé, un TXT pour DMARC. L'enregistrement de preuve vient en premier, et c'est lui qui décide de l'usage. Son nom est _agentmail-challenge.<domain> et sa valeur est le jeton propre à l'organisation. Le DKIM seul ne suffit pas : une identité déjà vérifiée dans le compte du fournisseur renvoie SUCCESS à quiconque la déclare, donc verified exige aussi cette preuve. Un nom TXT accepte plusieurs valeurs — deux organisations qui se transfèrent un domaine peuvent publier côte à côte. L'enregistrement de preuve est servi même quand le fournisseur est injoignable, parce que sa valeur vient de notre propre base de données.
    json
    {
  "success": true,
  "data": [
    {
      "id": "…",
      "domain": "atelier-nord.fr",
      "dkimStatus": "PENDING",
      "mailFromStatus": "PENDING",
      "verified": false,
      "ownershipProved": false,
      "lastCheckedAt": "2026-08-12T12:00:00.000Z",
      "sesUnavailable": false,
      "dnsRecords": [
        {"type": "TXT", "name": "_agentmail-challenge.atelier-nord.fr", "value": "Xy7pQ2rL9mNv4KtB1sZaWg"},
        {"type": "CNAME", "name": "abc._domainkey.atelier-nord.fr", "value": "abc.dkim.amazonses.com"},
        {"type": "MX", "name": "mail.atelier-nord.fr", "value": "feedback-smtp.eu-west-1.amazonses.com", "priority": 10},
        {"type": "TXT", "name": "mail.atelier-nord.fr", "value": "v=spf1 include:amazonses.com ~all"},
        {"type": "TXT", "name": "_dmarc.atelier-nord.fr", "value": "v=DMARC1; p=none;"}
      ]
    }
  ]
}
  3. Publiez-les chez le bureau d'enregistrement. Cette partie est hors de l'API.
  4. Revérifiez. POST /api/v1/domains/{domainId}/verify interroge à nouveau le fournisseur d'e-mail et enregistre la réponse. Interrogez-le régulièrement : la propagation DNS prend de quelques minutes à 72 h.
  5. Confirmez. GET /api/v1/me répond désormais "ready": true.
Le DKIM et la propriété conditionnent l'envoi, ensemble. mailFromStatus et l'enregistrement DMARC améliorent la délivrabilité — un MAIL FROM en attente ne bloque jamais un envoi. Le champ verified signifie utilisable : dkimStatus === "SUCCESS" et la preuve de propriété validée, sur le même domaine. Lisez verified et vous n'aurez jamais à réimplémenter la règle ; lisez ownershipProved et dkimStatus pour savoir lequel des deux enregistrements manque encore.

La propriété se prouve une fois, et n'est jamais révoquée

La preuve est un événement daté, pas un état continu. Une fois un domaine prouvé, retirer plus tard l'enregistrement TXT ne la révoque pas — sinon la moindre panne DNS couperait l'envoi. Republier la preuve pour une autre organisation transfère le domaine : un domaine prouvé appartient à exactement une organisation à la fois. La vérification est uniquement synchrone : elle a lieu quand vous appelez verify ou ouvrez l'écran du domaine. Il n'y a aucune tâche de fond.

Les enregistrements ne sont jamais stockés

Les enregistrements du fournisseur sont relus à chaque appel, parce qu'ils changent si l'identité est recréée. Ne les mettez pas en cache : une copie périmée envoie quelqu'un publier des enregistrements qui ne vérifient plus rien. L'enregistrement de preuve n'est une exception que par son origine — sa valeur est la nôtre, c'est pourquoi il survit à une panne du fournisseur — mais il est servi de la même façon, et vous ne le mettez jamais en cache.

Quand le fournisseur d'e-mail est injoignable

Les lectures n'échouent pas. GET /api/v1/domains renvoie le dernier état connu avec "sesUnavailable": true et son lastCheckedAt. verify, lui, échoue — vérifier est précisément ce que vous avez demandé, et prétendre le contraire serait mentir.