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

# Connecting a domain

> Verify your own sending and receiving domain with DNS records.

A domain is the part after the `@` in an agent's email address. Register a custom domain to send and receive on your own brand (for example `support@acme.com`) instead of the default platform domain. Registration is one identity that both sends and receives, so verification publishes DKIM, SPF, and DMARC records for outbound mail plus an inbound MX record for replies.

You don't have to register anything to start. Every organization can use the default platform domain `agents.anyreach.ai` without verifying, so addresses like `<name>@agents.anyreach.ai` work out of the box. Register a custom domain only when you want mail to come from your own domain.

<Note>
  Domains are unique platform-wide. Registering a domain that another organization already holds returns `409 The domain <domain> is already registered.`
</Note>

## Register a domain

Send the bare domain (no `@`, no subdomain prefix). The platform registers it with the email provider, enables receiving by default, and stores the DNS records you must publish.

```bash theme={null}
curl -X POST https://api.anyreach.ai/core/email-domains \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>" \
  -H "Content-Type: application/json" \
  -d '{"domain": "acme.com"}'
```

| Field      | Type     | Default  | Description                                                                          |
| ---------- | -------- | -------- | ------------------------------------------------------------------------------------ |
| `domain`   | `string` | —        | Required. The domain to register, lowercased and validated (for example `acme.com`). |
| `provider` | `string` | `resend` | Email provider. Leave as the default.                                                |

The response includes the new domain with its `status` and the `dns_records` to publish:

```json theme={null}
{
  "id": "...",
  "domain": "acme.com",
  "provider": "resend",
  "status": "pending",
  "dns_records": [
    {
      "type": "MX",
      "name": "...",
      "value": "...",
      "priority": 10,
      "status": "pending"
    }
  ]
}
```

## Publish the DNS records

Add every returned record at your DNS provider exactly as given, then verify. Each record carries its own `status`, and the domain only becomes usable once all records resolve. DNS changes can take a few minutes to several hours to propagate.

| Field      | Type     | Description                                                                                                    |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `type`     | `string` | Record type, such as `MX`, `TXT`, or `CNAME`. The inbound `MX` record is what makes replies reach your agents. |
| `name`     | `string` | The host/name to set at your registrar.                                                                        |
| `value`    | `string` | The record value to publish.                                                                                   |
| `priority` | `number` | Priority for `MX` records (lower wins). Absent on other types.                                                 |
| `status`   | `string` | Per-record verification state: `verified`, `pending`, or `failed`.                                             |

<Warning>
  Records must stay in place to keep working. Removing a published record after verification breaks sending or receiving on the domain. Do not delete them once verified.
</Warning>

## Verify vs. refresh

Two actions move a domain toward `verified`. They are different operations.

| Action             | Endpoint                                       | What it does                                                                                     | When to use                                                    |
| ------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| **Verify**         | `POST /core/email-domains/{domain_id}/verify`  | Re-initiates provider DNS verification, then re-reads status and records.                        | After you first publish the records, or after fixing a record. |
| **Refresh status** | `POST /core/email-domains/{domain_id}/refresh` | A passive re-read of the current provider status and records. Does not re-initiate verification. | To re-check progress while DNS is still propagating.           |

```bash theme={null}
# Re-initiate verification (use after publishing or fixing records)
curl -X POST https://api.anyreach.ai/core/email-domains/<domain_id>/verify \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>"

# Passive re-read of status (use while waiting on propagation)
curl -X POST https://api.anyreach.ai/core/email-domains/<domain_id>/refresh \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>"
```

<Tip>
  Verify after every DNS edit; refresh in between to watch records flip to `verified` without re-triggering the provider. Once the last record is verified, the whole domain reports `verified`.
</Tip>

## Domain status

The domain `status` normalizes to one of three values regardless of the provider's raw vocabulary:

| Status     | Meaning                                                                                 |
| ---------- | --------------------------------------------------------------------------------------- |
| `pending`  | Verification is in progress or not yet complete. One or more records have not resolved. |
| `verified` | Every record resolved. The domain can send and receive.                                 |
| `failed`   | The provider reported a verification failure. Re-check the records and verify again.    |

## Scopes

| Operation                | Required scope                                 |
| ------------------------ | ---------------------------------------------- |
| List, read, refresh      | `email_domains:read` or `email_domains:manage` |
| Register, verify, delete | `email_domains:manage`                         |

## Steps

<Steps>
  <Step title="Register the domain">
    `POST /core/email-domains` with the bare domain. The response returns `status: pending` and the `dns_records` to publish.
  </Step>

  <Step title="Publish the DNS records">
    Add every record (DKIM/SPF/DMARC plus the inbound MX) at your DNS provider, exactly as returned.
  </Step>

  <Step title="Verify">
    `POST /core/email-domains/{domain_id}/verify` to re-initiate provider verification.
  </Step>

  <Step title="Wait and refresh">
    While DNS propagates, `POST /core/email-domains/{domain_id}/refresh` to re-check without re-triggering. When the last record resolves, `status` becomes `verified`.
  </Step>

  <Step title="Create addresses">
    Once verified, create agent email addresses on the domain. See [Email addresses](/email/email-addresses).
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Email addresses" icon="at" href="/email/email-addresses">
    Create agent addresses on a verified domain or on `agents.anyreach.ai`.
  </Card>

  <Card title="Email overview" icon="envelope" href="/email/overview">
    How agents send and receive email across the platform.
  </Card>
</CardGroup>