Declare a domain

POST /api/v1/domains Declares a sending domain and creates the sending identity its records will prove. Admin role required. This is step one of a loop designed to be automated: declare, read the records, publish them, then verify until verified is true.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused — `403`

A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Request body

Field	Type	Required	Description
`domain`	string	yes	The domain or subdomain to send from, e.g. `mail.example.com`

Example

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"

Response

201 Created — the created resource.
400 Bad Request — validation failed; details carries the field-level issues.
401 Unauthorized — missing or invalid key, or its owner left the organization.
403 Forbidden — the key's owner is a member of the organization, not an admin.
429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

201 with the declared domain and the records to publish.

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`data.id`	string	Identifier of the declared domain
`data.domain`	string	The domain itself
`data.dkimStatus`	string	`PENDING`, `SUCCESS` or `FAILED` — the signing keys
`data.mailFromStatus`	string \	null
`data.mailFromDomain`	string \	null
`data.verified`	boolean	The only question that decides sending: DKIM `SUCCESS` and ownership proved
`data.ownershipProved`	boolean	Which of the two gestures is still missing
`data.lastCheckedAt`	string \	null
`data.sesUnavailable`	boolean	`true` means you are reading the last known state, not the current truth
`data.dnsRecords`	array	The records to publish — `{type, name, value, purpose}`

Example response

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"}
    ]
  }
}