---
title: "API reference: Domains"
url: "https://coldmeetings.com/docs/api/domains.md"
canonical_url: "https://coldmeetings.com/docs/api/domains"
last_updated: "2026-10-23"
type: "reference"
summary: "Register a sending domain, get the SPF, DKIM and DMARC records it needs, publish them and check live DNS with the ColdMeetings API."
related: ["https://coldmeetings.com/docs/api.md", "https://coldmeetings.com/docs/errors.md"]
---

# API reference: Domains

> **For AI agents:** the complete index of ColdMeetings pages is [llms.txt](https://coldmeetings.com/llms.txt). Every page is also served as markdown at its URL plus .md.

Register a sending domain, get the SPF, DKIM and DMARC records it needs, publish them and check live DNS with the ColdMeetings API.

Sending domains. Register a domain you own, publish its records and check that they are live. Only mailboxes on a domain that passes the check may send.

Base URL: `YOUR_API_BASE_URL`. Every request and response is JSON. Errors use [one envelope](https://coldmeetings.com/docs/errors.md).

| Operation | What it does |
| --- | --- |
| [`GET /v1/domains`](#get-v1domains) | List sending domains. |
| [`POST /v1/domains`](#post-v1domains) | Register a sending domain you already own and get the DNS records it needs. |
| [`POST /v1/domains/{id}/dns`](#post-v1domainsiddns) | Publish the required records to your DNS host (Cloudflare). 503 until configured. |
| [`POST /v1/domains/{id}/check-dns`](#post-v1domainsidcheck-dns) | Check live DNS for SPF, DKIM and DMARC and mark the domain authenticated. |

## GET /v1/domains

List sending domains.

Authentication: send your API key as a bearer token. See [Authentication](https://coldmeetings.com/docs/authentication.md).

### Query parameters

| Name | Type | Notes |
| --- | --- | --- |
| `limit` | integer | Rows per page, 1 to 100. More than 100 is held to 100. |
| `cursor` | string | The next_cursor of the previous page, sent back unchanged to the same route. Leave it out for the first page. A cursor that was edited or came from another route is refused. |

### Response

Status 200 OK.

```json
{
  "domains": [
    {
      "id": "dom_4kT9xQp2Wm7ZsLr1VbN8cE",
      "domain": "acme-mail.example",
      "status": "pending_dns",
      "dkim_selector": "google",
      "created_at": "2026-10-17T12:00:00.000Z",
      "required_records": [
        {
          "type": "TXT",
          "name": "acme-mail.example",
          "content": "v=spf1 include:_spf.google.com ~all"
        },
        {
          "type": "TXT",
          "name": "_dmarc.acme-mail.example",
          "content": "v=DMARC1; p=none; rua=mailto:dmarc@acme-mail.example"
        }
      ],
      "dkim_note": "The DKIM record is issued by your mailbox host after the domain is added there. Re-register with dkim_value to see it listed, or publish it yourself."
    }
  ],
  "next_cursor": null
}
```

- `status` is `pending_dns` until SPF, DKIM and DMARC all check out, then `authenticated`.
- Oldest first, 20 a page. Send `limit` (1 to 100) for more, and send `next_cursor` back as `cursor` for the next page; `next_cursor` is `null` on the last page.

### Errors

- [`unauthorized`](https://coldmeetings.com/docs/errors.md#unauthorized), HTTP 401: The API key is missing, malformed, revoked or unknown.
- [`rate_limited`](https://coldmeetings.com/docs/errors.md#rate_limited), HTTP 429: Too many requests for this key. Wait the number of seconds in `Retry-After`.

### Example request

```bash
curl YOUR_API_BASE_URL/v1/domains \
  -H "Authorization: Bearer $COLDMEETINGS_API_KEY"
```

## POST /v1/domains

Register a sending domain you already own and get the DNS records it needs.

Register a domain you already own. Buying domains is not an API operation. Use a domain separate from your company website domain.

Authentication: send your API key as a bearer token. See [Authentication](https://coldmeetings.com/docs/authentication.md).

### Request body

Send a JSON object.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | Yes | At least 4 characters. Up to 253 characters. |
| `dkim_selector` | string | No | Default `"google"`. Pattern `^[a-z0-9-]{1,63}$`. |
| `dkim_value` | string | No | The DKIM TXT value your mailbox host issued. Added to required_records when given. Up to 2048 characters. |

Example body:

```json
{
  "domain": "acme-mail.example"
}
```

### Response

Status 201 Created.

```json
{
  "id": "dom_4kT9xQp2Wm7ZsLr1VbN8cE",
  "domain": "acme-mail.example",
  "status": "pending_dns",
  "dkim_selector": "google",
  "created_at": "2026-10-17T12:00:00.000Z",
  "required_records": [
    {
      "type": "TXT",
      "name": "acme-mail.example",
      "content": "v=spf1 include:_spf.google.com ~all"
    },
    {
      "type": "TXT",
      "name": "_dmarc.acme-mail.example",
      "content": "v=DMARC1; p=none; rua=mailto:dmarc@acme-mail.example"
    }
  ],
  "dkim_note": "The DKIM record is issued by your mailbox host after the domain is added there. Re-register with dkim_value to see it listed, or publish it yourself."
}
```

- `required_records` lists the SPF and DMARC records to publish. The DKIM record appears only when you pass `dkim_value`, because your mailbox host issues the key.
- `dkim_note` repeats that. Registering the same domain a second time answers `invalid_input`, so pass `dkim_value` on the first call if you already have it.

### Errors

- [`unauthorized`](https://coldmeetings.com/docs/errors.md#unauthorized), HTTP 401: The API key is missing, malformed, revoked or unknown.
- [`invalid_input`](https://coldmeetings.com/docs/errors.md#invalid_input), HTTP 400: The domain name is not valid, or it is already registered. A body that is empty, is not JSON or fails validation also answers this, and the message names the field.
- [`payload_too_large`](https://coldmeetings.com/docs/errors.md#payload_too_large), HTTP 413: The body is over 256 KiB.
- [`plan_limit`](https://coldmeetings.com/docs/errors.md#plan_limit), HTTP 402: The plan's domain limit is reached.
- [`subscription_required`](https://coldmeetings.com/docs/errors.md#subscription_required), HTTP 402: The account has no active plan, so it cannot create sending domains. Nothing was created.
- [`rate_limited`](https://coldmeetings.com/docs/errors.md#rate_limited), HTTP 429: Too many requests for this key. Wait the number of seconds in `Retry-After`.

### Example request

```bash
curl -X POST YOUR_API_BASE_URL/v1/domains \
  -H "Authorization: Bearer $COLDMEETINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"acme-mail.example"}'
```

## POST /v1/domains/{id}/dns

Publish the required records to your DNS host (Cloudflare). 503 until configured.

Creates a DNS zone for the domain at your DNS host (Cloudflare) and writes the SPF and DMARC records into it.

Authentication: send your API key as a bearer token. See [Authentication](https://coldmeetings.com/docs/authentication.md).

> This operation answers 503 `provider_unavailable` when its outside service cannot be reached. The DNS host could not be reached. Nothing is simulated and nothing is charged.

### Path parameters

| Name | Type | Notes |
| --- | --- | --- |
| `id` | string | Id of the domain. |

### Response

Status 200 OK.

```json
{
  "zone_id": "zone_8f2d1c",
  "records_written": 2,
  "note": "Point the registrar nameservers at the zone, then publish the DKIM record and run check-dns."
}
```

### Errors

- [`unauthorized`](https://coldmeetings.com/docs/errors.md#unauthorized), HTTP 401: The API key is missing, malformed, revoked or unknown.
- [`unknown_product`](https://coldmeetings.com/docs/errors.md#unknown_product), HTTP 404: No such sending domain on this account.
- [`provider_unavailable`](https://coldmeetings.com/docs/errors.md#provider_unavailable), HTTP 503: The DNS host could not be reached. `retryable` tells you whether to retry.
- [`rate_limited`](https://coldmeetings.com/docs/errors.md#rate_limited), HTTP 429: Too many requests for this key. Wait the number of seconds in `Retry-After`.

### Example request

```bash
curl -X POST YOUR_API_BASE_URL/v1/domains/dom_4kT9xQp2Wm7ZsLr1VbN8cE/dns \
  -H "Authorization: Bearer $COLDMEETINGS_API_KEY"
```

## POST /v1/domains/{id}/check-dns

Check live DNS for SPF, DKIM and DMARC and mark the domain authenticated.

Authentication: send your API key as a bearer token. See [Authentication](https://coldmeetings.com/docs/authentication.md).

### Path parameters

| Name | Type | Notes |
| --- | --- | --- |
| `id` | string | Id of the domain. |

### Response

Status 200 OK.

```json
{
  "domain": "acme-mail.example",
  "spf": true,
  "dkim": false,
  "dmarc": true,
  "authenticated": false,
  "status": "pending_dns"
}
```

- `authenticated` is `true` only when `spf`, `dkim` and `dmarc` are all `true`. Then the domain `status` becomes `authenticated` and stays that way.
- The check reads live DNS, so a record you just published can take a while to show.

### Errors

- [`unauthorized`](https://coldmeetings.com/docs/errors.md#unauthorized), HTTP 401: The API key is missing, malformed, revoked or unknown.
- [`unknown_product`](https://coldmeetings.com/docs/errors.md#unknown_product), HTTP 404: No such sending domain on this account.
- [`provider_unavailable`](https://coldmeetings.com/docs/errors.md#provider_unavailable), HTTP 503: The DNS lookup failed. It is retryable.
- [`rate_limited`](https://coldmeetings.com/docs/errors.md#rate_limited), HTTP 429: Too many requests for this key. Wait the number of seconds in `Retry-After`.

### Example request

```bash
curl -X POST YOUR_API_BASE_URL/v1/domains/dom_4kT9xQp2Wm7ZsLr1VbN8cE/check-dns \
  -H "Authorization: Bearer $COLDMEETINGS_API_KEY"
```

## Related

- [API reference](https://coldmeetings.com/docs/api.md)
- [Errors](https://coldmeetings.com/docs/errors.md)