Technik · belegte Antwort
Idempotenzschlüssel: Doppelten E-Mail-Versand verhindern
Ein Idempotenzschlüssel ist ein eindeutiger Wert, den ein Client erzeugt und in einer API-Anfrage mitsendet, damit ein Vorgang genau einmal ausgeführt wird. Wird eine Anfrage mit demselben Schlüssel wiederholt, erkennt der Server das Duplikat und gibt die ursprüngliche Antwort zurück, ohne die Aktion erneut auszuführen.
Funktionsweise
Sendet ein Client eine Anfrage mit einem Idempotenzschlüssel, speichert der Server den Schlüssel und die daraus resultierende Antwort in einem Cache. Trifft später eine Anfrage mit demselben Schlüssel ein, überspringt der Server die Ausführungslogik und gibt einfach die zwischengespeicherte Antwort zurück. Dieser Mechanismus ist in verteilten Systemen entscheidend, in denen der Client nach einem Netzwerk-Timeout nicht sicher weiß, ob eine Anfrage den Server erreicht hat.
Bedeutung für Absender
Bei transaktionalen E-Mails kann das doppelte Senden derselben Nachricht zu einer schlechten Nutzererfahrung und mehr Spam-Meldungen führen. Mit Idempotenzschlüsseln können Entwickler fehlgeschlagene Netzwerkaufrufe offensiv wiederholen, ohne doppelte E-Mails an den Empfänger zu riskieren. Das sorgt für Zuverlässigkeit und Konsistenz in der gesamten Zustellpipeline.
Betriebliche Aspekte
Schlüssel sollten als UUID oder als zufällige Zeichenkette mit hoher Entropie erzeugt werden, um Kollisionen zu vermeiden. Server lassen diese Schlüssel in der Regel nach 24 Stunden ablaufen. Entwickler müssen sicherstellen, dass der Schlüssel an den konkreten Zweck der Nachricht gebunden ist: Werden Body oder Empfänger der E-Mail geändert, der Schlüssel aber beibehalten, sollte das zu einem Fehler führen und nicht zu einem zwischengespeicherten Erfolg.
Implementierungsbeispiel
Eine SaaS-Anwendung erzeugt einen eindeutigen Schlüssel für eine E-Mail zur Passwort-Zurücksetzung. Die App ruft die E-Mail-API auf, doch die Verbindung bricht ab, bevor eine Antwort eintrifft. Die App wiederholt die Anfrage mit demselben Schlüssel. Die API erkennt, dass der Schlüssel bereits existiert, und gibt 200 OK zurück, ohne dem Nutzer eine zweite E-Mail zu senden. Die kostenlosen SendHQ-Tools helfen Entwicklern, ihre E-Mail-Infrastruktur effizient zu verwalten.
Fehlerbehandlung
Wird eine Anfrage verändert, aber mit einem bereits verwendeten Idempotenzschlüssel gesendet, sollte der Server einen Konfliktfehler zurückgeben. Das verhindert, dass Schlüssel versehentlich für andere Nachrichten wiederverwendet werden. Fangen Sie solche Konflikte ab und erzeugen Sie für den geänderten Request-Payload einen neuen Schlüssel.
Häufige Fragen von Teams
Ist ein Idempotenzschlüssel dasselbe wie eine Message-ID?
Nein. Eine Message-ID vergibt der Server nach der Verarbeitung, einen Idempotenzschlüssel vergibt der Client, bevor die Anfrage gesendet wird.
Was passiert, wenn der Idempotenzschlüssel abläuft?
Ist der Schlüssel aus dem Server-Cache abgelaufen, wird ein Wiederholungsversuch als neue Anfrage behandelt. Dadurch kann eine doppelte E-Mail versendet werden.
Welcher Datentyp eignet sich am besten für Idempotenzschlüssel?
UUID v4 ist der Branchenstandard, weil die Wahrscheinlichkeit einer Kollision auch in verteilten Systemen verschwindend gering ist.
Primärquellen
- SendGrid-Dokumentation – Twilio SendGrid
- Postmark-Entwicklerdokumentation – Postmark