Create a sending domain
/v1/email/domainsconst domain = await bird.domains.create({ domain: "mail.acme.com" });
console.log(domain.id, domain.status); // "dom_…", "pending"domain = client.domains.create(domain="mail.acme.com")
print(domain.id, domain.status)domain, err := client.Domains.Create(context.Background(), bird.DomainCreateParams{
Domain: "mail.acme.com",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(domain.Id, *domain.Status)$domain = $bird->domains->create(
(new DomainCreate())->setDomain('mail.acme.com'),
);
echo $domain->getId(), ' ', $domain->getStatus(); // "dom_…", "pending"bird email domains create mail.acme.comcurl -X POST "https://us1.platform.bird.com/v1/email/domains" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"domain": "mail.acme.com"
}'{
"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.
Anfrage-Nutzlast
domainThe 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_pathReturn-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.
trackingTracking 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.
dkimDKIM signing configuration.
Untergeordnete Parameter anzeigen
dkim.modeHow 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 returns422.
Possible values: txt, delegated
settingsPer-domain behavior toggles. Changes apply immediately to new sends.
Antwort-Payload
idworkspace_iddomainThe sending domain name. Set at creation and immutable.
vendorThe 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
statusDomain 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
settingsPer-domain behavior toggles. Changes apply immediately to new sends.
nextWhat 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.
dkimActive DKIM signing configuration for the domain.
capabilitiesdns_recordsThe 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.
last_checked_atWhen 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_atWhen 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_atWhen the domain was added.
updated_atWhen 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.
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.