Documentation
Sign inGet started
शुरू करें
गाइड
API Reference
SDKs
CLI
Knowledge Base
Changelog

Create a sending domain

POST
/v1/email/domains
const domain = await bird.domains.create({ domain: "mail.acme.com" });
console.log(domain.id, domain.status); // "dom_…", "pending"
Response201
{
  "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"
    }
  ]
}
Registers a new sending domain and returns the DNS records to publish for it. The DKIM TXT record proves ownership, and together with the return-path CNAME (which also covers SPF, so no separate SPF record is needed) and a DMARC policy it gates sending. The tracking CNAME is optional and gates branded link tracking only. Publish the records at your DNS provider, then check progress with Trigger domain verification. Published records are also re-checked for you automatically. Setup walkthrough: Sending domains.
The domain starts in pending status. A domain already registered in this workspace returns 409, and creation beyond your organization's domain quota returns 422 E10000. A domain that never verifies ownership is removed after about 14 days, with a reminder email first.
Request Payload
domain
string
आवश्यक
The domain you send from: the domain of your from addresses. Use a dedicated subdomain (for example, mail.acme.com) rather than your registered domain so sending reputation stays separate from other services on the domain.
return_path
object
Return-path (bounce) domain configuration. The return-path domain receives bounce and complaint notifications for mail sent from this domain and is what mailbox providers check for SPF. Provide only the name part; we add the sending domain automatically.
चाइल्ड पैरामीटर दिखाएँ
return_path.name
string
आवश्यक
Name part to use for the return-path domain. For example, send on mail.acme.com becomes send.mail.acme.com. Defaults to send when omitted at creation.
tracking
object
Tracking domain configuration for branded open and click tracking URLs. Provide only the name part; we add the sending domain automatically. A domain created with no tracking configuration defaults to links. Tracked links are served over HTTPS after the tracking record verifies.
चाइल्ड पैरामीटर दिखाएँ
tracking.name
string
आवश्यक
Name part to use for branded open and click tracking URLs. For example, links on mail.acme.com becomes links.mail.acme.com.
dkim
object
DKIM signing configuration.
चाइल्ड पैरामीटर दिखाएँ
dkim.mode
string
How the DKIM public key is published in your DNS.
  • txt (default): you publish the DKIM public key as a TXT record. Key rotation requires updating the record.
  • delegated: you publish a CNAME that points to a DKIM key we host and rotate. This mode is unavailable for new configurations; supplying it returns 422.
Possible values: txt, delegated
settings
object
Per-domain behavior toggles. Changes apply immediately to new sends.
चाइल्ड पैरामीटर दिखाएँ
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.
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.
Response Payload
id
string
आवश्यक
workspace_id
string
आवश्यक
domain
string
आवश्यक
The sending domain name. Set at creation and immutable.
vendor
string
आवश्यक
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
आवश्यक
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
आवश्यक
Per-domain behavior toggles. Changes apply immediately to new sends.
चाइल्ड एट्रिब्यूट दिखाएँ
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.
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.
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.
चाइल्ड एट्रिब्यूट दिखाएँ
next.kind
string
आवश्यक
What you do about this step.
  • operation: call the operation named in operation, then read again.
  • external: act somewhere this API does not reach, then read again.
  • wait: nothing is asked of you, so read again later.
  • terminal: nothing you do resolves this, so stop retrying.
