Clés d’idempotence pour les API e-mail

Le problème des e-mails en double

Les e-mails en double surviennent lorsqu’un client envoie une requête, que le serveur la traite, mais que le réseau tombe avant que le client ne reçoive la réponse de succès. Le client, face à un timeout ou une erreur 5xx, réessaie la requête. Sans idempotence, le serveur traite cette nouvelle tentative comme une nouvelle requête et renvoie l’e-mail. Les clés d’idempotence l’évitent en permettant au serveur de reconnaître une requête répétée et de renvoyer le résultat d’origine sans réexécuter l’effet de bord.

Pour un ingénieur responsable de la file d’incidents, rien n’est pire qu’une « tempête d’e-mails en double ». Elle survient généralement lors d’une panne partielle d’un fournisseur en amont ou d’un interblocage de base de données qui ralentit les temps de réponse. Votre logique de nouvelles tentatives, conçue pour la fiabilité, devient une arme qui spamme vos utilisateurs et abîme votre réputation d’expéditeur.

Pourquoi les nouvelles tentatives échouent sans idempotence

Dans un système distribué, tout appel d’API peut échouer à trois endroits :

1. La requête n’atteint jamais le serveur.
2. Le serveur traite la requête, mais la réponse est perdue.
3. Le serveur plante en cours de traitement.

Si vous réessayez dans le cas 1, aucun risque. Si vous réessayez dans le cas 2, vous envoyez un doublon. Si vous réessayez dans le cas 3, vous risquez d’envoyer un doublon selon l’endroit où le plantage s’est produit.

Envoyer un e-mail est un effet de bord externe. Contrairement à la mise à jour du nom d’un utilisateur en base de données (naturellement idempotente si vous utilisez SET name = 'Alice'), l’envoi d’un e-mail est une action additive. Chaque appel à un endpoint send crée un nouveau message dans le monde réel. Pour le rendre idempotent, vous devez introduire un identifiant unique de l’intention d’envoi, appelé clé d’idempotence.

Implémenter des clés d’idempotence

Une clé d’idempotence est une valeur unique (généralement un UUID v4) générée par le client et envoyée dans un en-tête de la requête. Le serveur utilise cette clé pour suivre l’état de la requête.

Le workflow côté serveur

1. Réception de la requête : le serveur vérifie si l’en-tête Idempotency-Key est présent.
2. Recherche : le serveur cherche cette clé dans un stockage à accès rapide (comme Redis).
3. Clé trouvée (cache hit) : si la clé existe, le serveur renvoie immédiatement la réponse en cache sans appeler le moteur de livraison.
4. Clé absente (cache miss) : le serveur verrouille la clé, traite l’envoi de l’e-mail, stocke la réponse et la renvoie au client.
5. Expiration : la clé expire après une fenêtre donnée (par exemple 24 heures) pour éviter que la base de données ne grossisse indéfiniment.

Exemple concret de payload

Voici à quoi doit ressembler une requête avec une API comme SendHQ :

POST /v1/send Host: api.sendhq.cc Content-Type: application/json Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 Authorization: Bearer YOUR_API_KEY { "to": "user@example.com", "template_id": "welcome-email", "variables": { "name": "Alex" } }

Gérer les cas d’erreur

Toutes les nouvelles tentatives ne se valent pas. Vous devez distinguer les erreurs client des erreurs serveur.

• Erreurs 4xx : si le serveur renvoie 400 (Bad Request) ou 422 (Unprocessable Entity), la requête est invalide. Réessayer avec la même clé doit renvoyer la même erreur 4xx. Ne modifiez pas le payload en réutilisant la clé : cela crée un conflit.
• Erreurs 5xx : si le serveur renvoie 500 ou 503, le client doit réessayer. Si le serveur avait déjà transmis l’e-mail au MTA (Mail Transfer Agent), la clé d’idempotence garantit que la nouvelle tentative renvoie 200 OK au lieu d’envoyer un second e-mail.
• Requêtes concurrentes : si deux requêtes identiques avec la même clé arrivent exactement à la même milliseconde, le serveur doit renvoyer 409 Conflict pour la seconde afin d’indiquer que la première est toujours en cours de traitement.

L’idempotence pour les agents IA

Les agents IA (qui utilisent des serveurs MCP ou des cartes A2A) ajoutent un nouveau niveau de risque. Les LLM peuvent être non déterministes et déclencher plusieurs fois le même appel d’outil s’ils perçoivent un échec dans la boucle.

Lorsque vous construisez des intégrations prêtes pour les agents, ne laissez jamais un agent déclencher une action send sans étape de validation ou sans clé d’idempotence déterministe générée par l’orchestrateur. L’orchestrateur doit associer l’intention de l’agent (par exemple « Envoyer le rapport hebdomadaire à Bob ») à une clé stable fondée sur l’identifiant du rapport et la date. Cela évite que l’agent envoie cinq fois le même rapport parce qu’il « pensait » que le premier appel avait échoué.

Le coût de l’échec : comparaison des fournisseurs

Faute d’idempotence, vous n’agacez pas seulement vos utilisateurs : vous gaspillez de l’argent. Certains fournisseurs sont moins chers, mais le coût des doublons grimpe vite.

D’après les pages de tarification officielles (en septembre 2026) :

