Zum Inhalt springen
Alpha auf Einladung. Funktionen und Grenzen können sich durch unsere Testerfahrungen ändern.

Fehler und Zustände behandeln

Wenn etwas schiefgeht, zählen zwei Fragen: Was ist passiert, und ist ein neuer Versuch sicher? weneed.email beantwortet beide mit einem Grundcode, einer Kategorie und einer Wiederholungsregel. Dieselben Codes erscheinen in Control, in der API und in Webhooks.

Jede Nachricht hat einen Einlieferungszustand (was weneed.email mit ihr getan hat) und ein Empfängerergebnis (was der empfangende Mailserver gemeldet hat). Beide ändern sich unabhängig voneinander, und keines beweist die Zustellung in den Posteingang.

Einlieferungszustand
accepted ─► queued ─► dispatching ─► submitted
│ ▲ │
│ └─ retry_wait ◄─┤ der Server bat um einen späteren Versuch
▼ ├─► submission_unknown Antwort verloren; nie neu gesendet
held └─► rejected wird nicht erneut versucht
│
queued, held oder retry_wait können auch so enden: expired · cancelled · suppressed
Empfängerergebnis
pending ─► delivered_to_server ─► (eine spätere Bounce-Meldung ist weiterhin möglich)
├─► bounced
├─► delivery_unknown
└─► suppressed

email.delivery_delayed ist kein Schritt auf einer der Spuren: Der Server hat eine Verzögerung gemeldet und versucht es weiter, das Ergebnis bleibt pending.

Jeder Grundcode hat genau eine Kategorie. Sie sagt, wer als Nächstes handelt.

Kategorie Bedeutung Tun
wait weneed.email oder der empfangende Server arbeitet noch daran. Noch nichts. Beobachten Sie die Nachricht oder ihre Webhooks.
fix Etwas auf Ihrer Seite muss sich ändern, etwa die Adresse, der Inhalt oder eine Einstellung. Beheben Sie es und senden Sie bei Bedarf eine neue Nachricht.
contact_support Nur weneed kann es lösen, etwa eine Zurückhaltung. Schreiben Sie mit der Nachrichten-ID an den Support.
none Es ist nichts falsch. Nichts.
Regel Bedeutung
safe_same_key Wiederholen Sie dieselbe Anfrage mit demselben Idempotency-Key. Sie erhalten das ursprüngliche Ergebnis, nie eine zweite Nachricht.
do_not_resend Senden Sie die Nachricht nicht erneut. Sie kann schon angekommen sein oder nach einer Freigabe noch gesendet werden. Eine Kopie könnte doppelt ankommen.
not_applicable Es gibt nichts zu wiederholen.

API-Fehler haben eigene drei Regeln: safe_same_key, after_change (erst die Anfrage korrigieren) und never (eine Wiederholung kann nicht gelingen). Siehe API-Fehler.

  • Control: Die Nachrichtenseite zeigt Reason for this status, und der Verlauf zeigt den Grund jeder Zurückhaltung, jedes neuen Versuchs und jedes Versandversuchs.
  • API: GET /v1/emails/{id} liefert reason mit code, category und retry.
  • Webhooks: data.reason enthält dieselben drei Felder, festgehalten zum Zeitpunkt des Ereignisses.

Jeden Code finden Sie unter Ursachencodes. Ein unbekannter Code wird nie verborgen: Behandeln Sie ihn als contact_support und do_not_resend.

  • ?Unklar heißt unklar. Senden Sie eine Nachricht mit unklarem Ergebnis nie erneut; warten Sie auf eine Zustellmeldung oder wenden Sie sich an den Support.
  • Ein Webhook ist nie ein Grund, eine E-Mail erneut zu senden.
  • Ein 429 nennt sein Limit in error.reason. Warten Sie Retry-After ab, wenn vorhanden, und wiederholen Sie dann mit demselben Schlüssel. Ohne Retry-After hilft Warten nicht.
  • Ein dauerhafter Bounce sperrt die Adresse für Ihren ganzen Workspace. Korrigieren Sie die Adresse in Ihrer App; umgehen Sie die Sperre nicht. Siehe Bounces.