List domains and records

GET /api/v1/domains Every domain declared by the organization, with its verification status and the DNS records left to publish. The records are never stored: they are read back from the provider on every call, because they change if the identity is recreated.

Authorization

Role in the organizationThis endpoint
OWNERAllowed
ADMINAllowed
MEMBERAllowed
A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Example

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

Response

  • 200 OK — the call succeeded.
  • 401 Unauthorized — missing or invalid key, or its owner left the organization.
  • 429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

data is an array of:
verified answers the only question that matters. DKIM proves the domain can sign; the TXT challenge proves this organization owns it. A domain can sit at dkimStatus: "SUCCESS" and still block, with ownershipProved: false.
FieldTypeDescription
successbooleanIndicates if the operation was successful
data[].idstringIdentifier of the declared domain
data[].domainstringThe domain itself
data[].dkimStatusstringPENDING, SUCCESS or FAILED — the signing keys
data[].mailFromStatusstring \null
data[].mailFromDomainstring \null
data[].verifiedbooleanThe only question that decides sending: DKIM SUCCESS and ownership proved
data[].ownershipProvedbooleanWhich of the two gestures is still missing
data[].lastCheckedAtstring \null
data[].sesUnavailablebooleantrue means you are reading the last known state, not the current truth
data[].dnsRecordsarrayThe records to publish — {type, name, value, purpose}
paginationobject{total, page, limit, totalPages}

Example response

json
{
  "success": true,
  "data": [
    {
      "id": "b71f…",
      "domain": "mail.example.com",
      "dkimStatus": "SUCCESS",
      "mailFromStatus": "SUCCESS",
      "mailFromDomain": "bounce.mail.example.com",
      "verified": true,
      "ownershipProved": true,
      "lastCheckedAt": "2026-08-23T09:41:02.000Z",
      "sesUnavailable": false,
      "dnsRecords": [
        {"type": "CNAME", "name": "abc123._domainkey.mail.example.com", "value": "abc123.dkim.amazonses.com", "purpose": "dkim"},
        {"type": "TXT", "name": "_agentmail-challenge.mail.example.com", "value": "agentmail-verify=9f2c…", "purpose": "ownership"}
      ]
    }
  ]
}

Related