Ereignisse und Webhooks
Webhooks verbinden
Geben Sie in Ihren Integrationseinstellungen die Adresse für den Empfang von Webhooks an. Es erhält Benachrichtigungen über neue Briefe, den Status von Postfächern und die Betriebsergebnisse.
Legen Sie in den Integrationseinstellungen ein separates Webhook-Geheimnis fest und aktivieren Sie die Zustellung. Dieses Geheimnis wird zur Überprüfung von Benachrichtigungssignaturen verwendet. mail API-key ist dafür nicht geeignet.
Benachrichtigungsformat
Die Benachrichtigung kommt HTTP POST- Anfrage mit Content-Type: application/json. Feld event enthält den Ereignistyp, timestamp – Benachrichtigungszeit, data – Ereignisdaten. Die Zusammensetzung von data hängt vom Ereignis ab.
Anhand der Kennung data.event_id können Sie eine erneute Zustellung erkennen. Speichern Sie es zusammen mit Ihrer Integrations-ID und verarbeiten Sie ein Ereignis nur einmal.
{ "event": "mail.message.received", "timestamp": "2026-11-01T12:00:00Z", "data": { "event_id": "00000000-0000-4000-8000-000000000001", "created_at": "2026-11-01T12:00:00Z", "mailbox_id": 42, "folder": "INBOX", "uidvalidity": 123456, "uid": 120 }}Überprüfung und Bestätigung
Der Header X-Webhook-Signature enthält HMAC-SHA256 in kleiner hexadezimaler Schreibweise. Berechnen Sie die Signatur aus den ursprünglichen Bytes des Anforderungstexts und dem Webhook-Geheimnis. Überprüfen Sie die Signatur, bevor Sie Daten verarbeiten. Durch die erneute Serialisierung von JSON werden die zu signierenden Bytes geändert.
Nachdem Sie die Signatur überprüft und das Ereignis gespeichert haben, geben Sie HTTP 200 oder 201 zurück. Die Antworten 202 und 204 bestätigen den Empfang nicht. Antworten Sie innerhalb von 10 Sekunden; Führen Sie nach dem Speichern des Ereignisses eine längere Verarbeitung durch.
Benachrichtigungen können wiederholt und in unregelmäßiger Reihenfolge eingehen. Bevor Sie den Abonnementstatus ändern, überprüfen Sie dessen aktuelle Details. Der Lieferverlauf ist in den Integrationseinstellungen verfügbar.
Welche Ereignisse passieren
mailbox.created- Die Box ist erstellt und einsatzbereit.
mailbox.expiring- Das Ende des bezahlten Zeitraums für die Box naht.
mailbox.renewed- Der bezahlte Zeitraum für die Box wurde verlängert.
mailbox.suspended- Der Zugriff auf das Postfach ist gesperrt: Lesen und Senden sind nicht möglich.
mailbox.resumed- Der Zugriff auf das Postfach wurde wiederhergestellt.
mailbox.deleting_soon- Es verbleibt noch eine Stunde, bis die unbezahlte Box gelöscht wird.
mailbox.deleted- Die Box wurde gelöscht.
mailbox.account_changed- Das Postfach ist mit einem anderen E-Mail-Konto verknüpft.
mail.message.received- Im Briefkasten ist ein neuer eingehender Brief aufgetaucht.
mail.operation.succeeded- Der Vorgang wurde erfolgreich abgeschlossen. Beim Versenden bedeutet dies, dass der Brief vom Mailserver angenommen wird und nicht im Posteingang des Empfängers zugestellt wird.
mail.operation.failed- Der Vorgang ist fehlgeschlagen.
mail.operation.uncertain- Das Sendeergebnis ist unbekannt. Bitte überprüfen Sie den Zustand, bevor Sie es erneut senden.
Zahlungserinnerungen: 14, 7, 3, 2, 1 Tag und eine Stunde vor Ablauf. Durch die Verlängerung werden veraltete Erinnerungen, die noch nicht gesendet wurden, storniert.