Envoyer des e-mails transactionnels de façon fiable : ligne outbox, worker, nouvelles tentatives et clés d'idempotence

Objectif

Chaque confirmation de commande, réinitialisation de mot de passe ou facture quitte le système une seule fois, survit aux plantages de processus et aux pannes de fournisseur, et peut être tracée depuis l'événement métier jusqu'à l'identifiant de message du fournisseur.

Prérequis

Un stockage durable (la base de données propre de l'application suffit), un processus worker, un fournisseur ou un MTA joignable en SMTP ou HTTP, et une convention de Message-ID. La RFC 5321 citée répartit les réponses négatives en classes transitoires (4yz : la même requête peut réussir plus tard) et permanentes (5yz : ne pas répéter la requête sans la modifier) ; la RFC 5322 citée exige que le Message-ID soit un identifiant unique au niveau mondial.

Étapes

1. Dans la même transaction de base de données qui enregistre l'événement métier, insérer une ligne outgoing_email : destinataire, nom du modèle, paramètres rendus, une clé d'idempotence dérivée de l'événement (order-1234-confirmation), un Message-ID fraîchement généré et un statut pending. C'est le patron outbox appliqué au courrier.
2. Un worker s'attribue un lot de lignes en attente (en PostgreSQL : SELECT ... FOR UPDATE SKIP LOCKED), rend le message et appelle le fournisseur avec le Message-ID stocké et, lorsque l'API en accepte une, la clé d'idempotence.
3. Classer le résultat. Les réponses 4yz, les erreurs de connexion et les délais dépassés sont à réessayer : conserver la ligne, incrémenter attempts, définir next_attempt_at avec un backoff exponentiel et du jitter. Les réponses 5yz et les adresses rejetées sont définitives : marquer failed avec le texte de la réponse et s'arrêter.
4. Plafonner le nombre de tentatives et l'âge. La RFC 5321 indique que le délai d'abandon d'un MTA doit généralement être d'au moins 4 à 5 jours ; une file d'attente applicative plafonne d'ordinaire bien plus tôt, et les lignes au-delà du plafond passent à un statut de lettre morte qui déclenche une alerte.
5. Stocker l'identifiant de message du fournisseur et les horodatages sur la ligne, afin que les rebonds, les plaintes et les questions du support puissent être rattachés à l'événement.
6. Rendre le worker sûr à exécuter en parallèle et après des plantages : c'est la clé d'idempotence ou le Message-ID unique qui empêche un second envoi lorsque le processus meurt entre « accepté par le fournisseur » et « ligne marquée envoyée ».
7. Utiliser des files ou des priorités séparées pour le courrier urgent (codes de connexion, réinitialisations) et tout le reste, afin qu'une rafale en masse ne puisse pas retarder un code.

Résultat attendu

Les envois survivent aux redémarrages ; une panne de fournisseur se traduit par un nombre croissant de lignes en attente plutôt que par du courrier perdu ; les doublons après un plantage sont évités par la clé plutôt que par chance.

Limites et base de vérification

« Exactement une fois » ne tient que jusqu'à l'API du fournisseur : un fournisseur qui a accepté la requête mais n'a jamais répondu peut malgré tout avoir envoyé le message, et les clés d'idempotence côté fournisseur ne sont généralement honorées que pendant une période que le fournisseur documente. Tester en tuant le worker entre l'envoi et le marquage comme envoyé, et en simulant des réponses 4yz et 5yz. Fondé sur les RFC citées et sur une pratique documentée ; aucun chiffrage de délai ou de taux n'est avancé.