Transaktions-Webhooks

Webhooks ermöglichen es Ihrer Anwendung, Echtzeit-Benachrichtigungen zu erhalten, wenn nach dem Versand einer Transaktions-E-Mail etwas passiert. Anstatt die API abzufragen, um den Zustellungsstatus zu prüfen, sendet Flexmail in dem Moment, in dem ein Ereignis eintritt, eine HTTP-POST-Anfrage an Ihren Endpunkt.

Dies ist besonders wertvoll für Transaktions-E-Mails: Sie können sofort handeln, wenn ein Passwort-Reset bounced, wenn eine Bestellbestätigung zugestellt wird oder wenn ein Empfänger eine Nachricht als Spam meldet.

Webhook-Ereignisse

Flexmail sendet für jedes der folgenden Ereignisse eine Webhook-Benachrichtigung:

  • Gesendet – die Nachricht wurde akzeptiert und an den empfangenden Mailserver übergeben.
  • Zugestellt – der empfangende Mailserver hat die Zustellung in das Postfach des Empfängers bestätigt.
  • Bounced – Zustellung fehlgeschlagen. Hard Bounces weisen auf ein dauerhaftes Problem hin (Adresse existiert nicht); Soft Bounces weisen auf ein vorübergehendes Problem hin (Postfach voll, Server nicht verfügbar).
  • Geöffnet – der Empfänger hat die Nachricht geöffnet.
  • Geklickt – der Empfänger hat auf einen verfolgten Link in der Nachricht geklickt.
  • Beschwert – der Empfänger hat die Nachricht als Spam gemeldet.

Hinweis

Öffnungs- und Klick-Tracking erfordern aktivierte Tracking-Pixel und Link-Umschreibung. Zustellungsereignisse hängen davon ab, ob der empfangende Mailserver die Zustellung bestätigt – nicht alle Server tun dies.

Einen Webhook-Endpunkt einrichten

Ihr Webhook-Endpunkt ist eine URL auf Ihrem Server, die HTTP-POST-Anfragen akzeptiert und eine 200-Antwort zurückgibt, um den Empfang zu bestätigen.

Anforderungen für Ihren Endpunkt

  • Akzeptiert HTTP-POST-Anfragen.
  • Ist über HTTPS öffentlich zugänglich.
  • Gibt innerhalb eines angemessenen Timeouts einen 2xx-HTTP-Statuscode zurück, um den Empfang zu bestätigen.
  • Verarbeitet die Payload asynchron, wenn Ihre Verarbeitungslogik langsam ist – antworten Sie sofort und verarbeiten Sie im Hintergrund, um Timeouts zu vermeiden.

Ihren Endpunkt in Flexmail registrieren

Die Konfiguration des Webhook-Endpunkts erfolgt über die API. Der vollständige Registrierungsprozess und die verfügbaren Optionen sind in der API-Dokumentation unter email-api.flexmail.eu/documentation im Abschnitt Webhooks dokumentiert.

Webhook-Payload

Jede Webhook-Benachrichtigung ist eine HTTP-POST-Anfrage mit einem JSON-Body. Die Payload enthält den Ereignistyp, einen Zeitstempel, die Nachrichten-ID und die E-Mail-Adresse des Empfängers. Je nach Ereignis sind zusätzliche Felder enthalten – ein Bounce-Ereignis enthält beispielsweise den Bounce-Typ und den Grund, ein Klick-Ereignis enthält die angeklickte URL.

Eine typische Payload sieht folgendermaßen aus:

{ "event": "delivered", "timestamp": "2024-11-15T09:32:00Z", "messageId": "abc123", "recipient": "customer@example.com" }

Die vollständige Payload-Spezifikation für jeden Ereignistyp finden Sie in der API-Dokumentation.

Was mit Webhook-Ereignissen zu tun ist

Bounces

Wenn Sie ein Hard-Bounce-Ereignis erhalten, kennzeichnen Sie diese E-Mail-Adresse in Ihrem System. Stellen Sie das Senden an sie ein und untersuchen Sie, ob die Adresse korrekt eingegeben wurde. Das weitere Senden an Hard-Bounce-Adressen schädigt Ihre Absenderreputation.

Spam-Beschwerden

Wenn ein Empfänger eine Transaktions-E-Mail als Spam meldet, unterdrücken Sie diese Adresse sofort. Auch wenn die E-Mail wirklich transaktional war (z. B. eine Bestellbestätigung), hat der Empfänger signalisiert, dass er keine E-Mails von Ihnen erhalten möchte. Das weitere Senden ist sowohl für Ihre Reputation schädlich als auch möglicherweise ein rechtliches Problem.

Zustellungsbestätigungen

Für zeitkritische Nachrichten wie Passwort-Resets oder Zwei-Faktor-Authentifizierungscodes können Sie das Zustellungsereignis verwenden, um zu bestätigen, dass die E-Mail den Posteingang erreicht hat. Wenn innerhalb eines angemessenen Zeitfensters keine Zustellungsbestätigung eintrifft, können Sie in Ihrer Benutzeroberfläche eine Meldung anzeigen, die den Benutzer auffordert, seinen Spam-Ordner zu prüfen oder es erneut zu versuchen.

Tipp

Bestätigen Sie Webhook-Anfragen sofort mit einer 200-Antwort und verarbeiten Sie dann die Payload in einem Hintergrundjob oder einer Warteschlange. Wenn Ihr Handler zu lange für die Antwort braucht, kann Flexmail das Timeout erreichen und die Anfrage wiederholen, was zu doppelter Verarbeitung führen kann.

Wiederholungsversuche

Wenn Ihr Endpunkt keine erfolgreiche Antwort zurückgibt, wiederholt Flexmail die Webhook-Benachrichtigung. Machen Sie Ihre Ereignisverarbeitung idempotent – dieselbe Ereignisverarbeitung zweimal sollte dasselbe Ergebnis produzieren wie einmal. Verwenden Sie die Nachrichten-ID und den Ereignistyp zusammen für die Deduplizierung.

Nächste Schritte

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.