technique · réponse sourcée
Clé d’idempotence : éviter les envois d’e-mails en double
Une clé d’idempotence est une valeur unique générée par un client et envoyée dans une requête API pour garantir qu’une opération n’est exécutée qu’une seule fois. Si une requête est renvoyée avec la même clé, le serveur reconnaît le doublon et renvoie la réponse d’origine sans exécuter à nouveau l’action.
Fonctionnement technique
Lorsqu’un client envoie une requête avec une clé d’idempotence, le serveur stocke la clé et la réponse obtenue dans un cache. Si une requête ultérieure arrive avec la même clé, le serveur saute la logique d’exécution et renvoie simplement la réponse en cache. Ce mécanisme est essentiel dans les systèmes distribués, où un timeout réseau peut laisser le client dans l’incertitude quant à la bonne réception de sa requête par le serveur.
Pourquoi c’est important pour les expéditeurs
Pour l’e-mail transactionnel, envoyer deux fois le même message peut dégrader l’expérience utilisateur et augmenter les signalements de spam. Les clés d’idempotence permettent aux développeurs de mettre en place une logique de nouvelles tentatives agressive pour les appels réseau échoués, sans risquer d’envoyer des e-mails en double au destinataire. Cela garantit la fiabilité et la cohérence de toute la chaîne de livraison.
Considérations opérationnelles
Les clés doivent être générées à l’aide d’un UUID ou d’une chaîne aléatoire à forte entropie pour éviter les collisions. Les serveurs font généralement expirer ces clés au bout de 24 heures. Les développeurs doivent s’assurer que la clé est liée à l’intention précise du message : modifier le corps de l’e-mail ou le destinataire en conservant la même clé doit produire une erreur plutôt qu’un succès mis en cache.
Exemple de mise en œuvre
Une application SaaS génère une clé unique pour un e-mail de réinitialisation de mot de passe. L’application appelle l’API e-mail, mais la connexion tombe avant la réception de la réponse. L’application renvoie la requête avec la même clé. L’API constate que la clé existe déjà et renvoie un 200 OK sans envoyer de second e-mail à l’utilisateur. Les outils gratuits de SendHQ peuvent aider les développeurs à gérer efficacement leur infrastructure e-mail.
Gestion des erreurs
Si une requête est modifiée mais envoyée avec une clé d’idempotence existante, le serveur doit renvoyer une erreur de conflit. Cela évite la réutilisation accidentelle de clés pour des messages différents. Une gestion correcte consiste à intercepter ces conflits et à générer une nouvelle clé pour le payload de requête mis à jour.
Les questions que posent les équipes
Une clé d’idempotence est-elle la même chose qu’un identifiant de message ?
Non. Un identifiant de message est attribué par le serveur après le traitement, tandis qu’une clé d’idempotence est attribuée par le client avant l’envoi de la requête.
Que se passe-t-il si la clé d’idempotence expire ?
Si la clé a expiré dans le cache du serveur, une nouvelle tentative sera traitée comme une nouvelle requête, ce qui peut entraîner l’envoi d’un e-mail en double.
Quel type de données convient le mieux aux clés d’idempotence ?
L’UUID v4 est le standard du secteur, car il offre une probabilité de collision négligeable dans les systèmes distribués.
Sources primaires
- Documentation SendGrid — Twilio SendGrid
- Documentation développeur Postmark — Postmark