Domains

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.

GET/v1/domains#

List sending domains.

Authentication: send your API key as a bearer token. See Authentication.

Query parameters#

Response#

Status 200 OK.

{
  "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, HTTP 401: The API key is missing, malformed, revoked or unknown.
• rate_limited, HTTP 429: Too many requests for this key. Wait the number of seconds in Retry-After.

Example request#

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.

Request body#

Send a JSON object.

Example body:

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

Response#

Status 201 Created.

{
  "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, HTTP 401: The API key is missing, malformed, revoked or unknown.
• 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, HTTP 413: The body is over 256 KiB.
• plan_limit, HTTP 402: The plan's domain limit is reached.
• subscription_required, HTTP 402: The account has no active plan, so it cannot create sending domains. Nothing was created.
• rate_limited, HTTP 429: Too many requests for this key. Wait the number of seconds in Retry-After.

Example request#

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.

Path parameters#

Response#

Status 200 OK.

{
  "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, HTTP 401: The API key is missing, malformed, revoked or unknown.
• unknown_product, HTTP 404: No such sending domain on this account.
• provider_unavailable, HTTP 503: The DNS host could not be reached. retryable tells you whether to retry.
• rate_limited, HTTP 429: Too many requests for this key. Wait the number of seconds in Retry-After.

Example request#

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.

Path parameters#

Response#

Status 200 OK.

{
  "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, HTTP 401: The API key is missing, malformed, revoked or unknown.
• unknown_product, HTTP 404: No such sending domain on this account.
• provider_unavailable, HTTP 503: The DNS lookup failed. It is retryable.
• rate_limited, HTTP 429: Too many requests for this key. Wait the number of seconds in Retry-After.

Example request#

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