List sending domains

GET

/v1/email/domains

curl -X GET "https://us1.platform.bird.com/v1/email/domains" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "sort=created_at" \
  --url-query "order=desc" \
  --url-query "limit=25" \
  --url-query "include_total=false"

Returns all sending domains for the current workspace, ordered by creation date descending.

Parametry zapytania

name

string

Substring match against the domain name (case-insensitive).

sort

string

Field to sort by.

order

string

Sort direction. Defaults to desc (newest/largest first).

limit

integer

Maximum number of items to return per page.

starting_after

string

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_before

string

Cursor from the prev_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order.

include_total

boolean

When true, the response includes a total field with the total number of items matching the request's filters across all pages.

Treść odpowiedzi

data

array of object

wymagane

Pokaż atrybuty podrzędne

data.id

string

wymagane

data.workspace_id

string

wymagane

data.domain

string

wymagane

The sending domain name. Set at creation and immutable.

data.vendor

string

wymagane

The DNS provider hosting this domain's nameservers, so you know which provider's dashboard to manage the required DNS records in. Returns "other" when the provider has not been detected or is not recognized.

data.status

string

wymagane

Domain ownership verification, proven by the DKIM record. Readiness to send or track is reported separately per capability under capabilities.*.status.

pending — the DKIM record has not been published yet. - verified — the DKIM record is in place; ownership is confirmed. - failed — a DKIM record exists but does not match the expected value (for example a stale record from an earlier setup), or a previously verified record was removed. Correct the record to recover.
temporary_failure — DNS resolution failed transiently (timeout, unreachable nameserver). Verification is queued for retry on a 72h cadence; customer should not edit DNS records before the retry runs.
rejected — the domain was refused for policy reasons and cannot be used for sending. Contact support if you believe this is an error.

data.settings

object

wymagane

Per-domain behavior toggles. Changes apply immediately to new sends.

Pokaż atrybuty podrzędne

data.settings.click_tracking

boolean

Rewrite links in HTML email through your tracking domain to record clicks. You can enable this before your tracking domain has verified — it begins working once verification completes. A tracking domain must be configured; enabling it without one returns 409.

data.settings.open_tracking

boolean

Insert a tracking pixel in HTML email to record opens. You can enable this before your tracking domain has verified — it begins working once verification completes. A tracking domain must be configured; enabling it without one returns 409.

data.dkim

object

wymagane

Active DKIM signing configuration for the domain.

Pokaż atrybuty podrzędne

data.dkim.mode

string

wymagane

How the DKIM public key is published in your DNS. txt — you publish the key as a TXT record. delegated — you publish a single CNAME and Bird hosts and rotates the key.

data.dkim.selector

string

wymagane

DKIM selector used to sign mail from this domain.

data.dkim.key_size

integer

wymagane

RSA key size in bits.

data.capabilities

object

wymagane

Pokaż atrybuty podrzędne

data.capabilities.sending

object

wymagane

Pokaż atrybuty podrzędne

data.capabilities.sending.status

string

wymagane

Capability verification status.

pending — verification has not run, or is currently running. - verified — all DNS records for this capability resolved with the expected values.
warning — a record for this capability verified before and a recent check no longer matches, but it is still within the grace period. Sending is not yet affected; fix it before the grace period ends.
failed — DNS records resolved but at least one value is wrong. Update your DNS to recover.
temporary_failure — DNS lookup failed transiently. Verification is queued for retry; don't change DNS records yet.
not_configured — the capability is not set up on this domain (e.g. no tracking domain configured).

data.capabilities.sending.domain

nullable string

Hostname this capability is configured with — the return-path domain, the tracking domain, or the domain where the DMARC policy was found. Null when not applicable or not configured.

data.capabilities.sending.pending

object

A staged configuration change awaiting DNS verification. The currently active configuration keeps serving until the staged one verifies, at which point it is promoted automatically. Submitting another change for the same capability replaces the staged value.

Pokaż atrybuty podrzędne

data.capabilities.sending.pending.domain

string

wymagane

Hostname the capability will use once the staged change verifies.

data.capabilities.sending.pending.status

string

wymagane

Verification status of the staged change. pending — waiting for the DNS records to be detected. failed — the records resolved with wrong values; correct them or submit a different change. temporary_failure — DNS lookup failed transiently and will be retried.

data.capabilities.sending.reason

nullable string

Machine-readable reason code for a failed capability status. Only set when status is failed. Use this to display a specific message to users rather than a generic failure message.

tracking_domain_in_use — the link tracking subdomain is already claimed by another organization.

data.capabilities.return_path

