Domains by API

The application’s sending domains can be managed from your code as well as from Email → Setup. Every call needs a live key of the application; the writes need the explicit email:manage (Email Send and manage on the key), which a full-access key does not hold. A test key answers 403 live_key_required, a partner key 403 application_key_required.

Call	What it does
`GET /v1/email/domains`	Lists the domains, newest first, a page at a time (`state`, `limit`, `cursor`).
`POST /v1/email/domains`	Adds a domain: `{ "name": "acme.sa" }`. `201` with it, or `200` when the application already has it.
`GET /v1/email/domains/{id}`	Reads one, by its id or its name.
`PATCH /v1/email/domains/{id}`	Changes its defaults (`from_name`, `from_local`) and its tracking.
`POST /v1/email/domains/{id}/verify`	Checks its records now, at most six a minute.
`DELETE /v1/email/domains/{id}`	Removes it: nothing sends from it any more.

Each write takes an Idempotency-Key, and a change is recorded on the account’s trail as the key. The domain.created, domain.verified, domain.failed and domain.removed webhooks follow each change.

The domain object

{
  "id": "0199f1c2-7a41-7c3e-9d2b-5e8f1a2b3c4d",
  "name": "acme.sa",
  "state": "verified",
  "created_at": "2026-10-23T09:00:00+00:00",
  "verified_at": "2026-10-23T09:12:00+00:00",
  "pending_until": null,
  "records": [
    {
      "purpose": "dkim",
      "type": "TXT",
      "name": "tawked._domainkey.acme.sa",
      "value": "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA…",
      "state": "found"
    },
    {
      "purpose": "return_path",
      "type": "MX",
      "name": "send.acme.sa",
      "value": "feedback-smtp.eu-west-1.amazonses.com",
      "priority": 10,
      "state": "found"
    },
    {
      "purpose": "return_path",
      "type": "TXT",
      "name": "send.acme.sa",
      "value": "v=spf1 include:_spf.tawked.com ~all",
      "state": "found"
    },
    {
      "purpose": "tracking",
      "type": "CNAME",
      "name": "links.acme.sa",
      "value": "track.tawked.com",
      "state": "found"
    }
  ],
  "defaults": {
    "from_name": "متجر أكمي",
    "from_local": "orders"
  },
  "authentication": {
    "dkim": "pass",
    "return_path": "working",
    "dmarc": "none"
  },
  "tracking": {
    "opens": true,
    "clicks": true,
    "subdomain": "links.acme.sa",
    "state": "active",
    "problem": null,
    "checked_at": "2026-10-23T10:00:00+00:00"
  },
  "receiving": null
}

state is pending, verified or failed; a removed domain answers 404 not_found. records are the DNS records to add at your DNS host, each with what the last check saw. authentication says how the domain’s mail authenticates, as the console shows it. tracking is there while tracking is on. receiving is the receiving address on a subdomain of the domain, { "address_id", "domain", "state" }, or null when it has none; it is read here and added or changed in the console or the Account API.

Errors

Beyond the shared checks: 422 domain_invalid, domain_public or domain_tawked on an add; 409 domain_taken (another application holds it, verified) or domain_limit; 409 domain_not_verified on a change before the domain is verified; 409 tracking_unavailable, 422 tracking_subdomain_invalid and 409 tracking_subdomain_taken on tracking; 429 rate_limited past ten adds or six checks a minute for an application; 503 email_unavailable when the sending service cannot be reached. Errors has each one.

Get started

Verify

Notifications

Email

Webhooks and errors

Partners

Build with AI

Domains by API

The domain object

Errors

​The domain object

​Errors

The domain object

Errors