Eingehende Webhooks

Wenn eine eingehende E-Mail einer Route entspricht, deren actions webhook enthält, sendet MailLand die geparste E-Mail an den Webhook dieser Route als JSON-POST-Anfrage. Diese Seite beschreibt das Payload-Format, die Signaturprüfung und das Zustellverhalten.

Webhook-PayloadLink zum Abschnitt kopieren

MailLand sendet eine POST-Anfrage an Ihre Webhook-URL mit folgendem JSON-Body:

{
  "event": "inbound.received",
  "event_id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "timestamp": "2026-02-17T14:30:00Z",
  "occurred_at": "2026-02-17T14:29:58Z",
  "schema_version": 1,
  "data": {
    "idempotency_key": "k7m2x9q4p1w8z3_r7k3m9q2p4w8x1",
    "email": {
      "id": "k7m2x9q4p1w8z3",
      "received_at": "2026-02-17T14:29:58Z",
      "size_bytes": 48213,
      "envelope": {
        "from": "[email protected]",
        "to": ["[email protected]"]
      },
      "headers": {
        "from": { "address": "[email protected]", "name": "Jane Customer" },
        "to": [{ "address": "[email protected]", "name": null }],
        "cc": [],
        "subject": "Need help with my account",
        "message_id": "<[email protected]>",
        "in_reply_to": null,
        "reply_to": "[email protected]",
        "date": "2026-02-17T14:29:55Z"
      },
      "body": {
        "text_preview": "I need assistance with my account settings.",
        "has_text": true,
        "has_html": true
      },
      "attachments": [
        {
          "id": "a3k7m2q9p4w1x8",
          "file_name": "screenshot.png",
          "content_type": "image/png",
          "size_bytes": 34500,
          "is_inline": false,
          "content_id": null,
          "download_url": "https://r2.example.com/screenshot.png?X-Amz-Signature=..."
        }
      ],
      "authentication": {
        "spf": { "result": "pass" },
        "dkim": { "result": "pass" },
        "dmarc": { "result": "pass" }
      },
      "spam": {
        "score": 1.2,
        "is_spam": false,
        "reason": null
      },
      "source": {
        "ip": "203.0.113.42",
        "hostname": "mail.example.com"
      }
    },
    "matched_route": {
      "id": "r7k3m9q2p4w8x1",
      "name": "Support Inbox"
    }
  }
}

Der vollständige E-Mail-Text ist nie inline enthalten: nur eine gekürzte text_preview und die Flags has_text/has_html. Es gibt kein Feld body.html.

Felder ohne Wert (name, in_reply_to, content_id, reason, data.matched_route und so weiter) werden vollständig aus dem JSON weggelassen, statt als null gesendet zu werden. Das obige Beispiel zeigt null zur besseren Lesbarkeit; verlassen Sie sich nicht darauf, dass der Schlüssel vorhanden ist.

Payload-FelderLink zum Abschnitt kopieren

AnhängeLink zum Abschnitt kopieren

Anhangsinhalte sind nie inline enthalten. Jeder Eintrag in data.email.attachments enthält eine download_url:

GET https://api.mail.land/v1/transactional/inbound/emails/{emailId}/raw

SignaturprüfungLink zum Abschnitt kopieren

Eingehende Webhooks werden genau wie jeder andere MailLand-Webhook signiert: gleicher Header, gleiches Schema, gleiche Behandlung des Secrets. Die maßgebliche Referenz mit einem durchgerechneten Beispiel und Verifizierungscode in acht Sprachen ist Signature Verification; alles dort gilt hier unverändert.

Kurz zusammengefasst:

X-MLND-Signature: t=1708171200,v1=<hex>

• t ist ein Unix-Zeitstempel in Sekunden, v1 ist ein HMAC-SHA256 in Kleinbuchstaben-Hex;
• der signierte String ist {timestamp}.{raw_body}: der Zeitstempel, ein wörtlicher Punkt, dann der Body genau wie empfangen, vor dem JSON-Parsing;
• der Schlüssel ist das Signierungssecret des Webhooks, das einmalig bei der Erstellung angezeigt wird;
• vergleichen Sie in konstanter Zeit und lehnen Sie einen Zeitstempel ab, der älter als 300 Sekunden ist.

ZustellverhaltenLink zum Abschnitt kopieren

AntwortcodesLink zum Abschnitt kopieren

Ihr Endpunkt muss mit einem 2xx-Statuscode antworten, um den Empfang zu bestätigen. Alles andere, ein Nicht-2xx-Status oder ein Timeout, zählt als fehlgeschlagener Zustellversuch.

WiederholungsrichtlinieLink zum Abschnitt kopieren

Ein fehlgeschlagener Versuch wird nach demselben Zeitplan wiederholt wie jedes andere Webhook-Ereignis, bis zu insgesamt 6 Versuchen pro Ereignis: der erste Versuch, dann Wiederholungen sofort, nach 1 Minute, 5 Minuten, 15 Minuten und 1 Stunde. Nach dem 6. fehlgeschlagenen Versuch wird die Zustellung als dauerhaft fehlgeschlagen markiert. Sie können sie manuell erneut zustellen lassen. Den vollständigen Zeitplan finden Sie unter Wiederholungslogik.

Einen Webhook erneut zustellenLink zum Abschnitt kopieren

Den Webhook für eine bestimmte eingehende E-Mail erneut zustellen:

POST https://api.mail.land/v1/transactional/inbound/emails/{id}/replay-webhook

curl -X POST https://api.mail.land/v1/transactional/inbound/emails/k7m2x9q4p1w8z3/replay-webhook \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "emailId": "k7m2x9q4p1w8z3",
  "queued": true,
  "webhookUrl": "https://yourapp.com/webhooks/support",
  "message": "Webhook replay queued successfully"
}

Dadurch wird eine dauerhafte Zustellung an den Webhook der passenden Route eingereiht, und 202 Accepted wird zurückgegeben, sobald diese Zeile committet ist, es wird nicht synchron gesendet. Der Replay erhält eine neue Ereignis-ID (neue event_id und neuer X-MLND-Event-Id) und führt die ID der ursprünglichen Zustellung in data.replay_of. Ihre Deduplizierung sieht ihn daher als neues Ereignis, Sie können ihn aber weiterhin dem Original zuordnen. data.idempotency_key bleibt gleich wie bei der ursprünglichen Zustellung. Die Anfrage enthält X-MLND-Source: inbound und X-MLND-Inbound-Email-Id; jede download_url eines Anhangs im Payload wird beim Senden signiert und ist ab diesem Zeitpunkt 15 Minuten gültig, nicht ab dem Aufruf des Replays.

Ereignisse deduplizierenLink zum Abschnitt kopieren

Die Zustellung eingehender Webhooks erfolgt mindestens einmal (at-least-once): Ein Wiederholungsversuch, ein Timeout auf Ihrer Seite nach bereits verarbeiteter Anfrage oder eine Übergabe zwischen Workern kann dasselbe Ereignis mehr als einmal zustellen. Empfänger müssen deduplizieren.

• Jeder eingehende Webhook trägt eine stabile Ereignis-ID in event_id und im Header X-MLND-Event-Id. Sie ist pro eingehender Nachricht und Webhook deterministisch, sodass alle Zustellversuche derselben Nachricht an denselben Webhook dieselbe ID haben.
• Deduplizieren Sie anhand dieser ID. Speichern Sie verarbeitete IDs und überspringen Sie jede bereits gesehene.
• Ein manueller Replay ist ein neues Ereignis. Er hat eine neue event_id und ein Feld data.replay_of mit der ursprünglichen ID. Soll ein Replay ignoriert werden, wenn das Original bereits verarbeitet wurde, prüfen Sie zusätzlich data.replay_of gegen Ihre gespeicherten IDs.

app.post("/webhooks/support", express.raw({ type: "application/json" }), async (req, res) => {
  // 1. Verify X-MLND-Signature first (see Signature Verification).
  const eventId = req.header("X-MLND-Event-Id");
  const client = await db.connect();
  try {
    await client.query("BEGIN");
    // 2. Record the event id; the unique constraint makes this atomic.
    const inserted = await client.query(
      "INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT (event_id) DO NOTHING",
      [eventId],
    );
    // 3. Only a first-time id enqueues work, in the SAME transaction (jobs table).
    if (inserted.rowCount > 0) {
      await client.query("INSERT INTO jobs (kind, payload) VALUES ($1, $2)", [
        "process-inbound-email",
        req.body.toString(),
      ]);
    }
    await client.query("COMMIT");
    res.sendStatus(200); // new or duplicate: acknowledge
  } catch (err) {
    await client.query("ROLLBACK"); // id and job are both undone, so the retry is not a "duplicate"
    res.sendStatus(500);
  } finally {
    client.release();
  }
});

Die ID und das Einreihen der Arbeit in einer Transaktion zu speichern ist wichtig: Würde die ID zuerst gespeichert und das Einreihen schlüge fehl, würde der Wiederholungsversuch von MailLand als Duplikat übersprungen und die E-Mail ginge verloren.

Bewahren Sie verarbeitete IDs mindestens so lange auf wie Ihr längstes Wiederholungsfenster plus jeden Replay, den Sie auslösen könnten.

Webhook-HeaderLink zum Abschnitt kopieren

Jede Webhook-Anfrage enthält folgende Header:

Best PracticesLink zum Abschnitt kopieren

• Schnell antworten: bestätigen Sie den Webhook sofort mit 200 und verarbeiten Sie die E-Mail asynchron in einem Hintergrundjob.
• Signaturen prüfen: validieren Sie immer den X-MLND-Signature-Header, um gefälschte Payloads zu verhindern.
• Duplikate behandeln: die Zustellung erfolgt mindestens einmal, daher per X-MLND-Event-Id (die event_id im Payload) deduplizieren. Ein manueller Replay hat eine neue ID und data.replay_of verweist auf die ursprüngliche; siehe Ereignisse deduplizieren.
• Anhänge sofort herunterladen: jede download_url läuft 15 Minuten nach Erzeugung des Payloads ab; danach die Rohnachricht abrufen.
• HTTPS verwenden: Webhook-URLs müssen in Produktion HTTPS verwenden, um die Payload-Zustellung abzusichern.

FehlerantwortenLink zum Abschnitt kopieren

Nächste SchritteLink zum Abschnitt kopieren

• Inbound Overview: Einstellungen für eingehende E-Mails konfigurieren und E-Mails anzeigen
• Inbound Routes: Routing-Regeln für die Webhook-Zustellung einrichten
• Webhooks: Konfiguration ausgehender Webhooks für E-Mail-Ereignisse