object

wymagane

Pokaż atrybuty podrzędne

data.capabilities.return_path.status

string

wymagane

Capability verification status.

pending — verification has not run, or is currently running. - verified — all DNS records for this capability resolved with the expected values.
warning — a record for this capability verified before and a recent check no longer matches, but it is still within the grace period. Sending is not yet affected; fix it before the grace period ends.
failed — DNS records resolved but at least one value is wrong. Update your DNS to recover.
temporary_failure — DNS lookup failed transiently. Verification is queued for retry; don't change DNS records yet.
not_configured — the capability is not set up on this domain (e.g. no tracking domain configured).

data.capabilities.return_path.domain

nullable string

Hostname this capability is configured with — the return-path domain, the tracking domain, or the domain where the DMARC policy was found. Null when not applicable or not configured.

data.capabilities.return_path.pending

object

Pokaż atrybuty podrzędne

data.capabilities.return_path.pending.domain

string

wymagane

Hostname the capability will use once the staged change verifies.

data.capabilities.return_path.pending.status

string

wymagane

data.capabilities.return_path.reason

nullable string

Machine-readable reason code for a failed capability status. Only set when status is failed. Use this to display a specific message to users rather than a generic failure message.

tracking_domain_in_use — the link tracking subdomain is already claimed by another organization.

data.capabilities.dmarc

object

wymagane

Pokaż atrybuty podrzędne

data.capabilities.dmarc.status

string

wymagane

Capability verification status.

pending — verification has not run, or is currently running. - verified — all DNS records for this capability resolved with the expected values.
warning — a record for this capability verified before and a recent check no longer matches, but it is still within the grace period. Sending is not yet affected; fix it before the grace period ends.
failed — DNS records resolved but at least one value is wrong. Update your DNS to recover.
temporary_failure — DNS lookup failed transiently. Verification is queued for retry; don't change DNS records yet.
not_configured — the capability is not set up on this domain (e.g. no tracking domain configured).

data.capabilities.dmarc.domain

nullable string

Hostname this capability is configured with — the return-path domain, the tracking domain, or the domain where the DMARC policy was found. Null when not applicable or not configured.

data.capabilities.dmarc.pending

object

Pokaż atrybuty podrzędne

data.capabilities.dmarc.pending.domain

string

wymagane

Hostname the capability will use once the staged change verifies.

data.capabilities.dmarc.pending.status

string

wymagane

data.capabilities.dmarc.reason

nullable string

Machine-readable reason code for a failed capability status. Only set when status is failed. Use this to display a specific message to users rather than a generic failure message.

tracking_domain_in_use — the link tracking subdomain is already claimed by another organization.

data.capabilities.tracking

object

wymagane

Pokaż atrybuty podrzędne

data.capabilities.tracking.status

string

wymagane

Capability verification status.

pending — verification has not run, or is currently running. - verified — all DNS records for this capability resolved with the expected values.
warning — a record for this capability verified before and a recent check no longer matches, but it is still within the grace period. Sending is not yet affected; fix it before the grace period ends.
failed — DNS records resolved but at least one value is wrong. Update your DNS to recover.
temporary_failure — DNS lookup failed transiently. Verification is queued for retry; don't change DNS records yet.
not_configured — the capability is not set up on this domain (e.g. no tracking domain configured).

data.capabilities.tracking.domain

nullable string

Hostname this capability is configured with — the return-path domain, the tracking domain, or the domain where the DMARC policy was found. Null when not applicable or not configured.

data.capabilities.tracking.pending

object

Pokaż atrybuty podrzędne

data.capabilities.tracking.pending.domain

string

wymagane

Hostname the capability will use once the staged change verifies.

data.capabilities.tracking.pending.status

string

wymagane

data.capabilities.tracking.reason

nullable string

Machine-readable reason code for a failed capability status. Only set when status is failed. Use this to display a specific message to users rather than a generic failure message.

tracking_domain_in_use — the link tracking subdomain is already claimed by another organization.

data.capabilities.inbound

object

Pokaż atrybuty podrzędne

data.capabilities.inbound.status

string

wymagane

Capability verification status.

pending — verification has not run, or is currently running. - verified — all DNS records for this capability resolved with the expected values.
warning — a record for this capability verified before and a recent check no longer matches, but it is still within the grace period. Sending is not yet affected; fix it before the grace period ends.
failed — DNS records resolved but at least one value is wrong. Update your DNS to recover.
temporary_failure — DNS lookup failed transiently. Verification is queued for retry; don't change DNS records yet.
not_configured — the capability is not set up on this domain (e.g. no tracking domain configured).

