domains

Get a sending domain

Returns the domain with its capability statuses and every DNS record's current verification state. This read reports the stored result of the last check. To run a fresh DNS check, use Trigger domain verification.

get/v1/email/domains/{domain_id}

Request

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

Path parameters

domain_idstring required
Example:dom_01krdgeqcxet5s7t44vh8rt9mg

ID of the domain to fetch.

Headers

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

The sending domain.

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 2 revisions of this API.