Retry-Logik

Wenn eine Webhook-Zustellung fehlschlägt, versucht MailLand es automatisch mit zunehmenden Verzögerungen erneut. Diese Seite behandelt den Wiederholungsplan, Zustellstatus, Fehlerbehandlung und wie Sie Zustellungen überwachen und manuell erneut versuchen können.

WiederholungsplanLink zum Abschnitt kopieren

Dieser Abschnitt behandelt jedes Ereignis, das der durable dispatcher zustellt: message.*, suppression.*, account.* und inbound.received. Was speziell für eingehende Ereignisse gilt, steht unter Eingehende Zustellungen weiter unten.

MailLand versucht eine fehlgeschlagene Zustellung insgesamt bis zu 6 Mal erneut, mit einer zunehmenden Verzögerung vor jedem Wiederholungsversuch:

Schlägt der 6. Versuch fehl, wird die Zustellung als dauerhaft fehlgeschlagen markiert: es gibt keine weitere Wartezeit und keinen 7. Versuch.

Wiederholbar vs. Nicht-WiederholbarLink zum Abschnitt kopieren

Wiederholbare AntwortenLink zum Abschnitt kopieren

Diese Statuscodes lösen automatische Wiederholungen aus:

• 408 Request Timeout
• 429 Too Many Requests
• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout
• Netzwerkfehler (Timeouts, Socket-Fehler, DNS-Ausfälle)

Nicht-wiederholbare AntwortenLink zum Abschnitt kopieren

Diese Statuscodes werden als dauerhafte Fehler behandelt, kein Wiederholungsversuch:

• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• Alle anderen 4xx-Fehler (außer 408 und 429)
• Eine Redirect-Antwort, die die Validierung nicht besteht (siehe Weiterleitungen) oder das Hop-Limit überschreitet

WeiterleitungenLink zum Abschnitt kopieren

MailLand behandelt Ihren Endpunkt nicht wie ein Browser. Weiterleitungen werden manuell verfolgt, höchstens 3 Hops, und jeder Hop wird erneut validiert, bevor etwas an ihn gesendet wird:

• das Ziel muss https:// sein: eine Weiterleitung zu http:// wird abgelehnt, nicht herabgestuft;
• das Ziel muss zu einer öffentlichen Adresse aufgelöst werden: eine Weiterleitung zu einer privaten, loopback- oder link-lokalen Adresse wird abgelehnt, und die Anfrage wird nie gesendet;
• das Überschreiten von 3 Hops lässt die Zustellung fehlschlagen.

Eine abgelehnte Weiterleitung wird als Zustellfehler ohne Statuscode gemeldet. Wenn sich Ihr Endpunkt verschoben hat, richten Sie den Webhook auf die neue URL, statt sich auf eine Weiterleitung zu verlassen.

ZustellkonfigurationLink zum Abschnitt kopieren

Eingehende ZustellungenLink zum Abschnitt kopieren

inbound.received wird vom selben durable dispatcher zugestellt wie jedes andere Ereignis, mit demselben Wiederholungsplan, derselben Behandlung von Retry-After, demselben Zustellverlauf und derselben automatischen Pausierung wie oben beschrieben.

• Deduplizieren Sie wie bei jedem anderen Ereignis anhand von event_id (identisch mit X-MLND-Event-Id). Die ID ist pro eingehender Nachricht und Webhook stabil, sodass jeder Versuch für dieselbe E-Mail dieselbe ID trägt.
• Ein manueller Replay ist ein neues Ereignis: eine neue event_id, die ursprüngliche steht in data.replay_of. data.idempotency_key bleibt gleich.
• Die download_url jedes Anhangs wird pro Versuch signiert und ist ab dann 15 Minuten gültig; die id des Anhangs ist bei jedem Versuch dieselbe. Siehe Eingehende Webhooks.

Zustellverlauf anzeigenLink zum Abschnitt kopieren

Anzeigen der vergangenen Zustellungen für einen Webhook:

GET https://api.mail.land/v1/webhooks/{id}/deliveries

curl -X GET "https://api.mail.land/v1/webhooks/wh_abc123/deliveries?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

AbfrageparameterLink zum Abschnitt kopieren

