domains

Verify a domain

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.

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

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/email/domains/{domain_id}/verify
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

domain_idstring required
Example:dom_01krdgeqcxet5s7t44vh8rt9mg

ID of the domain to verify.

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

Verification result.

idstring required
workspace_idstring required
domainstring required

The sending domain name. Set at creation and immutable.

vendor'other' | 'cloudflare' | 'route53' | 'godaddy' | 'namecheap' | 'google' | 'azure' | 'digitalocean' | 'squarespace' required

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.

status'pending' | 'verified' | 'failed' | 'temporary_failure' | 'rejected' required

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.
last_checked_atstring date-time nullable

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_atstring date-time nullable

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_atstring date-time required

When the domain was added.

updated_atstring date-time required

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.

Example response

{
  "id": "dom_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "domain": "mail.acme.com",
  "dkim": {
    "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"
      }
    }
  }
}

Changes

No recorded changes to this operation across all 3 revisions of this API.