Verzenddomeinen
Voordat we e-mail vanaf je domein kunnen afleveren, moet je bewijzen dat je het bezit en de DNS-records publiceren waarmee mailboxproviders je e-mail kunnen authenticeren. Een verzenddomein is de werkruimtegebonden resource (dom_...) die die configuratie bijhoudt: welke records je moet publiceren, wat geverifieerd is en of het domein klaar is om te verzenden.
Een domein delen tussen organisaties
Hetzelfde domein kan door meer dan één organisatie worden geregistreerd zonder dat iemand een ander in de weg zit. Elke organisatie bewijst eigendom met zijn eigen DKIM-sleutel, dus:
- Een andere organisatie op hetzelfde domein kan je verificatiestatus nooit inzien of je configuratie wijzigen.
- Elke regio (us1, eu1) is onafhankelijk: hetzelfde domein in twee regio's zijn twee aparte registraties met eigen DNS-records. Registreer het in elke regio van waaruit je verzendt.
Een domein registreren
Maak het domein aan met POST /v1/email/domains. De aanroep is werkruimtegebonden en verwacht het verzenddomein plus optionele labels voor de return-path- en trackinghostnamen. Geef alleen het label door (send, links), en wij stellen de volledige hostnaam samen onder je verzenddomein. Weggelaten waarden krijgen standaard send en links.
Gebruik een specifiek subdomein (mail.acme.com) in plaats van je geregistreerde domein. Dat houdt je verzendreputatie gescheiden van al het andere op het domein, en het houdt alle records die we je vragen te publiceren weg van je zone-apex. Die tweede reden is degene die problemen veroorzaakt: het MX-record voor ontvangst staat op dezelfde naam als de MX-records die al de e-mail van je bedrijf verwerken, dus op een apex-verzenddomein stuurt het publiceren ervan die e-mail naar ons door.
const 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.com{
"name": "email_domains_create",
"arguments": {
"domain": "mail.acme.com"
}
}curl -s https://eu1.platform.bird.com/v1/email/domains \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domain": "mail.acme.com",
"return_path": { "name": "send" },
"tracking": { "name": "links" }
}'Het antwoord bevat status: pending, de DKIM-selector die aan je organisatie is toegewezen, en de dns_records om te publiceren. Een bestaande werkruimteregistratie retourneert 409. Overschrijding van het domeinquotum van je organisatie retourneert 422. Vervang eu1 door us1 voor een US-werkruimte. API-sleutels gebruiken dezelfde regionale prefixen: bk_eu1_... en bk_us1_.... Je kunt domeinen ook beheren in Email > Domains.

De DNS-records publiceren
De dns_records-array geeft je kopieerbare name, host en value voor elk record. Sommige providers weigeren een lange DKIM TXT-waarde als enkele tekenreeks; de DNS record splitter splitst deze in de aanhalingsteken-tekenreeksen die die providers verwachten. Wat je publiceert:
| Record | Type | Vereist voor verzending | Wat het doet |
|---|---|---|---|
| DKIM | TXT | Ja | Bewijst eigendom en ondertekent je e-mail met de sleutel van je organisatie |
| Return-path CNAME | CNAME | Ja | Routeert bounces terug naar ons en dekt SPF; de SPF-lookup volgt de CNAME, dus er is geen SPF-record op je domain-apex nodig |
| DMARC | TXT | Ja | Elk geldig v=DMARC1-beleid dat het verzenddomein dekt, op het domein zelf of op het geregistreerde (organisatie)domein. Een minimaal p=none-beleid is voldoende. |
| Tracking CNAME | CNAME | Nee | Maakt branded open/click-trackinghostnamen mogelijk; getrackte links worden via HTTPS aangeboden zodra het verifieert |
| Inbound MX | MX | Nee | Routeert e-mail voor het domein naar ons voor ontvangst. Draagt optional: true totdat je ontvangst inschakelt; het publiceren ervan vervangt de MX-records die het domein nu gebruikt. |
Zie DKIM, SPF en DMARC voor het doel en de waarden van elk record. De ontvangende MX-records staan in dns_records met purpose: inbound_mx wanneer ontvangst beschikbaar is in je regio, en ze dragen optional: true totdat je ontvangst inschakelt op het domein. Sla elk record met het label optional over, tenzij je wilt wat het mogelijk maakt. Zie voor DNS-providerconfiguratiesstappen de handleidingen voor Cloudflare, Route 53 of generieke registrar.
Het dashboard detecteert ondersteunde DNS-providers op basis van de nameservers van je domein en linkt naar hun DNS-instellingen. Open Email > Domains en selecteer een domein om de records te bekijken. Als iemand anders je DNS beheert, stuurt POST /v1/email/domains/{domain_id}/dns-records/share hen een e-mail met de te publiceren records.

