Webhooks und Events
Zustellergebnisse direkt in Ihrer App
Mail.Land sendet ein signiertes Event an Ihren Endpunkt, wenn eine Nachricht zugestellt, verzögert, gebounct oder mit einem Fehler beendet wird, wenn sich ein Empfänger beschwert und wenn eine eingehende E-Mail ankommt, mit einem Protokoll jedes Versuchs.
import crypto from "node:crypto";
// header: X-MLND-Signature: t=1708171200,v1=<hex>
export function verify(rawBody, header, secret) {
if (typeof header !== "string" || header === "") return false;
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const age = Math.abs(Date.now() / 1000 - Number(parts.t));
if (!parts.t || !parts.v1 || age > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Events, die Sie heute abonnieren können
Acht Event-Typen sind aktiv. Abonnieren Sie alle oder nur die, die Sie brauchen.
| Gesendet, wenn | |
|---|---|
| message.delivered | Der Mailserver des Empfängers die Nachricht angenommen hat |
| message.deferred | Die Zustellung vorerst verzögert ist; Mail.Land versucht es weiter |
| message.bounced | Der Server des Empfängers die Nachricht abgewiesen hat, mit Bounce-Art und Antwort |
| message.failed | Mail.Land die Nachricht aus einem internen oder richtlinienbedingten Grund als fehlgeschlagen markiert hat; der Empfänger wird dadurch nicht gesperrt |
| message.complained | Der Empfänger die Nachricht über einen Feedback-Loop als Spam gemeldet hat |
| message.outcome_unknown | Mail.Land noch nicht feststellen konnte, ob die Nachricht die Zustellwarteschlange erreicht hat; ein endgültiges Event folgt, wenn Mail.Land das Ergebnis später erfährt |
| message.retried | Sie eine gebouncte oder fehlgeschlagene Nachricht erneut gesendet haben und sie wieder in der Warteschlange ist |
| inbound.received | Eine E-Mail auf einer Ihrer Domains angekommen ist und zu einer Webhook-Route passt |
Weitere Event-Typen wie message.sent, Öffnungen und Klicks stehen für später im Katalog und werden noch nicht gesendet. Der Katalog-Endpunkt zeigt, welche jetzt verfügbar sind.
Signiert, und nur dorthin, wo es hin soll
Jede Anfrage lässt sich prüfen, und Mail.Land lehnt Ziele ab, die missbraucht werden könnten.
HMAC-SHA256 mit Zeitstempel
Der Header X-MLND-Signature enthält einen Zeitstempel und eine Signatur über diesen Zeitstempel und den Roh-Body. Prüfen Sie sie in konstanter Zeit und lehnen Sie alte Zeitstempel ab, um Wiederholungsangriffe zu verhindern.
Nur HTTPS auf Port 443
Private und Loopback-Adressen werden abgelehnt. Weiterleitungen werden höchstens über drei Stationen verfolgt, und jede Station wird erneut geprüft, bevor etwas an sie gesendet wird.
Ein Geheimnis pro Webhook
Das Signaturgeheimnis wird beim Anlegen des Webhooks einmal angezeigt. Ist es bekannt geworden, erzeugen Sie ein neues: Das alte funktioniert sofort nicht mehr.
Wenn Ihr Endpunkt nicht erreichbar ist
Eine fehlgeschlagene Zustellung wird standardmäßig nach diesem Zeitplan wiederholt. Eine 2xx-Antwort innerhalb von 15 Sekunden gilt als Erfolg.
| Wartezeit vor dem Versuch | Zeit seit dem ersten Versuch | |
|---|---|---|
| Versuch 1 | Keine | 0 |
| Versuch 2 | Sofort | Etwa 0 |
| Versuch 3 | 1 Minute | Etwa 1 Minute |
| Versuch 4 | 5 Minuten | Etwa 6 Minuten |
| Versuch 5 | 15 Minuten | Etwa 21 Minuten |
| Versuch 6 | 1 Stunde | Etwa 1 Stunde 21 Minuten |
Zeitüberschreitungen, Netzwerkfehler sowie Antworten 408, 429, 500, 502, 503 und 504 werden wiederholt, und ein Retry-After-Header legt die nächste Wartezeit fest. Andere Antworten außerhalb von 2xx sind endgültig. Jede fehlgeschlagene Zustellung können Sie im Protokoll erneut auslösen.
Gebaut für Events, die verspätet oder doppelt ankommen
Die Zustellung erfolgt mindestens einmal und nicht immer in Reihenfolge. Jedes Event trägt, was Sie dafür brauchen.
Statusversionen
Jedes Nachrichten-Event trägt eine Statusversion, die mit jeder Änderung steigt. Wenn Sie alle Nachrichten-Events abonnieren und ein Event nur anwenden, wenn seine Version höher ist als die gespeicherte, bleibt Ihr Status richtig, egal in welcher Reihenfolge Events ankommen. Mit weniger Events prüfen Sie den aktuellen Status über die API.
Stabile Event-IDs
Die Event-ID ist bei jeder Wiederholung eines Events gleich. Speichern Sie die verarbeiteten IDs und überspringen Sie Wiederholungen.
Versionierte Payloads
Jeder Event-Typ hat eine Schemaversion. Mail.Land fügt einer bestehenden Version nur Felder und Header hinzu, sodass ein Empfänger, der unbekannte Felder ignoriert, weiter funktioniert.
Kontrolle und Transparenz
Verwalten Sie Webhooks im Dashboard oder über die API.
Nach Produkt und Domain filtern
Wählen Sie Transaktions-, Marketing- oder Inbound-Events, bestimmte Event-Typen und alle Domains oder nur einige.
Testen, bevor Sie sich darauf verlassen
Senden Sie ein Test-Event mit echter Signatur und echtem Transport. Die Antwort zeigt auch, ob echte Events den Endpunkt mit seinem aktuellen Abonnement erreichen können.
Zustellprotokoll
Sehen Sie jeden Versuch mit seinem Status, filtern Sie fehlgeschlagene und wiederholen Sie eine Zustellung von Hand.
Automatische Pause
Nach standardmäßig 10 fehlgeschlagenen Versuchen in Folge wird der Webhook pausiert, und Sie erhalten eine Benachrichtigung im Dashboard. Setzen Sie ihn fort, sobald Ihr Endpunkt wieder läuft.
Fragen zu Webhooks
Gibt es ein Event, wenn eine Nachricht angenommen oder gesendet wird?
Noch nicht. message.sent steht im Katalog, wird aber heute nicht gesendet. Die API-Antwort auf Ihre Sendeanfrage enthält die Nachrichten-IDs, und das erste Webhook-Event ist das Zustellergebnis.
Kann ich Öffnungs- und Klick-Events erhalten?
Heute nicht per Webhook. Öffnungen und Klicks finden Sie, wo das Tracking aktiv ist, in Ihren Logs und Analysen; die Öffnungs- und Klick-Events stehen für später im Katalog.
Was, wenn eine zugestellte Nachricht später bounct?
Das kommt vor: Ein Empfangsserver kann eine Nachricht nach der Annahme noch ablehnen. Mail.Land sendet dann ein Bounce-Event mit höherer Statusversion; verarbeiten Sie also auch nach einem Zustell-Event weiter.
Was passiert, wenn mein Endpunkt einen Tag lang ausfällt?
Jedes Event wird standardmäßig bis zu sechsmal über etwa 80 Minuten versucht, und nach standardmäßig 10 fehlgeschlagenen Versuchen in Folge wird der Webhook pausiert. Solange er pausiert ist, werden keine neuen Events für ihn eingereiht. Wiederholen Sie nach dem Fortsetzen die fehlgeschlagenen Zustellungen im Protokoll, prüfen Sie den Status der Nachrichten über die API und senden Sie verpasste eingehende Nachrichten erneut.
Wie prüfe ich, ob eine Anfrage von Mail.Land stammt?
Berechnen Sie HMAC-SHA256 über Zeitstempel, einen Punkt und den Roh-Body mit Ihrem Webhook-Geheimnis, vergleichen Sie das Ergebnis in konstanter Zeit mit dem Wert v1 und lehnen Sie Zeitstempel ab, die älter als 5 Minuten sind. Die Dokumentation enthält ein Beispiel mit exakten Werten.
Kann ein Endpunkt Events nur für einige meiner Domains erhalten?
Ja. Stellen Sie den Geltungsbereich des Webhooks auf ausgewählte Domains und listen Sie sie auf; er erhält dann nur Events für diese Domains.
Verbinden Sie Ihre App mit jedem Zustellergebnis
Legen Sie ein kostenloses Konto an, fügen Sie einen Endpunkt hinzu und senden Sie ihm ein Test-Event.