Vérifier un domaine

POST /api/v1/domains/{domainId}/verify Demande au fournisseur d'e-mail de relire le DNS et enregistre la réponse. Rôle admin requis. C'est l'appel à répéter après avoir publié vos enregistrements — et non GET /api/v1/domains, qui renvoie le dernier état connu. La propagation prend jusqu'à 72 heures, en général quelques minutes.

Autorisation

Rôle dans l'organisationCet endpoint
OWNERAutorisé
ADMINAutorisé
MEMBERRefusé — 403
Une clé porte le rôle que son créateur détient dans cette organisation — jamais un rôle sur AgentsMail lui-même. Voir Clés d'API.

Paramètres de chemin

ParamètreTypeDescription
domainIdstringObligatoire. Le domaine à revérifier

Exemple

bash
curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/domains/$DOMAIN_ID/verify"

Réponse

  • 200 OK — l'appel a réussi.
  • 401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
  • 403 Forbidden — le propriétaire de la clé est member de l'organisation, pas admin.
  • 404 Not Found — aucune ressource de ce type, ou elle appartient à une autre organisation. L'API ne confirme jamais qu'un identifiant existe à un appelant qui n'y a pas droit.
  • 429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Champs de la réponse

Le domaine après la vérification, même forme qu'à la lecture.
Publier deux fois ne fait rien gagner. Interrogez cet endpoint jusqu'à ce que verified vaille true ; en cas de panne du fournisseur, il répond par une erreur plutôt que par un état périmé, parce que la vérification est précisément ce qui a été demandé.
ChampTypeDescription
successbooleanIndique si l'opération a réussi
data.idstringIdentifiant du domaine déclaré
data.domainstringLe domaine lui-même
data.dkimStatusstringPENDING, SUCCESS ou FAILED — les clés de signature
data.mailFromStatusstring \null
data.mailFromDomainstring \null
data.verifiedbooleanLa seule question qui décide de l'envoi : DKIM SUCCESS et propriété prouvée
data.ownershipProvedbooleanIndique lequel des deux gestes manque encore
data.lastCheckedAtstring \null
data.sesUnavailablebooleantrue signifie que vous lisez le dernier état connu, pas la vérité actuelle
data.dnsRecordsarrayLes enregistrements à publier — {type, name, value, purpose}

Exemple de réponse

json
{
  "success": true,
  "data": {
    "id": "4d19c0a2",
    "domain": "mail.example.com",
    "dkimStatus": "SUCCESS",
    "mailFromStatus": "SUCCESS",
    "mailFromDomain": "bounce.mail.example.com",
    "verified": true,
    "ownershipProved": true,
    "lastCheckedAt": "2026-08-23T10:22:05.000Z",
    "sesUnavailable": true,
    "dnsRecords": [
      {
        "type": "CNAME",
        "name": "abc123._domainkey.mail.example.com",
        "value": "abc123.dkim.amazonses.com",
        "purpose": "dkim"
      }
    ]
  }
}

Recette pour agent

Déclarer un domaine, publier ses enregistrements et le vérifier forment une boucle qu'un agent peut exécuter de bout en bout. La propagation prend de quelques minutes à 72 heures : espacez les tentatives plutôt que de marteler.
js
const {data: domain} = await (
  await fetch(`${base}/domains`, {
    method: 'POST',
    headers: {...headers, 'content-type': 'application/json'},
    body: JSON.stringify({domain: 'mail.example.com'}),
  })
).json()

await publishToDns(domain.dnsRecords) // your registrar, your API

for (let wait = 30_000; wait < 3_600_000; wait *= 2) {
  const {data} = await (
    await fetch(`${base}/domains/${domain.id}/verify`, {method: 'POST', headers})
  ).json()

  if (data.verified) break
  if (!data.ownershipProved) console.log('DKIM is fine — the TXT challenge is what is missing')
  await new Promise((resolve) => setTimeout(resolve, wait))
}

Voir aussi