Sendedomains

Bevor wir E-Mails von Ihrer Domain zustellen können, müssen Sie nachweisen, dass Sie die Domain besitzen, und die DNS-Einträge veröffentlichen, mit denen Mailbox-Provider Ihre E-Mails authentifizieren. Eine Sendedomain ist die Workspace-bezogene Ressource (dom_...), die dieses Setup verfolgt: welche Einträge zu veröffentlichen sind, was verifiziert wurde und ob die Domain sendebereit ist.

Eine Domain organisationsübergreifend nutzen

Dieselbe Domain kann von mehreren Organisationen registriert werden, ohne dass sich jemand in die Quere kommt. Jede Organisation weist den Besitz mit ihrem eigenen DKIM-Schlüssel nach, daher gilt:

Eine andere Organisation auf derselben Domain kann Ihren Verifizierungsstatus niemals einsehen oder Ihre Konfiguration ändern.
Jede Region (us1, eu1) ist unabhängig: Dieselbe Domain in zwei Regionen ergibt zwei separate Registrierungen mit eigenen DNS-Einträgen. Registrieren Sie die Domain in jeder Region, aus der Sie senden.

Eine Domain registrieren

Erstellen Sie die Domain mit POST /v1/email/domains. Der Aufruf ist Workspace-bezogen und erwartet die Sendedomain sowie optionale Labels für die Return-Path- und Tracking-Hostnamen. Übergeben Sie nur das Label (send, links), und wir setzen den vollständigen Hostnamen unter Ihrer Sendedomain zusammen. Ausgelassene Werte verwenden standardmäßig send und links.

Verwenden Sie eine dedizierte Subdomain (mail.acme.com) anstelle Ihrer registrierten Domain. Das hält Ihre Sendereputation von allem anderen auf der Domain getrennt und sorgt dafür, dass alle Einträge, die wir Sie zu veröffentlichen bitten, nicht auf Ihrem Zone-Apex liegen. Der zweite Grund ist der problematische: Der MX-Eintrag für den Empfang liegt auf demselben Namen wie die MX-Einträge, die bereits die E-Mails Ihres Unternehmens transportieren – bei einer Apex-Sendedomain leitet seine Veröffentlichung diese E-Mails an uns um.

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" }
  }'

Die Antwort enthält status: pending, den Ihrer Organisation zugewiesenen DKIM-Selektor und die zu veröffentlichenden dns_records. Eine bestehende Workspace-Registrierung gibt 409 zurück. Bei Überschreitung des Domain-Kontingents Ihrer Organisation wird 422 zurückgegeben. Ersetzen Sie eu1 durch us1 für einen US-Workspace. API-Schlüssel verwenden dieselben regionalen Präfixe: bk_eu1_... und bk_us1_.... Sie können Domains auch unter Email > Domains verwalten.

Die Domains-Seite im Dashboard mit einer verifizierten Sendedomain und ihren Sende-, Return-Path- und Tracking-Fähigkeiten

Die DNS-Einträge veröffentlichen

Das dns_records-Array liefert Ihnen für jeden Eintrag kopierbereite name, host und value. Einige Anbieter lehnen einen langen DKIM-TXT-Wert als einzelnen String ab; der DNS-Record-Splitter zerlegt ihn in die Strings in Anführungszeichen, die diese Anbieter erwarten. Was Sie veröffentlichen:

Eintrag	Typ	Zum Senden erforderlich	Funktion
DKIM	TXT	Ja	Weist den Besitz nach und signiert Ihre E-Mails mit dem Schlüssel Ihrer Organisation
Return-Path-CNAME	CNAME	Ja	Leitet Bounces an uns zurück und deckt SPF ab; die SPF-Abfrage folgt dem CNAME, daher wird kein SPF-Eintrag auf Ihrem Domain-Apex benötigt
DMARC	TXT	Ja	Eine gültige v=DMARC1-Richtlinie, die die Sendedomain abdeckt – auf der Domain selbst oder auf ihrer registrierten (organisationsbezogenen) Domain. Eine minimale p=none-Richtlinie genügt.
Tracking-CNAME	CNAME	Nein	Aktiviert gebrandete Open-/Click-Tracking-Hostnamen; getrackte Links werden nach der Verifizierung über HTTPS ausgeliefert
Inbound-MX	MX	Nein	Leitet E-Mails für die Domain zum Empfang an uns weiter. Trägt optional: true, bis Sie den Empfang aktivieren; die Veröffentlichung ersetzt die MX-Einträge, die die Domain aktuell verwendet.

Zweck und Werte der einzelnen Einträge finden Sie unter DKIM, SPF und DMARC. Die Empfangs-MX-Einträge befinden sich in dns_records mit purpose: inbound_mx, sobald der Empfang in Ihrer Region verfügbar ist, und tragen optional: true, bis Sie den Empfang aktivieren für die Domain. Überspringen Sie jeden mit optional markierten Eintrag, es sei denn, Sie möchten die damit verbundene Funktion nutzen. Für DNS-Provider-spezifische Einrichtungsschritte siehe die Anleitungen für Cloudflare, Route 53 oder allgemeine Registrare.

Das Dashboard erkennt unterstützte DNS-Provider anhand der Nameserver Ihrer Domain und verlinkt deren DNS-Einstellungen. Öffnen Sie Email > Domains und wählen Sie eine Domain aus, um ihre Einträge anzuzeigen. Falls jemand anderes Ihr DNS verwaltet, sendet POST /v1/email/domains/{domain_id}/dns-records/share dieser Person die zu veröffentlichenden Einträge per E-Mail.

