Webhook-Ereignisse

Der Ereigniskatalog von MailLand definiert 21 Ereignistypen in 6 Kategorien (2 der 21 sind Plattformhinweise, die Sie nicht abonnieren können). Jedes Ereignis wird als signierter HTTP-POST-Request an Ihren Webhook-Endpunkt zugestellt.

EreigniskatalogLink zum Abschnitt kopieren

Rufen Sie den vollständigen Ereigniskatalog programmatisch ab:

GET https://api.mail.land/v1/webhooks/catalog

curl -X GET https://api.mail.land/v1/webhooks/catalog

{
  "version": 1,
  "products": [
    { "id": "transactional", "name": "Transactional Email", "isActive": true, "comingSoon": false },
    { "id": "marketing", "name": "Marketing Email", "isActive": true, "comingSoon": false },
    { "id": "inbound", "name": "Inbound Email", "isActive": true, "comingSoon": false },
    { "id": "system", "name": "System Events", "isActive": true, "comingSoon": false },
    { "id": "validation", "name": "Email Validation", "isActive": false, "comingSoon": true }
  ],
  "categories": [
    {
      "id": "message",
      "name": "Message Events",
      "events": [
        { "id": "message.sent", "name": "Message Sent", "products": ["transactional", "marketing"] },
        { "id": "message.delivered", "name": "Message Delivered", "products": ["transactional", "marketing"] }
      ]
    }
  ]
}

Dieser Endpunkt ist öffentlich (keine Authentifizierung erforderlich) und liefert immer die aktuellste Katalogversion.

Standardmäßige DatenstrukturLink zum Abschnitt kopieren

Jede Webhook-Zustellung enthält eine einheitliche äußere Struktur:

{
  "event": "message.delivered",
  "event_id": "evt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
  "timestamp": "2026-02-17T12:34:56.789Z",
  "occurred_at": "2026-02-17T12:34:56.120Z",
  "schema_version": 1,
  "data": {
    // Event-specific fields
  }
}

Der data-Teil jedes Nachrichtenereignisses enthält außerdem status_version, status, previous_status, complaint_status und reason, siehe Statusversionen.

StatusversionenLink zum Abschnitt kopieren

Jedes Nachrichtenereignis enthält data.status_version, data.status, data.previous_status, data.complaint_status und data.reason. status_version steigt um eins, jedes Mal wenn MailLand ein Ereignis für eine Änderung des Status, des Grundes oder des Beschwerdestatus der Nachricht sendet.

Zwei Ausnahmen:

• Eine Nachricht beginnt mit status_version 0, solange sie queued oder sent ist. Der Schritt von queued zu sent sendet kein Ereignis und ändert die Version nicht.
• Mehrere message.deferred-Ereignisse können dieselbe status_version haben: Eine wiederholte Verzögerung ändert den Status nicht.

Webhooks können in anderer Reihenfolge ankommen und wiederholt werden. Wenden Sie sie daher nach status_version an, nie nach Eingangsreihenfolge.

Ein Status kann sich ändern, nachdem er endgültig war. MailLand meldet, was es weiß, sobald es es weiß. Erfährt es später mehr, sendet es den neueren Status mit einer höheren status_version:

• Eine zugestellte Nachricht kann später bouncen, wenn der Server des Empfängers sie nachträglich ablehnt (ein Out-of-Band-Bounce);
• nach einem internen Fehler oder nachdem der Mailserver von MailLand sich erholt hat, kann eine Zustellung oder eine Ablehnung verspätet gemeldet werden. Eine failed-Nachricht kann dann bounced oder delivered werden, eine bounced-Nachricht delivered, und eine unknown-Nachricht jeder endgültige Status.

Eine Nachricht geht nie von delivered zu failed. MailLand zählt diese Korrekturen.

WiederholungsfristenLink zum Abschnitt kopieren

MailLand versucht eine verzögerte Nachricht bis zu ihrer Wiederholungsfrist erneut zuzustellen: etwa 5 Stunden, nachdem sie erstmals an die Zustellwarteschlange übergeben wurde, bei Transaktionsmails und etwa 25 Stunden bei Marketingmails. Nach der Frist stellt MailLand die Nachricht für keinen neuen Zustellversuch mehr in die Warteschlange. Eine Kopie, die zum Fristende bereits auf eine Verbindung wartete, kann danach noch versucht werden. Das sind Wiederholungsfristen, keine Zusagen, wann Sie das endgültige Ereignis erhalten. Sie erhalten jedes Ereignis, sobald das Ergebnis MailLand erreicht; diese Verzögerung ist noch nicht gemessen und kann bei einem internen Ausfall länger sein. Eine Nachricht, die MailLand nicht innerhalb von 24 Stunden an seine Zustellwarteschlange übergeben konnte, wird als expired beendet.