data.capabilities.inbound.domain

nullable string

Hostname this capability is configured with — the return-path domain, the tracking domain, or the domain where the DMARC policy was found. Null when not applicable or not configured.

data.capabilities.inbound.pending

object

Pokaż atrybuty podrzędne

data.capabilities.inbound.pending.domain

string

wymagane

Hostname the capability will use once the staged change verifies.

data.capabilities.inbound.pending.status

string

wymagane

data.capabilities.inbound.reason

nullable string

Machine-readable reason code for a failed capability status. Only set when status is failed. Use this to display a specific message to users rather than a generic failure message.

tracking_domain_in_use — the link tracking subdomain is already claimed by another organization.

data.dns_records

array of object

wymagane

The domain's DNS records and their individual verification state, returned in full on both the list and single-domain responses. This is the complete set to publish across DKIM, return-path, DMARC, tracking, and inbound; records for a staged change carry state: pending. Inbound MX records are always included as a regional reference, even while receiving is off (capabilities.inbound.status is not_configured) — their presence alone does not mean receiving is enabled (see DomainUpdate.inbound).

Pokaż atrybuty podrzędne

data.dns_records.type

string

wymagane

data.dns_records.name

string

wymagane

The record name — the part you enter in your DNS provider's "Name" or "Host" field, relative to the DNS zone the record belongs in (your registered domain). For a sending domain mail.acme.com the DKIM record name is bird1._domainkey.mail, entered in the acme.com zone. @ for records at the zone apex.

data.dns_records.host

string

wymagane

The fully qualified hostname for this record (e.g. bird1._domainkey.mail.acme.com).

data.dns_records.value

string

wymagane

data.dns_records.purpose

string

wymagane

What this record is for.

dkim — signs outbound mail and proves domain ownership. - return_path — return-path (bounce) CNAME for sending. - tracking — branded open/click tracking CNAME (optional). - dmarc — advisory DMARC policy record. - inbound_mx — MX record routing mail to Bird for receiving. Always present wherever inbound is available, as a regional reference, regardless of whether receiving is enabled; publishing it does not enable receiving on its own — see DomainUpdate.inbound.

data.dns_records.state

string

wymagane

Lifecycle state of this record.

active — the record backs the domain's current configuration. - pending — the record belongs to a staged configuration change; publish it to complete the change.
deprecated — the record belonged to a previous configuration. Keep it in DNS until safe_to_remove is true; in-flight mail and previously sent tracked links may still resolve through it.

data.dns_records.optional

boolean

wymagane

Whether this record can be skipped. Optional records enable extra functionality (e.g. tracking) but are not required for sending.

data.dns_records.status

string

wymagane

Verification status of this record's most recent DNS check.

pending — the record has not verified yet; publish it (or correct it) and it will verify on the next check.
verified — the most recent check matched the expected value. - warning — the record verified before and a recent check no longer matched, but it is still within the grace period. Sending is not yet affected; fix the record before the grace period ends to avoid it being blocked.
failed — the record verified before but later checks kept failing past the grace period; the configuration has regressed and needs attention.

data.dns_records.error

nullable string

Human-readable detail for a failed check on this record — what was found in DNS and why it did not match. Null when the record is verified or not yet checked.

data.dns_records.safe_to_remove

nullable boolean

Only set on deprecated records: true once the record is no longer referenced by in-flight mail or live tracked links and can be deleted from your DNS. Null on active and pending records.

data.last_checked_at

nullable string

When Bird last checked this domain's DNS records, whether or not the outcome changed. Updated on every verification — your manual refresh and the periodic automatic re-checks alike. Null if the domain has never been checked.

data.verified_at

nullable string

When the domain's ownership was confirmed — the moment status became verified via the DKIM record. Unchanged by later re-checks while it stays verified. Null if the domain has never been verified.

data.created_at

string

wymagane

When the domain was added.

data.updated_at

string

wymagane

When the domain's configuration was last changed (such as a settings or return-path change). Verification re-checks do not change this; see last_checked_at and verified_at for verification timing.

next_cursor

nullable string

wymagane

Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.

prev_cursor

nullable string

wymagane

Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.

refresh_cursor

nullable string

wymagane

Refresh anchor. Pass back as ending_before later to fetch items that have appeared since this response. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

total

nullable integer

Total number of items matching the request's filters across all pages. Present only when include_total=true was passed; otherwise null.

curl -X GET "https://us1.platform.bird.com/v1/email/domains" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "sort=created_at" \
  --url-query "order=desc" \
  --url-query "limit=25" \
  --url-query "include_total=false"