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.

TLS-Versionen: Die Ports 465, 587 und 2525 unterstützen TLS 1.2 und TLS 1.3. Konfigurieren Sie Ihren Client für TLS 1.2 oder höher. TLS 1.0 und TLS 1.1 werden nicht unterstützt.

In beiden Fällen 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 steht für die Einlieferung nicht zur Verfügung.

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 Platzhalter ohne eigene Identität. Der API-Key im Passwortfeld übernimmt die Authentifizierung. In den meisten SMTP-Tools fügen Sie Ihren API-Key in das Passwortfeld ein und setzen den Benutzernamen auf bird. Wenn Sie den Key widerrufen, wird sein SMTP-Versand innerhalb von Sekunden unterbunden, auch mitten in einer Verbindung.

Was aus der Nachricht stammt und was aus der Konfiguration des Keys

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, der HTML- und Textkörper sowie Anhänge und Inline-Bilder. 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 höchstens 50 Empfänger über To, Cc und Bcc haben, und die Gesamtgröße ist auf 20 MB begrenzt.

Sendeoptionen, die keinen Standardplatz in einer MIME-Nachricht haben, stammen aus der SMTP-Konfiguration des Keys. Dazu gehören der IP-Pool, die Kategorie, Tags sowie Open- und Click-Tracking. Ein unkonfigurierter Key verwendet den Standardpool 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 andere Standardwerte benötigt. Änderungen gelten für neue Nachrichten, ohne dass der Client neu verbunden werden muss.

Eine vollständige Sitzung

Auf Port 465 öffnet der Client zuerst die TLS-Verbindung 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 Upgrade 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 von der API erhalten würden. Sie können die Nachricht anhand dieser ID im E-Mail-Log oder über GET /v1/email/messages/{message_id} nachschlagen.

Sicheres erneutes Senden

Die Pipeline nimmt eine Nachricht entgegen und stellt sie asynchron zu, und SMTP-Clients versuchen bei einem Verbindungsabbruch aggressiv erneut zu senden. Um einen Wiederholungsversuch 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 Anwendungsereignis, das den Versand ausgelöst hat. Wenn die Verbindung abbricht, bevor Sie die abschließende Antwort erhalten, senden Sie die logische Nachricht mit demselben Key erneut. Nach dem Aufbewahrungsfenster kann ein Wiederholungsversuch eine weitere Nachricht erzeugen. Führen Sie einen eigenen Versandnachweis 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 ab 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. Verwenden Sie Verbindungen wieder, reduzieren Sie die Parallelität 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 gegen das Verbindungslimit der Organisation. Drosseln Sie Einlieferungen entsprechend der Sendekontingente. HTTP-Rate-Limit-Header beschreiben API-Anfragen; sie stellen keine SMTP-Senderate-Freigabe dar.

SMTP-Antworten verarbeiten

SMTP meldet eine nicht verifizierte Sendedomain, eine reservierte Empfängerdomain, einen nicht nutzbaren 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 Sendekontingent 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 entgegen, dann erscheint jeder unterdrückte Empfänger 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 Arbeit ein, bevor die Zustellung an den Empfänger erfolgt. Ein email.delivered-Event dokumentiert die Annahme durch den empfangenden Server. Dieses Event bestätigt keine Zustellung in den Posteingang.

Nächste Schritte

Absenderdomains: Verifizieren Sie die Domain, von der Sie senden werden.
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: eine Nachricht anhand der von SMTP zurückgegebenen ID finden.

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

SMTP relay

Verwandte Ressourcen