Wenn Sie den aktuellen Status einer Nachricht aus Webhooks führen (Handlungsbedarf)Link zum Abschnitt kopieren

Dies ist eine Verhaltensänderung für bestehende Integrationen. Eine Integration, die message.failed oder message.delivered als endgültig behandelt und spätere Ereignisse ignoriert, kann nach einer Korrektur einen falschen Status behalten. Bestehende Ereignisnamen haben jetzt neue mögliche Abfolgen.

• Abonnieren Sie jedes Nachrichtenereignis: message.delivered, message.deferred, message.bounced, message.failed, message.complained, message.outcome_unknown und message.retried. Nur dann enthalten die empfangenen Ereignisse jede Statusänderung.
• Speichern Sie status_version zusammen mit dem Status. Wenden Sie ein Ereignis nur an, wenn seine status_version höher ist als die gespeicherte; ein message.deferred mit gleicher Version ändert nichts.
• Verarbeiten Sie Ereignisse nach message.failed, message.bounced oder message.delivered weiter: Ein späteres Ereignis mit höherer status_version ersetzt den früheren Status.
• Sobald Sie jedes Ereignis bis zur status_version der API erhalten haben, entspricht Ihr Status dem der API. Die API kann den bisher empfangenen Webhooks voraus sein, und bei status_version 0 kann sie sent ohne Ereignis zeigen.

Wenn Sie nur einige Nachrichtenereignisse abonnieren, ist die höchste empfangene status_version nicht unbedingt der aktuelle Status: Ein nicht abonnierter Ereignistyp kann ihn geändert haben. Lesen Sie den aktuellen Status aus der API, zum Beispiel für jede Nachricht, deren zuletzt empfangenes Ereignis message.failed, message.bounced oder message.outcome_unknown ist, und gleichen Sie ab.

Wenn Sie Ihre Integration nicht ändern können, fragen Sie den Status der für Sie wichtigen Nachrichten über die API ab. Integrationen, die Ereignisse nur zählen oder nur einen Verlauf anzeigen, brauchen keine Änderung.

NachrichtenereignisseLink zum Abschnitt kopieren

message.sentLink zum Abschnitt kopieren

Illustrativ: noch nicht ausgelöst. Dieses Ereignis ist katalogisiert, hat aber heute keinen Erzeuger.

{
  "event": "message.sent",
  "event_id": "evt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
  "timestamp": "2026-02-17T12:34:56.789Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:34:56.789Z"
  }
}

message.deliveredLink zum Abschnitt kopieren

Ausgelöst, wenn die E-Mail erfolgreich an den Mailserver des Empfängers zugestellt wurde.

Dieses Ereignis kann auch als Korrektur nach einem früheren endgültigen Status derselben Nachricht eintreffen. Siehe Statusversionen.

{
  "event": "message.delivered",
  "event_id": "evt_b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "timestamp": "2026-02-17T12:34:58.123Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:34:58.123Z",
    "smtp_response": "OK",
    "status_version": 1,
    "status": "delivered",
    "previous_status": "sent",
    "complaint_status": "none",
    "reason": null
  }
}

message.deferredLink zum Abschnitt kopieren

Ausgelöst, wenn die Zustellung vorübergehend verzögert ist. MailLand versucht es automatisch erneut.

Eine Nachricht kann mehrmals verzögert werden. Die erste Verzögerung erhöht status_version; wiederholte Verzögerungen tragen dieselbe status_version.

{
  "event": "message.deferred",
  "event_id": "evt_c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
  "timestamp": "2026-02-17T12:35:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:35:00.000Z",
    "smtp_response": "Try again later",
    "bounce_reason": "TransientFailure"
  }
}

message.bouncedLink zum Abschnitt kopieren

Ausgelöst, wenn eine E-Mail unzustellbar ist (Hard- oder Soft-Bounce).

