---
title: "Retrieve Sending Domain"
method: GET
path: "/newsletters/{id}/sending-domain"
tags: ["Newsletters"]
---

# Retrieve Sending Domain

`GET /newsletters/{id}/sending-domain`

Retrieve the DNS verification status and required records for a newsletter's custom sending domain. While `is_checking` is true, a background re-verification is in flight; poll until it flips to false. Pass `force=true` to trigger a re-check.

## Path parameters

- `id` string, required

## Query parameters

- `force` boolean — When true, trigger a fresh DNS re-verification instead of serving the last-known record.

## Response `200`

OK

- SendingDomainRecord
  - `id` string, required — The ESP-side identifier for the domain, when available.
  - `domain` string, required — The custom sending domain being verified.
  - `status` 'none' | 'invalid' | 'awaiting_ssl' | 'failing' | 'deliberately_cold' | 'valid', required — The DNS verification status of a newsletter's custom sending domain.
  - `warnings` unknown[], required — Human-readable warnings about the domain's DNS setup (e.g. a record left proxied through Cloudflare).
    - unknown
  - `requirements` RequirementRecord[], required — The DNS records required for the domain, each with its current verification state.
    - `record_type` string, required — The DNS record type to create (e.g. `CNAME`, `TXT`, `MX`).
    - `name` string, required — The host/name the DNS record should be created at.
    - `is_valid` boolean, required — Whether the record is currently present and correct in DNS.
    - `required_value` string, required — The value the DNS record must point to.
    - `current_values` string[], required — The values currently observed at this record, if any.
    - `context` 'managed' | 'manual', required — `manual` if the customer must create this record themselves; `managed` if Buttondown provisions it.
  - `existing_mail_provider` string, nullable — The third-party mail provider already handling this domain's inbound mail, when detected; its MX record is then omitted from `requirements`.
  - `detected_dns_provider` ApexAliasProvider
    - `id` string, required — Stable identifier for the DNS provider (e.g. `cloudflare`).
    - `name` string, required — Human-readable name of the DNS provider.
    - `apex_alias_support` string, required — How the provider supports pointing an apex/root domain at a CNAME target (e.g. CNAME flattening or ALIAS records).
    - `wording_kind` string, required — Which copy variant to show for this provider's setup instructions.
    - `nameserver_regexes` string[], required — Patterns matched against a domain's nameservers to detect this provider.
    - `support_doc_url` string, nullable, required — Link to the provider's own DNS documentation, when available.
    - `side_notes` string, required — Provider-specific caveats to surface alongside the setup guidance.
    - `buttondown_guide_url` string, nullable — A first-party Buttondown setup guide for this provider, when one exists.
    - `supports_nameserver_delegation` boolean — Whether the provider lets customers delegate a child zone with NS records.
  - `checked_date` string, date-time, nullable — When the record was last computed. Null until the first verification completes.
  - `is_checking` boolean — Whether a background re-verification is currently in flight. Clients poll while this is true.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `429` — Too Many Requests

---

[API](https://skmtc.net/buttondown/apis/buttondown-api.md) · [All operations](https://skmtc.net/buttondown/apis/buttondown-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/buttondown/buttondown-api/revisions/06b741c56b33/schema)