> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tawked.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Domains by API

> Add, read, check, update and remove the application's sending domains with a key that manages Email: the domain object, its records, its defaults and its open and click tracking.

The application's [sending domains](https://docs.tawked.com/email/senders.md) 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](https://docs.tawked.com/email/tracking.md). |
| `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](https://docs.tawked.com/webhooks/events.md#domain-events) follow each change.

## The domain object

```json theme={"dark"}
{
  "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](https://docs.tawked.com/email/receiving.md) 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](https://docs.tawked.com/errors.md#email) has each one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.