Dieses Ereignis kann auch als Korrektur nach einem früheren endgültigen Status derselben Nachricht eintreffen. Siehe Statusversionen.

{
  "event": "message.bounced",
  "event_id": "evt_d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
  "timestamp": "2026-02-17T12:35:01.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:35:01.000Z",
    "bounce_type": "hard",
    "bounce_reason": "InvalidRecipient",
    "smtp_response": "The email account that you tried to reach does not exist.",
    "status_version": 1,
    "status": "bounced",
    "previous_status": "sent",
    "complaint_status": "none",
    "reason": "InvalidRecipient"
  }
}

bounce_reason ist das Klassifizierungstoken, das MailLand dem Bounce zuweist (z. B. InvalidRecipient, QuotaIssues, SpamBlock), nicht der rohe SMTP-Text, dafür smtp_response verwenden. bounce_type ist eines von hard, soft, blocked oder unknown.

smtp_response ist der Antworttext des empfangenden Servers, ohne numerischen Antwortcode und erweiterten Statuscode. bounce_type sagt, was MailLand mit der Adresse getan hat: hard, für alle E-Mails unterdrückt; soft, 30 Tage lang für Marketing-E-Mails unterdrückt; blocked, die Ablehnung betraf den Versand, nicht die Adresse (etwa Spamfilter, Absenderauthentifizierung, Reputation oder die Richtlinie des Empfängers), daher wird nichts unterdrückt; unknown, keine Klassifizierung, wird wie soft behandelt.

message.failedLink zum Abschnitt kopieren

Wird ausgelöst, wenn MailLand eine Nachricht auf Grundlage eindeutiger Belege beendet, dass sie nicht zugestellt wurde, aus einem Grund auf Seiten von MailLand und nicht beim Empfänger. In den unter Statusversionen beschriebenen Fällen kann später ein message.delivered oder message.bounced mit höherer status_version folgen. Der Status der Nachricht wird Failed, nicht Bounced, und reason nennt den Fall:

• Der Empfänger wird nicht unterdrückt, und der Fehlschlag zählt nicht zu Ihrer Bounce-Rate.
• Eine Nachricht erzeugt höchstens ein message.failed. Es ist das letzte Ereignis dieser Nachricht, es sei denn, MailLand erhält später eine Zustellung oder eine Ablehnung; dann folgt ein message.delivered oder message.bounced mit höherer status_version.

Eine Ablehnung durch den empfangenden Mailserver wird als message.bounced gemeldet, nie als message.failed.

{
  "event": "message.failed",
  "event_id": "evt_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "timestamp": "2026-09-28T02:00:19.1047332Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-09-28T02:00:18.2522997Z",
    "reason": "dkim_revoked",
    "smtp_response": "Next delivery time PT3.028008S > PT1S",
    "status_version": 1,
    "status": "failed",
    "previous_status": "sent",
    "complaint_status": "none"
  }
}

message.outcome_unknownLink zum Abschnitt kopieren

Wird ausgelöst, wenn MailLand nicht feststellen kann, ob eine Nachricht seine Zustellwarteschlange erreicht hat, zum Beispiel weil die Übergabe unterbrochen wurde und sich danach nicht klären ließ. Es wird einige Zeit nach der Wiederholungsfrist der Nachricht gesendet, derzeit 7 Tage, wenn bis dahin kein Beleg eingetroffen ist. Dies ist kein endgültiger Status. Der Status wird unknown. Erfährt MailLand das Ergebnis später, erhalten Sie message.delivered, message.bounced oder message.failed mit höherer status_version.

{
  "event": "message.outcome_unknown",
  "event_id": "evt_0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d",
  "timestamp": "2026-10-08T17:05:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-10-08T17:05:00.000Z",
    "status_version": 1,
    "status": "unknown",
    "previous_status": "queued",
    "complaint_status": "none",
    "reason": "handoff_undetermined"
  }
}

message.retriedLink zum Abschnitt kopieren

Wird ausgelöst, wenn Sie eine gebouncte oder fehlgeschlagene Nachricht erneut versuchen und MailLand sie wieder in die Warteschlange stellt. Der Status wird queued und status_version steigt; die Ereignisse der erneut gesendeten Kopie folgen mit höheren Versionen. Dies ist kein endgültiger Status.

