E-Mail über SMTP senden

Wenn Ihre Anwendung bereits SMTP unterstützt, richten Sie sie auf unser Relay, indem Sie Host, Port und Zugangsdaten ändern. Frameworks, Content-Management-Systeme, Drucker und andere Software, die E-Mails an ein SMTP-Relay übergeben kann, können diesen Weg nutzen.

Über SMTP eingelieferte E-Mails werden exakt wie über die E-Mail-API gesendete E-Mails behandelt: dieselbe Domain-Verifizierung, IP-Pools, DKIM-Signierung, Unterdrückungsbehandlung, Tracking, Events und Analytics. SMTP ist ein zweiter Zugang zum selben Produkt – alles, was Sie für den einen Weg einrichten, gilt auch für den anderen.

Wählen Sie den SMTP-Relay-Dienst, wenn Sie den vorhandenen Code zur Nachrichtenerstellung Ihrer Anwendung beibehalten möchten. Wählen Sie die E-Mail-API, wenn Sie strukturierte Anfragefelder oder gespeicherte Templates benötigen. SMTP übernimmt den Inhalt aus der MIME-Nachricht und die Versandoptionen aus der Konfiguration des API-Keys.

Was Sie zuerst brauchen

Eine verifizierte Absenderdomain. Die Adresse, die Sie in MAIL FROM angeben (und der From-Header der Nachricht), muss zu einer Domain gehören, die Sie in diesem Workspace verifiziert haben. Siehe Absenderdomains.
Ein API-Key mit dem emails-Scope. SMTP verwendet Ihre normalen API-Keys und benötigt keine separaten SMTP-Zugangsdaten. Erstellen Sie einen Key unter Developers > API keys mit aktiviertem E-Mail-Versand. Ein Key ohne den emails-Scope kann nicht senden, ebenso wenig ein reiner verify-Key.

Verbindungseinstellungen

Richten Sie Ihren Client auf den SMTP-Host für die Region Ihres Keys. Die Region ist das Präfix im Key selbst: Ein bk_eu1_...-Key sendet über den eu1-Host, ein bk_us1_...-Key über us1. Die Authentifizierung mit einem Key aus der anderen Region schlägt mit einer 535-Antwort fehl, die den richtigen Host nennt.

Region	Host
EU	eu1.smtp.bird.com
US	us1.smtp.bird.com

Port	Verschlüsselung
465	Implizites TLS (SMTPS)
587	STARTTLS
2525	STARTTLS

Verwenden Sie den Port, den Ihr Client unterstützt:

Port 465, implizites TLS (SMTPS). Die Verbindung ist ab dem ersten Byte verschlüsselt, bevor ein Befehl gesendet wird. In den meisten Bibliotheken ist das die Option "SSL/TLS" oder "SMTPS".
Ports 587 und 2525, STARTTLS. Die Verbindung wird im Klartext aufgebaut und vor der Authentifizierung mit dem Befehl STARTTLS auf TLS hochgestuft. Das ist die Option "STARTTLS", manchmal schlicht als "TLS" bezeichnet. Verwenden Sie 2525, wenn Ihr Netzwerk Port 587 blockiert.

In jedem Fall ist die Sitzung verschlüsselt, bevor Ihre Zugangsdaten gesendet werden – sie werden also nie im Klartext übertragen: Auf Port 587 und 2525 wird AUTH abgelehnt, bis STARTTLS abgeschlossen ist. Port 25 wird für die Einlieferung nicht angeboten.

Authentifizierung

Authentifizieren Sie sich mit AUTH PLAIN oder AUTH LOGIN. Der Benutzername ist die feste Zeichenkette bird, und das Passwort ist Ihr API-Key:

Codebeispiel

Username: bird
Password: bk_eu1_your_api_key

Der Benutzername ist ein fester Literalwert ohne eigene Identität. Der API-Key im Passwortfeld führt die Authentifizierung durch. In den meisten SMTP-Tools fügen Sie Ihren API-Key in das Passwortfeld ein und setzen den Benutzernamen auf bird. Wird der Key widerrufen, wird sein SMTP-Versand innerhalb von Sekunden unterbunden, auch bei laufender Verbindung.

Was aus der Nachricht kommt und was aus der Key-Konfiguration

Alles, was einen natürlichen Platz in einer MIME-Nachricht hat, stammt aus der Nachricht selbst: die Header From, To, Cc und Reply-To, der Betreff, die HTML- und Text-Bodys sowie Anhänge und Inline-Bilder. Die Empfänger werden aus dem SMTP-Envelope übernommen (RCPT TO). Eine Adresse in RCPT TO, die nicht in einem sichtbaren To- oder Cc-Header steht, wird als Bcc behandelt. Eine Nachricht kann maximal 50 Empfänger über To, Cc und Bcc haben, und die Gesamtgröße der Nachricht ist auf 20 MB begrenzt.

