Zum Inhalt springen
Doku

Anleitung

Idempotente Anfragen

Wiederholen Sie Sende- und Weiterleitungsanfragen sicher mit dem Header Idempotency-Key. Schlüsselformat, das 24-Stunden-Fenster, Wiederholungen, die Antworten 409 und 503 sowie Strategien für Schlüssel.

Aktualisiert am 1. Okt. 2026

Netzwerke fallen aus. Wenn eine Sendeanfrage in ein Timeout läuft, wissen Sie nicht, ob Emailit sie erhalten hat, und ein erneutes Senden könnte Ihrem Kunden die E-Mail zweimal zustellen. Ein Header Idempotency-Key macht die Wiederholung sicher: Emailit verarbeitet die erste Anfrage und gibt für jede Wiederholung mit demselben Schlüssel dieselbe Antwort zurück.

So funktioniert es

Fügen Sie POST /emails oder POST /emails/{id}/forward einen Header Idempotency-Key hinzu.

  1. Erste Anfrage. Emailit reserviert den Schlüssel für Ihren Workspace und verarbeitet die Anfrage.
  2. Erfolg. Emailit speichert die Antwort 24 Stunden lang. Jede Anfrage mit demselben Schlüssel in diesem Zeitfenster erhält die gespeicherte Antwort mit 200 zurück, und es wird keine neue E-Mail erstellt.
  3. Fehlschlag. Schlägt die Anfrage fehl, zum Beispiel mit 400 oder 402, gibt Emailit den Schlüssel wieder frei. Beheben Sie das Problem und wiederholen Sie die Anfrage mit demselben Schlüssel.
  4. Überschneidung. Trifft eine zweite Anfrage ein, während die erste noch läuft, erhält sie 409, und nichts wird gesendet. Wiederholen Sie die Anfrage kurz darauf mit demselben Schlüssel.

Schlüssel gelten pro Workspace, sodass zwei Workspaces denselben Schlüssel ohne Konflikt verwenden können.

Schlüsselformat

Regel Wert
Länge 1 bis 256 Zeichen
Zeichen Buchstaben A–Z und a–z, Ziffern 0–9, Bindestrich - und Unterstrich _
Gültigkeitsbereich Pro Workspace
Zeitfenster 24 Stunden nach der ersten erfolgreichen Antwort

Ein Schlüssel mit anderen Zeichen, etwa : oder /, wird mit 400 Invalid Idempotency-Key abgelehnt.

Schlüssel wählen

Leiten Sie den Schlüssel aus dem Ereignis ab, das die E-Mail auslöst, damit jeder Wiederholungspfad denselben Schlüssel erzeugt:

E-Mail Beispielschlüssel
Bestellbeleg order-1042-receipt
Passwort-Reset password-reset-7f3c9a1e (die ID des Reset-Tokens)
Wöchentlicher Digest digest-user-881-2026-w40
Hintergrundjob Die ID des Jobs oder eine UUID, die Sie beim Einreihen des Jobs erzeugen und mit ihm speichern

Vermeiden Sie Schlüssel, die sich zwischen Versuchen ändern, etwa Zeitstempel oder eine UUID, die in der Wiederholungsschleife erzeugt wird. Sie lassen jede Wiederholung wie eine neue Anfrage aussehen.

Mit Idempotenzschlüssel senden

Die Beispiele für Node.js, Python und PHP wiederholen die Anfrage bei Netzwerkfehlern und bei den Antworten 409, 429 und 5xx und verwenden dabei jedes Mal denselben Schlüssel. Das cURL-Beispiel nutzt die eingebaute Wiederholung von curl, die Timeouts, 429 und die meisten 5xx-Antworten abdeckt.

Terminal
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-receipt" \
  --retry 3 \
  -d '{
    "from": "Acme <orders@acme.com>",
    "to": "ada@example.com",
    "subject": "Receipt for order 1042",
    "text": "Thanks for your order."
  }'

Antworten

Status Wann Was Sie tun
200 Erste erfolgreiche Anfrage oder ihre Wiederholung innerhalb von 24 Stunden Verwenden Sie die Antwort. Eine Wiederholung hat denselben Body, einschließlich derselben id.
400 Invalid Idempotency-Key Der Schlüssel ist leer, zu lang oder enthält ungültige Zeichen Korrigieren Sie den Schlüssel.
409 Idempotency key in progress Eine Anfrage mit demselben Schlüssel wird noch verarbeitet Warten Sie einen Moment und wiederholen Sie die Anfrage dann mit demselben Schlüssel.
503 Idempotency unavailable Emailit konnte seinen Idempotenzspeicher nicht erreichen und hat die Anfrage abgelehnt, statt ein Duplikat zu riskieren Wiederholen Sie die Anfrage mit demselben Schlüssel.
Jeder andere Fehler Die Anfrage ist fehlgeschlagen, und der Schlüssel wurde freigegeben Beheben Sie die Ursache und wiederholen Sie die Anfrage mit demselben Schlüssel.

Rate Limits werden vor dem Schlüssel geprüft, daher kann eine Wiederholung trotzdem 429 erhalten. Warten Sie die im Header retry-after angegebene Zeit ab und senden Sie denselben Schlüssel erneut.

War diese Seite hilfreich?

Danke für Ihr Feedback.

Danke, wir lesen jede Nachricht.