{
  "event": "message.retried",
  "event_id": "evt_1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e",
  "timestamp": "2026-10-01T18:00:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-10-01T18:00:00.000Z",
    "attempt": 1,
    "status_version": 2,
    "status": "queued",
    "previous_status": "bounced",
    "complaint_status": "none",
    "reason": null
  }
}

InteraktionsereignisseLink zum Abschnitt kopieren

message.openedLink zum Abschnitt kopieren

Illustrativ: nicht verfügbar.

{
  "event": "message.opened",
  "event_id": "evt_f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "timestamp": "2026-02-17T13:15:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T13:15:00.000Z"
  }
}

message.clickedLink zum Abschnitt kopieren

Illustrativ: nicht verfügbar.

{
  "event": "message.clicked",
  "event_id": "evt_g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1",
  "timestamp": "2026-02-17T13:16:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T13:16:00.000Z"
  }
}

message.unsubscribedLink zum Abschnitt kopieren

Wird ausgelöst, wenn sich ein Empfänger von einer Nachricht abmeldet, die Sie gesendet haben: über deren List-Unsubscribe-Header oder mailto:-Adresse, den One-Click-POST, den Abmeldelink oder die Präferenzseite. Er wird nicht ausgelöst, wenn Sie selbst über die API oder das Dashboard abmelden, und nicht bei Spam-Beschwerden (message.complained). Er wird einmal pro Nachricht gesendet, im selben Moment, in dem der Empfänger abgemeldet wird, an jeden Endpunkt, der ihn abonniert hat. Wie jedes Nachrichtenereignis enthält data außerdem die aktuellen Statusfelder der Nachricht (siehe Status-Versionen).

{
  "event": "message.unsubscribed",
  "event_id": "evt_h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2",
  "timestamp": "2026-02-17T14:00:00.000Z",
  "data": {
    "message_id": "m_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T14:00:00.000Z",
    "status_version": 3,
    "status": "delivered",
    "previous_status": "queued",
    "complaint_status": "none",
    "reason": null
  }
}

UnterdrückungsereignisseLink zum Abschnitt kopieren

message.complainedLink zum Abschnitt kopieren

Ausgelöst, wenn ein Empfänger die E-Mail als Spam markiert (ISP-Feedback-Loop).

{
  "event": "message.complained",
  "event_id": "evt_i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3",
  "timestamp": "2026-02-17T15:00:00.000Z",
  "data": {
    "message_id": "m_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T15:00:00.000Z",
    "feedback_type": "abuse"
  }
}

suppression.addedLink zum Abschnitt kopieren

Illustrativ: noch nicht ausgelöst. Dieses Ereignis ist katalogisiert, hat aber heute keinen Erzeuger.

{
  "event": "suppression.added",
  "event_id": "evt_j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4",
  "timestamp": "2026-02-17T15:00:01.000Z",
  "data": {
    "email": "[email protected]",
    "type": "complaint",
    "scope": "global",
    "reason": "Spam complaint via ISP feedback loop"
  }
}

suppression.removedLink zum Abschnitt kopieren

Illustrativ: noch nicht ausgelöst. Dieses Ereignis ist katalogisiert, hat aber heute keinen Erzeuger.

{
  "event": "suppression.removed",
  "event_id": "evt_k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5",
  "timestamp": "2026-02-17T16:00:00.000Z",
  "data": {
    "email": "[email protected]",
    "type": "manual",
    "scope": "global"
  }
}

Eingehende EreignisseLink zum Abschnitt kopieren

inbound.receivedLink zum Abschnitt kopieren

Ausgelöst, wenn eine eingehende E-Mail auf einer Ihrer Domains empfangen wird.

{
  "event": "inbound.received",
  "event_id": "evt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "timestamp": "2026-02-17T12:00:00.000Z",
  "occurred_at": "2026-02-17T12:00:00.000Z",
  "schema_version": 1,
  "data": {
    "idempotency_key": "r7n2k5x9m1p4w6_s5m3x8k1p7n4w2",
    "email": {
      "id": "r7n2k5x9m1p4w6",
      "received_at": "2026-02-17T12:00:00.000Z",
      "size_bytes": 4521,
      "envelope": {
        "from": "[email protected]",
        "to": ["[email protected]"]
      },
      "headers": {
        "from": { "address": "[email protected]", "name": "Jane Doe" },
        "to": [{ "address": "[email protected]" }],
        "subject": "Help with my order",
        "message_id": "<[email protected]>",
        "date": "2026-02-17T11:59:50.000Z"
      },
      "body": {
        "text_preview": "Hi, I need help with...",
        "has_text": true,
        "has_html": true
      },
      "attachments": [],
      "authentication": {
        "spf": { "result": "pass" },
        "dkim": { "result": "pass" },
        "dmarc": { "result": "pass" }
      },
      "spam": {
        "score": 0.1,
        "is_spam": false,
        "reason": null
      },
      "source": {
        "ip": "203.0.113.10",
        "hostname": "mail.external.com"
      }
    },
    "matched_route": {
      "id": "s5m3x8k1p7n4w2",
      "name": "Support inbox"
    }
  }
}