• Amazon SES : 0.10 USD pour 1 000 e-mails à la carte (tarifs Amazon SES). Les nouvelles formules par paliers introduites le 21 juillet 2026 comprennent Essentials (0.16 USD pour 1 000), Pro (0.22 USD pour 1 000 plus 105 USD par mois et par région) et Enterprise (0.23 USD pour 1 000 plus 500 USD par mois).
• Resend : l’offre gratuite comprend 3 000 e-mails par mois, plafonnés à 100 par jour. Pro coûte 20 USD par mois pour 50 000 e-mails, avec des dépassements à 0.90 USD pour 1 000 (tarifs Resend).
• SendGrid : l’offre gratuite est désormais un essai de 60 jours, et les formules Essentials démarrent à 19.95 USD par mois (tarifs SendGrid).
• Mailgun : 15 USD par mois pour 10 000 e-mails, avec des dépassements allant de 1.80 à 1.10 USD pour 1 000 (tarifs Mailgun).
• Postmark : 15 USD par mois pour 10 000 e-mails, avec des dépassements de 1.80 à 1.20 USD pour 1 000 (tarifs Postmark).

Pour mettre les choses en perspective, envoyer 50 000 e-mails coûte environ 5 USD avec SES à la carte, contre environ 66 USD avec les paliers de Postmark. Si une boucle de nouvelles tentatives sans idempotence multiplie accidentellement votre volume par 10, l’écart financier entre fournisseurs devient une ligne non négligeable de votre rapport d’incident.

Délivrabilité ou acceptation

Il est essentiel de comprendre que l’idempotence ne résout que le problème de l’acceptation.

1. Acceptation : l’API accepte votre requête et renvoie 200 OK. C’est ici qu’interviennent les clés d’idempotence.
2. Livraison : l’API transmet l’e-mail au serveur de réception (par exemple Gmail). C’est là que SPF et DKIM/DMARC comptent.
3. Placement en boîte de réception : le serveur de réception décide si l’e-mail va dans la boîte de réception ou dans le dossier spam.

Une clé d’idempotence garantit que vous n’acceptez la requête qu’une seule fois. Elle ne garantit ni que l’e-mail sera délivré, ni qu’il évitera le dossier spam. Pour vous assurer que votre infrastructure est correctement configurée pour la livraison, utilisez des outils comme le vérificateur DNS e-mail de SendHQ pour contrôler vos enregistrements.

Checklist d’implémentation pour les ingénieurs

Si vous auditez aujourd’hui votre logique d’envoi d’e-mails, utilisez cette checklist :

• Génération de clé côté client : générez-vous un UUID v4 pour chaque intention d’e-mail unique ?
• Implémentation d’en-tête : la clé est-elle transmise dans un en-tête standard (par exemple, Idempotency-Key) plutôt que dans le corps de la requête ?
• Couche de stockage : vos clés d’idempotence ont-elles un TTL (Time To Live) pour éviter l’encombrement du stockage ?
• Verrouillage atomique : votre serveur utilise-t-il un verrou distribué (comme SET NX dans Redis) pour empêcher les conditions de concurrence sur une même clé ?
• Mise en cache des réponses : stockez-vous la réponse complète (code d’état et corps) afin de la renvoyer au client lors des nouvelles tentatives ?
• Garde-fous pour les agents : lorsque vous utilisez des agents IA, la clé est-elle générée par l’orchestrateur système plutôt que par le LLM ?

Exemple de code : middleware d’idempotence en Node.js

Voici un exemple simplifié d’implémentation de cette logique dans un environnement Node.js avec Redis.

const redis = require('redis'); const client = redis.createClient(); async function sendEmailHandler(req, res) { const idempotencyKey = req.headers['idempotency-key']; if (!idempotencyKey) { return res.status(400).json({ error: 'Idempotency-Key header is required' }); } // Try to acquire a lock and check for existing response const cachedResponse = await client.get(`idempotency:${idempotencyKey}`); if (cachedResponse) { const { status, body } = JSON.parse(cachedResponse); return res.status(status).json(body); } // Set a lock to prevent concurrent requests const lock = await client.set(`lock:${idempotencyKey}`, 'true', 'NX', 'EX', 30); if (!lock) { return res.status(409).json({ error: 'Request is currently being processed' }); } try { // Actual email sending logic const result = await emailProvider.send(req.body); const responsePayload = { status: 200, body: result }; // Cache the result for 24 hours await client.set(`idempotency:${idempotencyKey}`, JSON.stringify(responsePayload), 'EX', 86400); return res.status(200).json(result); } catch (error) { return res.status(500).json({ error: 'Internal Server Error' }); } finally { await client.del(`lock:${idempotencyKey}`); } }

Conclusion

L’idempotence n’est pas un « plus » pour l’e-mail transactionnel : c’est une exigence pour tout système qui tient à l’expérience utilisateur et à la maîtrise des coûts. En confiant au client la responsabilité de l’unicité et en fournissant côté serveur un mécanisme pour la suivre, vous éliminez le risque d’envois en double en cas d’instabilité du réseau.

Que vous construisiez un produit SaaS classique ou un agent IA autonome, traiter l’e-mail comme un effet de bord critique garantit la fiabilité de votre système et la satisfaction de vos utilisateurs. Pour une API e-mail pensée pour les développeurs qui gère ces complexités, découvrez https://sendhq.cc.