Nach dem Checkout hat Ihre Anwendung eine Bestellung und einen Empfänger, der eine Quittung benötigt. Sie nutzt eine E-Mail-API, um die Nachricht zu übermitteln. Sie speichert die Antwort zur Bestellung.
Die Übermittlung ist nur der erste Schritt. Ihre Anwendung braucht außerdem eine Möglichkeit, eine Anfrage erneut zu versuchen. Sie muss erfahren, was nach der Übermittlung mit der Nachricht passiert ist.
Wie wird ein Anwendungsereignis zu einer E-Mail?
Ihre Anwendung wandelt eine abgeschlossene Transaktion oder eine Kontoanfrage in einen Sendevorgang um. Der E-Mail-Dienst übernimmt die Zustellung nach der Übermittlung.
Für eine Quittung sieht dieser Ablauf so aus:
- Ihre Anwendung bestätigt, dass die Bestellung für eine Quittung bereit ist.
- Sie wählt den Empfänger aus und liefert die Bestelldetails als Inhalt oder Template-Werte.
- Sie übermittelt den Sendevorgang und speichert die zurückgegebene Nachrichten-ID zur Bestellung.
- Sie aktualisiert den Sendedatensatz, wenn Zustellungsereignisse eintreffen.
Eine E-Mail-API kann sowohl transaktionale als auch Marketing-Nachrichten unterstützen. Die Verwendung einer API macht Werbeinhalte nicht transaktional und hebt keine CAN-SPAM-Pflichten auf.
Was bedeutet eine erfolgreiche Antwort?
Eine erfolgreiche Übermittlungsantwort protokolliert, was der Dienst angenommen hat. Sie ist unabhängig von der späteren Entscheidung des empfangenden Mailservers.
Der 202-Status von HTTP bedeutet, dass eine Anfrage zur Verarbeitung angenommen wurde. Die Verarbeitung ist nicht abgeschlossen, daher kann diese Antwort keine Zustellung bestätigen.
Die genaue Antwort hängt von der API ab. Der Send-Endpoint von Bird gibt beispielsweise eine in die Warteschlange gestellte Nachricht mit einer id zurück. Speichern Sie diese ID zusammen mit der Bestellung oder dem Kontoereignis, damit spätere Ergebnisse der ursprünglichen Anfrage zugeordnet werden können.
Wenn die Validierung fehlschlägt, gibt Bird 422 mit einem Fehler zurück, der erklärt, warum die Anfrage abgelehnt wurde.
Wie vermeiden Wiederholungsversuche doppelte Nachrichten?
Ein Idempotenzschlüssel identifiziert einen logischen Sendevorgang über Wiederholungsversuche hinweg. Eine API, die ihn unterstützt, kann eine wiederholte Anfrage erkennen, statt einen weiteren Sendevorgang zu erstellen.
Zum Beispiel kann eine Quittung für Bestellung 8472 den Schlüssel receipt/order-8472 verwenden. Wiederholen Sie dieselbe Anfrage mit diesem Schlüssel, wenn die Verbindung abbricht, bevor Sie die Antwort erhalten.
Ein neuer Schlüssel identifiziert einen anderen Vorgang. Ihre Anwendung muss daher den ursprünglichen Schlüssel über eigene Wiederholungsversuche und Neustarts hinweg beibehalten.
Idempotenz hat ein vom Anbieter definiertes Aufbewahrungsfenster. Nach Ablauf dieses Fensters kann derselbe Schlüssel als neue Anfrage verarbeitet werden.
Wie berichten Webhooks über die Zustellung?
Ein Webhook sendet ein Ereignis an Ihre Anwendung, wenn sich der Status der Nachricht ändert. So kann Ihre Anwendung ihre Datensätze nach der initialen API-Antwort aktualisieren.
Die E-Mail-Ereignisse von Bird unterscheiden diese Ergebnisse:
| Ereignis | Was es bestätigt |
|---|---|
email.delivered | Der empfangende Mailserver hat die Verantwortung für die Nachricht übernommen |
email.deferred | Ein vorübergehender Zustellungsfehler wird erneut versucht |
email.bounced | Der empfangende Server hat die Zustellung abgelehnt |
email.rejected | Die Nachricht hat keinen Zustellversuch erreicht |
Die Annahme durch den Server bestätigt weder die Platzierung im Posteingang noch das Lesen. Ein empfangender Server kann auch nach Annahme der Nachricht einen späteren Bounce melden.
Ihr Webhook-Handler muss die Signatur des Absenders verifizieren und doppelte Zustellungen behandeln. Der Webhook-Vertrag von Bird erfordert Deduplizierung mittels webhook-id.
Was ändern Templates?
Ein gespeichertes Template trennt wiederverwendbaren Nachrichteninhalt von den Werten, die bei jedem Sendevorgang übergeben werden. Ihre Anwendung kann eine Bestellnummer und einen Kundennamen liefern, ohne den vollständigen E-Mail-Body zusammenzusetzen.
Mit den Templates von Bird benennt ein Sendevorgang ein veröffentlichtes Template und übergibt dessen Parameter. Das Template liefert Betreff und Body.
Ein Template entscheidet nicht, wann eine Bestellung abgeschlossen ist oder ob eine Passwortzurücksetzung autorisiert ist. Diese Entscheidungen verbleiben in Ihrer Anwendung.
Wie unterscheidet es sich von SMTP-Relay oder einer Marketing-Plattform?
Eine HTTP-API und ein SMTP-Relay sind unterschiedliche Übermittlungsschnittstellen. Eine Marketing-Plattform verwaltet zusätzlich Kampagnenarbeit, etwa Zielgruppenauswahl und Sendeplanung.
| Schnittstelle oder Produkt | Was Ihre Anwendung liefert |
|---|---|
| E-Mail-API | Eine strukturierte HTTP-Anfrage mit Empfängern und Inhalt oder einem Template |
| SMTP-Relay | Eine SMTP-Konversation, die Empfänger und eine formatierte E-Mail-Nachricht übermittelt |
| Marketing-Plattform | Kampagneninhalt, Zielgruppenauswahl und Sendeanweisungen |
SMTP definiert den Austausch für die Übermittlung einer Nachricht und ihrer Empfänger. Es kann transaktionale oder Marketing-E-Mails transportieren.
Das SMTP-Relay von Bird und HTTP API nutzen dasselbe Zustellungsprodukt, einschließlich Ereignissen und Unterdrückungsbehandlung. Die Wahl von SMTP entfernt diese Funktionen nicht.
Wie senden Sie transaktionale E-Mails über Bird?
Sie rufen POST /v1/email/messages mit einem verifizierten Absender, Empfängern und Inline-Inhalt oder einem veröffentlichten Template auf. Setzen Sie category: "transactional" für operative E-Mails. Die Antwort ist 202 Accepted mit einer Nachrichten-ID; die Zustellung erfolgt asynchron.
Verwenden Sie einen Idempotency-Key für jeden logischen Sendevorgang. Bird behält eine abgeschlossene Antwort drei Stunden lang. Ein Wiederholungsversuch nach diesem Fenster kann eine weitere Nachricht erzeugen – führen Sie daher eigene Aufzeichnungen über abgeschlossene Geschäftsereignisse.
Abonnieren Sie E-Mail-Ereignisse und ordnen Sie email_id und recipient_id Ihren Datensätzen zu. Eine Nachricht mit mehreren Empfängern hat separate Ergebnisse für jeden Empfänger.
Für die Anbieterwahl deckt die Checkliste für transaktionale E-Mail-Dienste die zu vergleichenden Zustellungs- und Betriebsfähigkeiten ab.