KontoereignisseLink zum Abschnitt kopieren

account.webhook_pausedLink zum Abschnitt kopieren

Ausgelöst, wenn ein Webhook aufgrund aufeinanderfolgender Fehlschläge automatisch pausiert wird.

{
  "event": "account.webhook_paused",
  "event_id": "evt_m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7",
  "timestamp": "2026-02-17T18:00:00.000Z",
  "data": {
    "webhook_id": "z8m3p1k6x4w2n7",
    "webhook_name": "Production Events",
    "consecutive_failures": 10,
    "last_error": "Connection refused"
  }
}

account.domain_verifiedLink zum Abschnitt kopieren

Illustrativ: noch nicht ausgelöst. Dieses Ereignis ist katalogisiert, hat aber heute keinen Erzeuger.

{
  "event": "account.domain_verified",
  "event_id": "evt_n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8",
  "timestamp": "2026-02-17T10:15:00.000Z",
  "data": {
    "domain_id": "q3z8v1k6m9p2x5",
    "domain": "yourdomain.com"
  }
}

account.domain_failedLink zum Abschnitt kopieren

Illustrativ: noch nicht ausgelöst. Dieses Ereignis ist katalogisiert, hat aber heute keinen Erzeuger.

{
  "event": "account.domain_failed",
  "event_id": "evt_o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9",
  "timestamp": "2026-02-17T10:15:00.000Z",
  "data": {
    "domain_id": "q3z8v1k6m9p2x5",
    "domain": "yourdomain.com",
    "reason": "DKIM record not found for selector mlnd"
  }
}

account.quota_warningLink zum Abschnitt kopieren

Illustrativ: noch nicht ausgelöst. Dieses Ereignis ist katalogisiert, hat aber heute keinen Erzeuger.

{
  "event": "account.quota_warning",
  "event_id": "evt_p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0",
  "timestamp": "2026-02-17T20:00:00.000Z",
  "data": {
    "used": 45000,
    "limit": 50000,
    "percentage": 90
  }
}

account.quota_exceededLink zum Abschnitt kopieren

Illustrativ: noch nicht ausgelöst. Dieses Ereignis ist katalogisiert, hat aber heute keinen Erzeuger.

{
  "event": "account.quota_exceeded",
  "event_id": "evt_q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1",
  "timestamp": "2026-02-17T22:00:00.000Z",
  "data": {
    "used": 50000,
    "limit": 50000,
    "percentage": 100
  }
}

EreignisübersichtLink zum Abschnitt kopieren

„Verfügbar" ist das availableNow-Flag des Katalogs: ob heute überhaupt etwas dieses Ereignis auslöst. Nur verfügbare Ereignisse dürfen in einem Abonnement enthalten sein.

Zukünftige EreignisseLink zum Abschnitt kopieren

Wenn includeFutureEvents true ist (Standard), erhält Ihr Webhook automatisch neue Ereignistypen, sobald sie zu Ihren abonnierten Produkten hinzugefügt werden. Setzen Sie es auf false, um Ihr Abonnement auf den aktuellen Ereignisstand festzulegen.

Die oben mit „Noch nicht" markierten Ereignisse werden abonnierbar, sobald ihre Erzeuger ausgeliefert werden: Die hier dokumentierten Ereignisnamen und Nutzdatenstrukturen ändern sich dann nicht.

Nächste SchritteLink zum Abschnitt kopieren

• Signaturprüfung: Ereignisse als von MailLand stammend verifizieren
• Logik für Wiederholungsversuche: Wiederholungsverhalten verstehen
• Webhook-Übersicht: Webhooks erstellen und verwalten