Tolerate a value you do not recognize: show the description and offer no action.
Possible values (may grow over time): operation, external, wait, terminal
next.description
string
आवश्यक
A short, human-readable label for the step, suitable for display.
next.operation
string
The operationId to call. Present only when kind is operation. The operation's own schema says how to call it; this says only which one, and what to address it with.
next.params
object
The parameters that address the operation, by name: {"sender_id": "…"} for an operation on /v1/sms/senders/{sender_id}/requirements. A parameter the operation takes in its query string is given the same way, so an operation addressed as ?subject_id= carries {"subject_id": "…"}. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when kind is operation and the operation names a subject. A request body, when the operation takes one, is described by the operation's own schema and never appears here.
next.url
string
A URL to open. Present only when kind is external, and only when the step has one. An external step whose description says to go and do something with no URL to open is normal.
dkim
object
आवश्यक
Active DKIM signing configuration for the domain.
चाइल्ड एट्रिब्यूट दिखाएँ
dkim.mode
string
आवश्यक
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 we host and rotate the key.
Possible values: txt, delegated
dkim.selector
string
आवश्यक
DKIM selector used to sign mail from this domain.
dkim.key_size
integer
आवश्यक
RSA key size in bits.
capabilities
object
आवश्यक
चाइल्ड एट्रिब्यूट दिखाएँ
capabilities.sending
object
आवश्यक
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.
चाइल्ड एट्रिब्यूट दिखाएँ
capabilities.sending.status
string
आवश्यक
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.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.
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.
चाइल्ड एट्रिब्यूट दिखाएँ
capabilities.sending.pending.domain
string
आवश्यक
Hostname the capability uses after the staged change verifies.
capabilities.sending.pending.status
string
आवश्यक
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.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.
capabilities.return_path
object
आवश्यक
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.
चाइल्ड एट्रिब्यूट दिखाएँ
capabilities.return_path.status
string
आवश्यक
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.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.
capabilities.return_path.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.
चाइल्ड एट्रिब्यूट दिखाएँ
capabilities.return_path.pending.domain
string
आवश्यक
Hostname the capability uses after the staged change verifies.
capabilities.return_path.pending.status
string
आवश्यक
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.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.
capabilities.dmarc
object
आवश्यक
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.
चाइल्ड एट्रिब्यूट दिखाएँ
capabilities.dmarc.status
string
आवश्यक
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.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.
capabilities.dmarc.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.
चाइल्ड एट्रिब्यूट दिखाएँ
capabilities.dmarc.pending.domain
string
आवश्यक
Hostname the capability uses after the staged change verifies.
capabilities.dmarc.pending.status
string
आवश्यक
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.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.
capabilities.tracking
object
आवश्यक
Branded open/click tracking domain. not_configured until a tracking domain is set. Tracked links are served over HTTPS once the CNAME verifies.
चाइल्ड एट्रिब्यूट दिखाएँ
capabilities.tracking.status
string
आवश्यक
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.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.
capabilities.tracking.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.
चाइल्ड एट्रिब्यूट दिखाएँ
capabilities.tracking.pending.domain
string
आवश्यक
Hostname the capability uses after the staged change verifies.
capabilities.tracking.pending.status
string
आवश्यक
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.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.
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.
चाइल्ड एट्रिब्यूट दिखाएँ
capabilities.inbound.status
string
आवश्यक
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.
चाइल्ड एट्रिब्यूट दिखाएँ
capabilities.inbound.pending.domain
string
आवश्यक
Hostname the capability uses after the staged change verifies.
capabilities.inbound.pending.status
string
आवश्यक
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
आवश्यक
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.
चाइल्ड एट्रिब्यूट दिखाएँ
dns_records.type
string
आवश्यक
The DNS record type to publish, determined by purpose.
  • TXT: used for the dkim and dmarc purposes.
  • CNAME: used for the return_path and tracking purposes.
  • MX: used for the inbound_mx purpose.
Possible values: TXT, CNAME, MX
dns_records.name
string
आवश्यक
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.
dns_records.host
string
आवश्यक
The fully qualified hostname for this record (for example, bird1._domainkey.mail.acme.com).
dns_records.value
string
आवश्यक
The value to publish, as entered in your DNS provider's Value or Content field. For TXT, enter the full record content. For CNAME, enter the target hostname. For MX, enter the priority followed by the mail server hostname.
dns_records.purpose
string
आवश्यक
What this record is for.
  • dkim: signs outbound mail and proves domain ownership.
  • return_path: identifies the return-path (bounce) CNAME for sending.
  • tracking: identifies the optional branded open/click tracking CNAME.
  • inbound_mx: identifies the MX record routing mail to us 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. It is optional until receiving is enabled, and publishing it before then is destructive: on a domain at the zone apex it replaces the MX records that carry the domain's existing mail.
  • dmarc: identifies the advisory DMARC policy record.
Possible values: dkim, return_path, tracking, inbound_mx, dmarc
dns_records.state
string
आवश्यक
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.
Possible values: active, pending, deprecated
dns_records.optional
boolean
आवश्यक
Whether this record can be skipped. An optional record enables extra functionality (branded tracking, or receiving) rather than sending, so publish one only when you want what it enables. The inbound_mx records are optional until you enable receiving on the domain, and publishing one before then changes where mail to the domain is delivered.
dns_records.status
string
आवश्यक
Verification status of this record's most recent DNS check.
  • pending: the record has not verified yet; publish it (or correct it) and it verifies 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.
Possible values: pending, verified, warning, failed
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.
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.
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
आवश्यक
When the domain was added.
updated_at
string
आवश्यक
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.