technisch · antwoord met bronnen
Idempotentiesleutel: dubbel verstuurde e-mails voorkomen
Een idempotentiesleutel is een unieke waarde die een client genereert en in een API-request meestuurt, zodat een bewerking precies één keer wordt uitgevoerd. Als een request met dezelfde sleutel opnieuw wordt verstuurd, herkent de server het duplicaat en geeft hij de oorspronkelijke respons terug zonder de actie opnieuw uit te voeren.
Hoe het technisch werkt
Wanneer een client een request met een idempotentiesleutel stuurt, slaat de server de sleutel en de bijbehorende respons op in een cache. Komt er daarna een request binnen met dezelfde sleutel, dan slaat de server de uitvoeringslogica over en geeft hij simpelweg de gecachte respons terug. Dit mechanisme is essentieel in gedistribueerde systemen, waar de client door netwerktimeouts niet altijd weet of een request de server heeft bereikt.
Waarom het belangrijk is voor afzenders
Bij transactionele e-mail leidt het twee keer versturen van hetzelfde bericht tot een slechte gebruikerservaring en meer spammeldingen. Met idempotentiesleutels kunnen developers agressieve retrylogica voor mislukte netwerkcalls bouwen zonder het risico dat de ontvanger dubbele e-mails krijgt. Dat zorgt voor betrouwbaarheid en consistentie in de hele bezorgpipeline.
Praktische overwegingen
Genereer sleutels met een UUID of een willekeurige string met hoge entropie om botsingen te voorkomen. Servers laten deze sleutels doorgaans na 24 uur verlopen. Developers moeten ervoor zorgen dat de sleutel gekoppeld is aan de specifieke bedoeling van het bericht: als de body of de ontvanger verandert terwijl de sleutel gelijk blijft, moet dat een fout opleveren en geen gecacht succes.
Implementatievoorbeeld
Een SaaS-applicatie genereert een unieke sleutel voor een e-mail voor een wachtwoordreset. De app roept de e-mail-API aan, maar de verbinding valt weg voordat er een respons binnenkomt. De app probeert het request opnieuw met dezelfde sleutel. De API ziet dat de sleutel al bestaat en geeft 200 OK terug zonder een tweede e-mail naar de gebruiker te sturen. Met de gratis tools van SendHQ kunnen developers hun e-mailinfrastructuur efficiënt beheren.
Foutafhandeling
Als een request is gewijzigd maar met een bestaande idempotentiesleutel wordt verstuurd, moet de server een conflictfout teruggeven. Dat voorkomt dat sleutels per ongeluk voor verschillende berichten worden hergebruikt. Vang deze conflicten netjes af en genereer een nieuwe sleutel voor de bijgewerkte request-payload.
Vragen die teams stellen
Is een idempotentiesleutel hetzelfde als een Message-ID?
Nee. Een Message-ID wordt na de verwerking door de server toegekend, terwijl een idempotentiesleutel door de client wordt toegekend voordat het request wordt verstuurd.
Wat gebeurt er als de idempotentiesleutel verloopt?
Als de sleutel uit de cache van de server is verlopen, wordt een retry als nieuw request behandeld, waardoor er mogelijk een dubbele e-mail wordt verstuurd.
Welk datatype is het meest geschikt voor idempotentiesleutels?
UUID v4 is de industriestandaard, omdat de kans op botsingen in gedistribueerde systemen verwaarloosbaar klein is.
Primaire bronnen
- SendGrid Documentation — Twilio SendGrid
- Postmark Developer Documentation — Postmark