Get one domain

GET /api/v1/domains/{domainId} One domain with its verification status and the DNS records to publish. A domainId belonging to another organization answers 404, never 403.

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.

Path parameters

ParameterTypeDescription
domainIdstringRequired. The domain to read

Example

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

Response

  • 200 OK — the call succeeded.
  • 401 Unauthorized — missing or invalid key, or its owner left the organization.
  • 404 Not Found — no such resource, or it belongs to another organization. The API never confirms that an id exists to a caller who has no right to it.
  • 429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

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}

Example response

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

Related