Verify a domain

POST

/v1/email/domains/{domain_id}/verify

const domain = await bird.domains.verify("dom_01krdgeqcxet5s7t44vh8rt9mg");
console.log(domain.status); // "verified" once DNS is in place

domain = client.domains.verify("dom_01krdgeqcxet5s7t44vh8rt9mg")
print(domain.status)

domain, err := client.Domains.Verify(context.Background(), "dom_123")
if err != nil {
	log.Fatal(err)
}
fmt.Println(*domain.Status)

$domain = $bird->domains->verify('dom_01krdgeqcxet5s7t44vh8rt9mg');
echo $domain->getStatus(); // "verified" once DNS is in place

bird email domains verify <domain-id>

curl -X POST "https://us1.platform.bird.com/v1/email/domains/{domain_id}/verify" \
  -H "Authorization: Bearer $TOKEN"

Antwort200

{
  "id": "dom_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "domain": "mail.acme.com",
  "vendor": "other",
  "status": "pending",
  "next": [
    {
      "kind": "operation"
    }
  ],
  "dkim": {
    "mode": "txt",
    "selector": "bird1",
    "key_size": 2048
  },
  "capabilities": {
    "sending": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    },
    "return_path": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    },
    "dmarc": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    },
    "tracking": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    },
    "inbound": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    }
  },
  "dns_records": [
    {
      "type": "TXT",
      "purpose": "dkim",
      "state": "active",
      "status": "pending"
    }
  ]
}

Runs a fresh DNS check across the domain's records (DKIM, return path, DMARC, tracking, inbound MX, and any staged changes) and returns the updated domain. Use it for an immediate result after publishing or correcting records. Get a sending domain only reports the last stored result. Published records are also re-checked for you automatically in the background.

A 200 with records still pending is not a failure: the records were not found yet, which is normal while DNS propagates (minutes to hours). Recently verified records are not re-queried, so the call is safe to repeat while you wait.

Parameter

domain_idstring

ID of the domain to verify.

Antwort-Payload

id

string

erforderlich

workspace_id

string

erforderlich

domain

string

erforderlich

The sending domain name. Set at creation and immutable.

vendor

string

erforderlich

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.

Possible values: other, cloudflare, route53, godaddy, namecheap, google, azure, digitalocean, squarespace

status

string

erforderlich

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, such as from a timeout or unreachable nameserver. Verification retries automatically; do not change the DNS records unless they are incorrect.
rejected: the domain was refused for policy reasons and cannot be used for sending. Contact support if you believe this is an error.

Possible values: pending, verified, failed, temporary_failure, rejected

settings

object

erforderlich

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

Untergeordnete Attribute anzeigen

next

array of object

What to do next about this domain, given the state it is in. Each entry names one action and says why it is worth taking, so you can act on this response without working out the order yourself. Present on reads that compute it: an empty list means there is nothing to do, and the field is absent entirely on responses that do not report next actions.

This answers whether you own the domain, which is what status reports. What each capability still needs before it can send or receive is reported separately under capabilities, so an empty list here does not on its own mean the domain is ready.

Untergeordnete Attribute anzeigen

dkim

object

erforderlich

Active DKIM signing configuration for the domain.

Untergeordnete Attribute anzeigen

capabilities

object

erforderlich

Untergeordnete Attribute anzeigen

capabilities.sending

object

erforderlich

Overall authorization to send from this domain. Verified when the DKIM record, the return-path CNAME, and a DMARC policy are all in place. Required for live sends.

Untergeordnete Attribute anzeigen

capabilities.return_path

object

erforderlich

Return-path (bounce) CNAME verification. The return-path domain receives bounce and complaint notifications and is what mailbox providers check for SPF: no separate SPF record is needed.

Untergeordnete Attribute anzeigen

capabilities.dmarc

object

erforderlich

DMARC policy check. Satisfied by any valid DMARC record covering the sending domain: on the domain itself or on its registered (organizational) domain; domain reports where the policy was found. A minimal policy of p=none is sufficient.

Untergeordnete Attribute anzeigen

capabilities.tracking

object

erforderlich

Branded open/click tracking domain. not_configured until a tracking domain is set. Tracked links are served over HTTPS once the CNAME verifies.

Untergeordnete Attribute anzeigen

capabilities.inbound

object

Inbound mail receiving. not_configured until receiving is enabled on this domain (see DomainUpdate.inbound), then pending while the published MX records are checked, and verified once they resolve to us. The MX records to publish are always listed under dns_records (purpose: inbound_mx) as a regional reference, even while this is not_configured: enabling is what actually starts delivery.

Untergeordnete Attribute anzeigen

capabilities.inbound.status

string

erforderlich

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 retries automatically; do not change DNS records unless they are incorrect.
not_configured: the capability is not set up on this domain (for example, no tracking domain configured).

Possible values: pending, verified, warning, failed, temporary_failure, not_configured

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.

capabilities.inbound.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.

Untergeordnete Attribute anzeigen

capabilities.inbound.pending.domain

string

erforderlich

Hostname the capability uses after the staged change verifies.

capabilities.inbound.pending.status

string

erforderlich

Verification status of the staged change.

pending: the DNS records have not been detected yet.
failed: the records resolved with wrong values; correct them or submit a different change.
temporary_failure: the DNS lookup failed transiently and is queued for retry.

Possible values: pending, failed, temporary_failure

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.

dns_records

array of object

erforderlich

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 and capabilities.inbound.status is not_configured. Their presence alone does not mean receiving is enabled; see DomainUpdate.inbound.

Untergeordnete Attribute anzeigen

last_checked_at

nullable string

When we 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.

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.

created_at

string

erforderlich

When the domain was added.

updated_at

string

erforderlich

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.

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Implementierungs-Briefing erhalten

const domain = await bird.domains.verify("dom_01krdgeqcxet5s7t44vh8rt9mg");
console.log(domain.status); // "verified" once DNS is in place

domain = client.domains.verify("dom_01krdgeqcxet5s7t44vh8rt9mg")
print(domain.status)

domain, err := client.Domains.Verify(context.Background(), "dom_123")
if err != nil {
	log.Fatal(err)
}
fmt.Println(*domain.Status)

$domain = $bird->domains->verify('dom_01krdgeqcxet5s7t44vh8rt9mg');
echo $domain->getStatus(); // "verified" once DNS is in place

bird email domains verify <domain-id>

curl -X POST "https://us1.platform.bird.com/v1/email/domains/{domain_id}/verify" \
  -H "Authorization: Bearer $TOKEN"

Antwort200

{
  "id": "dom_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "domain": "mail.acme.com",
  "vendor": "other",
  "status": "pending",
  "next": [
    {
      "kind": "operation"
    }
  ],
  "dkim": {
    "mode": "txt",
    "selector": "bird1",
    "key_size": 2048
  },
  "capabilities": {
    "sending": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    },
    "return_path": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    },
    "dmarc": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    },
    "tracking": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    },
    "inbound": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    }
  },
  "dns_records": [
    {
      "type": "TXT",
      "purpose": "dkim",
      "state": "active",
      "status": "pending"
    }
  ]
}

Verify a domain

Parameter

Antwort-Payload

Verwandte Ressourcen