{
  "items": [
    {
      "publicId": "p8r2kx7m9wq4rtz",
      "eventType": "message.delivered",
      "messageId": "t_a1b2c3d4e5f6",
      "statusCode": 200,
      "responseTimeMs": 145,
      "success": true,
      "errorMessage": null,
      "createdAt": "2026-02-17T12:34:58.000Z",
      "attemptNumber": 1
    },
    {
      "publicId": "p8r2kx7m3nq1abc",
      "eventType": "message.bounced",
      "messageId": "t_d4e5f6a1b2c3",
      "statusCode": 503,
      "responseTimeMs": 15000,
      "success": false,
      "errorMessage": "Service Unavailable",
      "createdAt": "2026-02-17T12:30:00.000Z",
      "attemptNumber": 3
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Eine fehlgeschlagene Zustellung erneut versuchenLink zum Abschnitt kopieren

Versuchen Sie eine bestimmte fehlgeschlagene Zustellung manuell erneut:

POST https://api.mail.land/v1/webhooks/{id}/deliveries/{publicId}/retry

curl -X POST https://api.mail.land/v1/webhooks/wh_abc123/deliveries/p8r2kx7m3nq1abc/retry \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Gibt bei Erfolg 202 Accepted zurück. Der Wiederholungsversuch wird in die Warteschlange eingereiht und verwendet die ursprüngliche Ereignis-Payload.

Automatische Pause bei FehlernLink zum Abschnitt kopieren

Wenn ein Webhook genügend aufeinanderfolgende fehlgeschlagene Zustellversuche ansammelt, pausiert MailLand ihn automatisch. Die Schwelle ist der eigene pauseThreshold des Webhooks, falls dieser auf einen Wert größer als 0 gesetzt ist, sonst der Standardwert von 10 aufeinanderfolgenden fehlgeschlagenen Zustellversuchen:

1. Das isActive des Webhooks wird auf false gesetzt, und pausedAt / pausedReason werden befüllt: pausedReason nennt die Anzahl der Fehler und den letzten Fehler
2. Eine In-App-Benachrichtigung wird erstellt
3. Bis zur Wiederaufnahme des Webhooks werden keine weiteren Ereignisse zugestellt

Der Zähler zählt Versuche, nicht Ereignisse: Ein Ereignis, das seine gesamte Wiederholungs-Leiter ausschöpft, trägt mehrere Fehler bei.

Es gibt keine frühere Warnbenachrichtigung, bevor die Schwelle erreicht wird: prüfen Sie consecutiveFailures proaktiv (siehe Best Practices unten), statt darauf zu warten, informiert zu werden.

Einen pausierten Webhook fortsetzenLink zum Abschnitt kopieren

POST https://api.mail.land/v1/webhooks/{id}/resume

curl -X POST https://api.mail.land/v1/webhooks/wh_abc123/resume \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Dies aktiviert den Webhook wieder: Es löscht den Pausenstatus, setzt den Zähler für aufeinanderfolgende Fehler auf null zurück und setzt ihn wieder auf aktiv. Der nächste Ereigniszustellversuch wird normal durchgeführt.

Best PracticesLink zum Abschnitt kopieren

• Geben Sie 200 schnell zurück: verarbeiten Sie Webhook-Payloads asynchron. Stellen Sie das Ereignis in die Warteschlange und geben Sie sofort 200 zurück. Langwierige Handler riskieren Timeouts.
• Verwenden Sie die Ereignis-ID für die idempotente Verarbeitung: der Header X-MLND-Event-Id (und das entsprechende event_id-Feld in den Nutzdaten) ist über Wiederholungen und erneute Zustellungen hinweg stabil: dasselbe zugrunde liegende Ereignis kommt immer mit derselben ID an, egal wie oft es erneut zugestellt wird. Speichern Sie verarbeitete IDs und überspringen Sie bereits bearbeitete, sodass eine doppelte Zustellung bei Ihnen ein No-op ist.
• Überwachen Sie aufeinanderfolgende Fehler: prüfen Sie das Feld consecutiveFailures beim Auflisten von Webhooks. Untersuchen Sie die Ursache, bevor die automatische Pause-Schwelle erreicht wird.
• Behandeln Sie 429 korrekt: wenn Ihr Endpunkt überlastet ist, geben Sie 429 mit einem Retry-After-Header zurück. MailLand wird dies respektieren.

Nächste SchritteLink zum Abschnitt kopieren

• Signaturverifizierung: Webhook-Authentizität überprüfen
• Ereignisse: vollständige Ereignistyprreferenz
• Webhooks-Übersicht: Webhooks erstellen und verwalten