Die DNS-Records-Seite einer Domain im Dashboard mit dem verifizierten DKIM-Eintrag mit kopierbarem Namen und Wert, gefolgt von den Return-Path- und DMARC-Abschnitten

Verifizierungslebenszyklus

Eine neue Domain startet als pending. Sie müssen niemals pollen, da wir Ihre Einträge automatisch prüfen. Die Prüfungen beginnen sofort bei der Registrierung und gehen von alle paar Minuten auf stündlich innerhalb der ersten drei Tage zurück. Danach laufen sie täglich für jede aktive Domain. Es genügt, Ihre Einträge zu veröffentlichen und zu warten; die meisten Domains werden innerhalb von Minuten nach der DNS-Propagierung verifiziert. Wenn Sie eine sofortige Prüfung wünschen (z. B. direkt nach einer DNS-Änderung), rufen Sie POST /v1/email/domains/{domain_id}/verify auf: Der Aufruf führt eine aktuelle Prüfung durch und gibt die aktualisierte Domain zurück. Eine 200-Antwort mit Einträgen, die noch pending sind, ist kein Fehler – sie bedeutet, dass die Einträge noch nicht gefunden wurden, was während der DNS-Propagierung (Minuten bis Stunden) normal ist. Der Aufruf kann während des Wartens beliebig oft wiederholt werden.

Eine Domain, die etwa 14 Tage lang unverifiziert bleibt, wird entfernt. Wir senden dem Workspace einige Tage vor der Entfernung eine Erinnerungs-E-Mail, damit Sie das Setup abschließen können.

Der status auf oberster Ebene der Domain spiegelt den Besitznachweis wider, belegt durch den DKIM-Eintrag:

pending: Der DKIM-Eintrag wurde noch nicht veröffentlicht.
verified: Der DKIM-Eintrag ist vorhanden; der Besitz ist bestätigt.
failed: Ein DKIM-Eintrag existiert, stimmt aber nicht mit dem erwarteten Wert überein, oder ein zuvor verifizierter Eintrag wurde entfernt. Korrigieren Sie den Eintrag, um den Zustand wiederherzustellen.
temporary_failure: Die DNS-Auflösung ist vorübergehend fehlgeschlagen; die Verifizierung wird automatisch erneut versucht.
rejected: Die Domain wurde aus Richtliniengründen abgelehnt; kontaktieren Sie den Support.

Die Sendebereitschaft wird separat unter capabilities gemeldet. Das Sende-Gate ist capabilities.sending, das nur verifiziert, wenn DKIM, der Return-Path-CNAME und eine DMARC-Richtlinie alle vorhanden sind; SPF auf dem Domain-Apex ist nicht erforderlich. Die Tracking-Bereitschaft (capabilities.tracking) ist unabhängig vom Sende-Gate: Sie steuert, ob gebrandetes Open-/Click-Tracking genutzt werden kann, niemals ob die Domain senden darf.

Wenn ein verifizierter Eintrag ungültig wird

Die Verifizierung hört nie auf: Die tägliche Nachprüfung hält verifizierte Domains aktuell – wenn Ihr DNS später fehlerhaft wird, bemerken wir das. Um ein Hin-und-Her bei vorübergehenden DNS-Störungen zu vermeiden, wird ein verifizierter Eintrag, der bei der Nachprüfung fehlschlägt, in einem Warnzustand als verifiziert gehalten und stündlich erneut geprüft, und wir benachrichtigen Sie. Erst wenn der Eintrag volle 24 Stunden lang fehlgeschlagen ist, wird die Domain herabgestuft; jede bestandene Prüfung innerhalb dieses Zeitfensters hebt die Warnung auf. Herabstufungen werden beim nächsten Versand wirksam, und eine herabgestufte Domain wird automatisch erneut verifiziert, sobald die Einträge korrigiert sind – bei der nächsten automatischen Prüfung oder einer manuellen Verifizierung.

Domains verwalten

Regionen. Der Domain-Status ist regional. Wenn Sie sowohl aus us1 als auch aus eu1 senden, registrieren Sie die Domain in jeder Region; jede Registrierung erhält ihren eigenen DKIM-Selektor und wird unabhängig verifiziert.

Return-Path- oder Tracking-Hostnamen ändern. Diese Hostnamen gehören zur Domain-Konfiguration Ihres Workspaces. Ein bereits verifizierter Hostname wird nie durch einen unverifizierten ersetzt: Änderungen werden bereitgestellt, parallel zu Ihrer aktiven Konfiguration verifiziert und erst übernommen, wenn die neuen Einträge bestätigt sind.

Open-/Click-Tracking. Die settings-Schalter gehören zur Domain-Konfiguration des Workspaces. Änderungen an den Schaltern gelten nur für diese Domain-Konfiguration. Sie können sie aktivieren, sobald eine Tracking-Domain konfiguriert ist. Die Aktivierung ohne konfigurierte Tracking-Domain gibt 409 zurück. Die Schalter wirken sich auf den Versand erst aus, nachdem die Tracking-Domain verifiziert ist – die Verifizierung wird also pro Versand durchgesetzt.

Löschung. DELETE /v1/email/domains/{domain_id} entfernt die Sendedomain aus Ihrem Workspace. Andere Verwendungen der Domain bleiben unverändert.

Nächste Schritte

DKIM, SPF und DMARC: Was jeder Eintrag bewirkt und wie Sie Werte auswählen.
DNS-Anleitungen nach Provider: Einrichtungsschritte für Cloudflare, Route 53, GoDaddy und mehr.
Domains-API-Referenz: Vollständige Request-/Response-Schemas für jeden Endpunkt.

Verwandte Ressourcen