Déclarer un domaine

POST /api/v1/domains Déclare un domaine d'envoi et crée l'identité d'envoi que ses enregistrements prouveront. Rôle admin requis. C'est la première étape d'une boucle conçue pour être automatisée : déclarer, lire les enregistrements, les publier, puis vérifier jusqu'à ce que verified vaille true.

Autorisation

Rôle dans l'organisation	Cet endpoint
`OWNER`	Autorisé
`ADMIN`	Autorisé
`MEMBER`	Refusé — `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.

Corps de la requête

Champ	Type	Obligatoire	Description
`domain`	string	oui	Le domaine ou sous-domaine depuis lequel envoyer, par exemple `mail.example.com`

Exemple

bash

curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mail.example.com"}' \
  "https://www.agentsmail.io/api/v1/domains"

Réponse

201 Created — la ressource créée.
400 Bad Request — la validation a échoué ; details porte les erreurs champ par champ.
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.
429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Champs de la réponse

201 avec le domaine déclaré et les enregistrements à publier.

Champ	Type	Description
`success`	boolean	Indique si l'opération a réussi
`data.id`	string	Identifiant du domaine déclaré
`data.domain`	string	Le domaine lui-même
`data.dkimStatus`	string	`PENDING`, `SUCCESS` ou `FAILED` — les clés de signature
`data.mailFromStatus`	string \	null
`data.mailFromDomain`	string \	null
`data.verified`	boolean	La seule question qui décide de l'envoi : DKIM `SUCCESS` et propriété prouvée
`data.ownershipProved`	boolean	Indique lequel des deux gestes manque encore
`data.lastCheckedAt`	string \	null
`data.sesUnavailable`	boolean	`true` signifie que vous lisez le dernier état connu, pas la vérité actuelle
`data.dnsRecords`	array	Les enregistrements à publier — `{type, name, value, purpose}`

Exemple de réponse

json

{
  "success": true,
  "data": {
    "id": "b71f…",
    "domain": "mail.example.com",
    "dkimStatus": "PENDING",
    "verified": false,
    "ownershipProved": false,
    "dnsRecords": [
      {"type": "CNAME", "name": "abc123._domainkey.mail.example.com", "value": "abc123.dkim.amazonses.com", "purpose": "dkim"}
    ]
  }
}