Verificatiecyclus
Een nieuw domein begint als pending. Je hoeft nooit te pollen, want we controleren je records automatisch. Controles starten direct bij registratie en lopen terug van elke paar minuten naar elk uur gedurende de eerste drie dagen. Daarna worden ze dagelijks uitgevoerd voor elk actief domein. Je records publiceren en wachten is voldoende; de meeste domeinen verifiëren binnen enkele minuten na DNS-propagatie. Wil je een directe controle (bijvoorbeeld vlak na het bewerken van DNS), roep dan POST /v1/email/domains/{domain_id}/verify aan: het voert een nieuwe controle uit en retourneert het bijgewerkte domein. Een 200 met records die nog pending zijn, is geen fout; het betekent dat de records nog niet gevonden zijn, wat normaal is terwijl DNS propageert (minuten tot uren). De aanroep kan veilig herhaald worden terwijl je wacht.
Een domein dat ongeveer 14 dagen niet geverifieerd blijft, wordt verwijderd. We sturen de werkruimte een paar dagen voor verwijdering een herinnering, zodat je de configuratie kunt afronden.
De status op het hoogste niveau van het domein weerspiegelt eigendom, bewezen door het DKIM-record:
- pending: het DKIM-record is nog niet gepubliceerd.
- verified: het DKIM-record is aanwezig; eigendom is bevestigd.
- failed: er bestaat een DKIM-record, maar het komt niet overeen met de verwachte waarde, of een eerder geverifieerd record is verwijderd. Corrigeer het record om te herstellen.
- temporary_failure: DNS-resolutie is tijdelijk mislukt; verificatie wordt automatisch opnieuw geprobeerd.
- rejected: het domein is om beleidsredenen geweigerd; neem contact op met support.
Gereedheid om te verzenden wordt apart gerapporteerd onder capabilities. De verzendpoort is capabilities.sending, die pas verifieert wanneer DKIM, de return-path CNAME en een DMARC-beleid allemaal aanwezig zijn; SPF op de domain-apex is niet vereist. Trackinggereedheid (capabilities.tracking) is onafhankelijk van de verzendpoort: het bepaalt of branded open/click-tracking kan worden gebruikt, nooit of het domein mag verzenden.
Wanneer een geverifieerd record breekt
Verificatie stopt nooit: de dagelijkse hercontrole houdt geverifieerde domeinen eerlijk, dus als je DNS later kapotgaat, merken we dat. Om schommelingen bij tijdelijke DNS-storingen te voorkomen, wordt een geverifieerd record dat begint te falen bij hercontroles in een waarschuwingsstatus als geverifieerd vastgehouden en elk uur opnieuw gecontroleerd, en we stellen je op de hoogte. Pas nadat het record 24 uur lang is blijven falen, wordt het domein gedegradeerd; elke geslaagde controle binnen dat venster heft de waarschuwing op. Degradaties gelden vanaf de volgende verzending, en een gedegradeerd domein verifieert automatisch opnieuw zodra de records zijn hersteld, bij de volgende automatische controle of een handmatige verificatie.
Domeinen beheren
Regio's. Domeinstatus is regionaal. Als je vanuit zowel us1 als eu1 verzendt, registreer het domein dan in elke regio; elke registratie krijgt zijn eigen DKIM-selector en verifieert onafhankelijk.
Return-path- of trackinghostnamen wijzigen. Deze hostnamen behoren tot de domeinconfiguratie van je werkruimte. Een hostnaam die al geverifieerd is, wordt nooit vervangen door een niet-geverifieerde: wijzigingen worden klaargezet, geverifieerd naast je actieve configuratie, en pas gepromoveerd wanneer de nieuwe records in orde zijn.
Open/click-tracking. De settings-toggles behoren tot de domeinconfiguratie van de werkruimte. Wijzigingen aan de toggles gelden alleen voor deze domeinconfiguratie. Je kunt ze inschakelen zodra een trackingdomein is geconfigureerd. Een toggle inschakelen zonder trackingdomein retourneert een 409. De toggles beïnvloeden verzendingen pas nadat dat trackingdomein verifieert, dus verificatie wordt per verzending afgedwongen.
Verwijdering. DELETE /v1/email/domains/{domain_id} verwijdert het verzenddomein uit je werkruimte. Ander gebruik van het domein blijft ongewijzigd.
Volgende stappen
- DKIM, SPF en DMARC: wat elk record doet en hoe je waarden kiest.
- DNS-walkthroughs per provider: configuratiestappen voor Cloudflare, Route 53, GoDaddy en meer.
- Domains API-referentie: volledige request/response-schema's voor elk endpoint.
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
Bekijk de gidsGetting started with emailOntdek de mogelijkheidEmailVolg het leerpadBuild your first integrationImplementatiegidsSend your first email
Probeer de oefening en ontvang een implementatieoverzicht