Versandoptionen ohne Standardplatz in einer MIME-Nachricht stammen aus der SMTP-Konfiguration des Keys. Dazu gehören IP-Pool, Kategorie, Tags sowie Open- und Click-Tracking. Ein unkonfigurierter Key verwendet den Standard-Pool Ihrer Organisation, die Kategorie transactional und aktiviertes Tracking. Konfigurieren Sie den Key unter Email > SMTP, oder rufen Sie die SMTP-Config-API auf. Geben Sie jeder Anwendung einen eigenen Key, wenn sie unterschiedliche Standardwerte benötigt. Änderungen gelten für neue Nachrichten, ohne den Client neu zu verbinden.

Eine vollständige Sitzung

Auf Port 465 baut der Client zuerst die TLS-Verbindung auf und führt dann den gesamten SMTP-Dialog darin aus:

Codebeispiel

   ... TLS handshake ...
S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0

Auf Port 587 oder 2525 verbindet sich der Client im Klartext, sendet STARTTLS zum Hochstufen der Verbindung und führt dann denselben Dialog innerhalb von TLS aus. AUTH wird erst nach Abschluss des Upgrades angeboten:

Codebeispiel

S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-STARTTLS
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: STARTTLS
S: 220 2.0.0 Ready to start TLS
   ... TLS handshake ...
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0

Das abschließende 250 gibt die ID der eingereihten Nachricht zurück – dieselbe em_...-ID, die Sie auch von der API erhalten würden. Sie können die Nachricht über diese ID im E-Mail-Log oder über GET /v1/email/messages/{message_id} nachschlagen.

Sicheres erneutes Senden

Die Pipeline nimmt eine Nachricht an und stellt sie asynchron zu, und SMTP-Clients versuchen es aggressiv erneut, wenn eine Verbindung abbricht. Um einen Retry sicher zu machen, fügen Sie der Nachricht einen X-Bird-Idempotency-Key-Header hinzu: Eine Wiederholung innerhalb des Aufbewahrungsfensters gibt die ID der bereits eingereihten Nachricht zurück, statt eine zweite Kopie zu senden. Verwenden Sie einen Wert, der für die logische Nachricht stabil ist, z. B. eine Bestell-ID oder Benachrichtigungs-ID. Vermeiden Sie es, bei jedem Versuch einen zufälligen Wert zu generieren.

Speichern Sie die ID der eingereihten Nachricht zusammen mit dem Anwendungs-Event, das den Versand ausgelöst hat. Wenn die Verbindung abbricht, bevor Sie die abschließende Antwort erhalten, senden Sie diese logische Nachricht mit demselben Key erneut. Nach dem Aufbewahrungsfenster kann ein Retry eine weitere Nachricht erzeugen. Führen Sie eine eigene Versandaufzeichnung für die Wiederherstellung über dieses Fenster hinaus.

Verbindungslimits

Jede Organisation kann standardmäßig bis zu 10 gleichzeitige authentifizierte SMTP-Verbindungen halten. Eine Verbindung zählt von der Authentifizierung bis zum Schließen, über alle Server und API-Keys der Organisation hinweg. Am Limit erhält eine weitere Verbindung nach der Authentifizierung eine vorübergehende 421-Antwort. Nutzen Sie Verbindungen wieder, reduzieren Sie die Gleichzeitigkeit und versuchen Sie es erneut. Das Limit zählt offene Verbindungen unabhängig vom Nachrichtenvolumen. Email > SMTP zeigt aktive Verbindungen im Verhältnis zum Limit an.

Dimensionieren Sie Ihren Verbindungspool nach dem Verbindungslimit der Organisation. Drosseln Sie die Einlieferung entsprechend den Versandkontingenten. HTTP-Rate-Limit-Header beschreiben API-Anfragen; sie sind kein SMTP-Versandratenkontingent.

SMTP-Antworten verarbeiten

SMTP meldet eine nicht verifizierte Absenderdomain, eine reservierte Empfängerdomain, einen nicht verwendbaren IP-Pool, einen blockierten Anhangstyp oder eine fehlerhafte Nachricht mit einer permanenten 550-Antwort. Eine Nachricht über dem 20-MB-Limit gibt 552 zurück. Ein überschrittenes Versandkontingent oder eine Empfängeranzahl über 50 gibt eine vorübergehende 452-Antwort zurück. Unterdrückte Empfänger werden asynchron behandelt: SMTP nimmt die Nachricht an, und jeder unterdrückte Empfänger erscheint als rejected im E-Mail-Log und in den Events.

Vergleichen Sie für die Schnittstellenentscheidung SMTP- und HTTP-Einlieferung und -Wiederherstellung. Beide Wege reihen die Arbeit vor der Empfängerzustellung ein. Ein email.delivered-Event protokolliert die Annahme durch den empfangenden Server. Dieses Event bestätigt nicht die Platzierung im Posteingang.

Nächste Schritte

Absenderdomains: Verifizieren Sie die Domain, von der Sie senden möchten.
Dedizierte IPs und Pools: Wählen Sie, über welchen Pool ein Key sendet.
Unterdrückungen: Warum ein akzeptierter Empfänger eine Nachricht möglicherweise nicht erhält.
E-Mail-Log: Finden Sie eine Nachricht anhand der von SMTP zurückgegebenen ID.

Verwandte Ressourcen