Que faire si les e-mails de test ne s’affichent pas dans Mailpit 1.33.1 en 2026 ?

Distinguez d’abord les trois preuves d’envoi

Un test peut réussir sans que Mailpit ait enregistré le message attendu. Cela arrive notamment quand l’assertion porte sur l’appel d’une fonction, quand un composant accepte la demande d’envoi, ou quand le test interroge ensuite une autre instance. Ces résultats ne prouvent pas la même chose.

Séparez le diagnostic en trois preuves :

• L’application a tenté l’envoi. Le code a exécuté la branche d’envoi, mais l’appel peut encore viser une configuration inattendue.
• Le serveur de test a reçu une demande. Une réponse favorable indique ce que le serveur a accepté à cette étape ; elle ne prouve pas que votre test a cherché au bon endroit.
• Mailpit a enregistré un message que vous pouvez lire. C’est la preuve utile pour examiner le contenu capturé. Elle ne certifie toutefois pas une livraison à un service de courrier externe.

Cette distinction est particulièrement utile dans un test d’inscription. L’assertion « le compte a été créé » peut réussir même si le message de vérification part vers un autre hôte, ou si votre test attend le mauvais destinataire. Pour éviter ce faux diagnostic, relevez au même moment l’environnement du processus, l’adresse du destinataire, la réponse du serveur et l’instance consultée.

Première étape : comparez la configuration réelle avec l’instance ouverte

Ne partez pas de la valeur prévue dans un fichier de configuration. Vérifiez celle que le processus de test utilise effectivement au moment de l’envoi. Un paramètre différent dans un conteneur, un environnement de préproduction ou une tâche automatisée suffit à faire parvenir le message ailleurs.

Contrôlez les éléments suivants :

• Le nom d’hôte SMTP et le port employés par l’application correspondent-ils à ceux du service Mailpit que vous avez lancé ? La documentation officielle de configuration SMTP décrit les paramètres de ce service.
• Si l’application utilise une interface HTTP, l’adresse de base configurée correspond-elle à l’instance dont vous ouvrez l’interface ? La configuration HTTP concerne l’accès à l’interface et à l’API ; ne confondez pas cette adresse avec le serveur SMTP de réception. Consultez la documentation de configuration HTTP.
• Le processus tourne-t-il dans un conteneur ? Dans ce cas, une adresse valable depuis votre navigateur sur l’hôte n’est pas nécessairement celle que doit utiliser le conteneur. Vérifiez le réseau et le nom de service accessibles depuis ce processus, plutôt que de recopier une adresse « locale » sans la tester.
• Les variables d’environnement ou les paramètres du profil de test remplacent-ils ceux que vous avez examinés dans les fichiers ?
• Les journaux et la réponse observée concernent-ils bien la même instance Mailpit que celle affichée dans le navigateur ?

Pour un diagnostic reproductible, notez la configuration effective avec l’identifiant de la tâche ou du scénario de test. N’inscrivez pas de secrets dans ces traces. Si vos journaux contiennent des adresses ou des contenus de test associés à des personnes, réduisez ces données au strict nécessaire.

Un scénario fréquent en préproduction

Vous lancez l’interface Mailpit sur la machine hôte, mais l’application de test s’exécute dans un conteneur. L’interface reste accessible depuis le navigateur ; pourtant, l’application peut contacter un autre hôte SMTP, ou ne pas pouvoir résoudre celui que vous avez indiqué. Le navigateur qui affiche la page ne prouve donc pas que le processus applicatif peut joindre le même service.

Suivez l’appel depuis l’application : configuration au démarrage, connexion au serveur, réponse à l’envoi, puis journaux du collecteur visé. Cette séquence révèle si le problème survient avant la connexion, pendant la transmission ou après celle-ci. Elle évite aussi de conclure trop tôt que Mailpit « perd » un message.

Deuxième étape : contrôlez la réponse SMTP et le message transmis

Pour un test SMTP, observez le résultat de l’échange tel qu’il est rapporté par votre bibliothèque et par le serveur. Ne vous contentez pas de constater que la méthode d’envoi a été appelée. La documentation de Mailpit sur l’envoi de messages peut vous aider à comparer votre configuration et la manière dont vous injectez un message dans l’environnement de test.

Vérifiez ensuite le message réellement construit :

• le champ destinataire est-il celui que le scénario de test attend ?
• le message est-il envoyé une seule fois, ou plusieurs scénarios utilisent-ils la même adresse ?
• les en-têtes et le corps transmis correspondent-ils au chemin de code que vous testez ?
• la réponse provient-elle du collecteur local, ou d’un autre service défini par la configuration ?

Si vous utilisez l’API plutôt que SMTP pour injecter un message, identifiez clairement cette voie dans votre diagnostic. Une réponse d’API ne doit pas être assimilée à une réponse SMTP : elle correspond à une interface différente. La documentation d’intégration des tests Mailpit apporte le contexte nécessaire pour comprendre les approches d’intégration documentées, sans supposer que votre application emploie automatiquement celle que vous aviez en tête.

Conservez un échantillon minimal et reproductible du message lorsque le problème dépend de son contenu. Retirez les données personnelles et les secrets avant de le partager. Cet échantillon permet de comparer une version qui fonctionne et une version qui échoue sans confondre le contenu du message avec le transport ou le choix de l’instance.

Troisième étape : examinez les changements d’analyse de la version 1.33.1

Les notes officielles de Mailpit 1.33.1 mentionnent des changements concernant l’analyse des en-têtes, les destinataires Bcc et le traitement des messages impossibles à analyser. Elles signalent notamment que ces derniers sont rejetés plutôt que silencieusement ignorés. Pour éviter d’étendre ces indications au-delà de ce qui est annoncé, comparez-les aux notes de version de Mailpit 1.33.1.

Concrètement, si un test échoue avec un nom d’affichage non UTF-8 ou un message contenant un destinataire Bcc, reproduisez le cas avec l’instance et la version réellement exécutées. Vérifiez si le message apparaît et si les champs attendus sont lisibles dans la capture. La version corrigée ne permet pas de conclure que tous les formats d’en-têtes sont acceptés, ni que tout cas de Bcc aura le résultat que votre application attend.

Face à un message rejeté, préservez l’échantillon concerné et la réponse du serveur. Examinez les journaux de l’instance, puis comparez votre résultat à la documentation officielle. N’inventez pas un code d’erreur ou une règle de rejet à partir d’un symptôme qui n’est pas documenté. Si le problème n’est pas reproductible, vérifiez d’abord la version démarrée, plutôt que celle inscrite dans les fichiers du projet.

La différence importe pour votre triage : un message absent peut signaler une mauvaise destination, un problème de transport, un rejet lié à l’analyse ou une recherche inadéquate. Les changements de la version 1.33.1 ne sont qu’une piste lorsque le cas reproduit correspond aux éléments annoncés.

Quatrième étape : séparez la capture de la recherche dans l’API

Ouvrez l’interface de l’instance concernée et cherchez le message sans commencer par le filtre complexe utilisé par le test. S’il est visible, la capture a eu lieu : orientez alors l’analyse vers la requête, l’identifiant et les critères de recherche. S’il est absent, retournez au transport, à la configuration et au traitement du message.

Pour la vérification programmatique, partez des routes documentées dans l’API Mailpit. Comparez la requête de votre test à l’API de la version effectivement lancée. Relevez l’adresse de l’API utilisée, la réponse HTTP, les filtres de recherche et la façon dont le code sélectionne le message. Le fait de demander « le dernier message » peut conduire à lire un message antérieur ou un message créé par un autre scénario si plusieurs tests partagent le même collecteur.

Une recherche API vide n’est pas automatiquement un échec de réception. Le filtre peut exclure le destinataire, la requête peut interroger une autre instance, ou le code peut chercher un identifiant différent de celui du message capturé. À l’inverse, une réponse de recherche valide mais sans résultat ne prouve pas que l’envoi n’a jamais eu lieu.

Au lieu de laisser plusieurs tests partager une boîte sans corrélation, ajoutez un marqueur propre au scénario dans les données de test, par exemple un destinataire distinct lorsque votre application le permet. Gardez également l’identifiant du message renvoyé par la recherche ou affiché dans l’interface, puis faites porter les assertions suivantes sur ce message précis. Évitez de dépendre d’un ordre d’arrivée implicite.

Utilisez cette liste pour choisir la prochaine vérification

Cochez chaque contrôle au moment où vous l’avez effectué. Le premier élément non confirmé indique où poursuivre le diagnostic.

• [ ] Je connais l’hôte et le port SMTP, ou l’adresse API, utilisés par le processus de test — pas seulement la valeur prévue dans le fichier de configuration.
• [ ] J’ai vérifié que l’instance consultée dans l’interface est celle que le processus peut joindre.
• [ ] J’ai conservé la réponse d’envoi et les journaux pertinents, sans exposer de secret ni de donnée personnelle inutile.
• [ ] J’ai confirmé le destinataire, le contenu du message et les en-têtes transmis par le scénario qui échoue.
• [ ] J’ai cherché le message dans l’interface avant d’attribuer l’échec à l’API.
• [ ] Si le message est visible, j’ai contrôlé la route, les filtres et l’identifiant employés par le test à l’aide de la documentation API.
• [ ] Si le message est absent, j’ai vérifié la version lancée et conservé un exemple reproductible avant d’incriminer l’analyse.
• [ ] J’ai séparé le résultat « capturé localement » du résultat « livré à un destinataire externe ».

Choisissez la branche suivante :

• Si la configuration ou la réponse d’envoi n’est pas confirmée, corrigez le trajet entre l’application et l’instance avant d’examiner l’API.
• Si l’interface contient le message, conservez l’envoi tel quel et corrigez la recherche ou l’association du message au scénario.
• Si le message manque et que le cas reproductible implique un en-tête ou un Bcc, comparez le résultat à la version et aux notes officielles.
• Si l’objectif est de vérifier la réception par un service externe, concevez un test distinct : la capture Mailpit ne couvre pas cette étape.

Refaites le test sans élargir la conclusion

Après correction, rejouez le scénario qui échouait et vérifiez trois résultats séparément : l’application a soumis le message à la destination attendue, Mailpit l’a enregistré, et le contenu capturé correspond au test. Si votre défaut concernait un nom d’affichage non UTF-8 ou un destinataire Bcc, réutilisez précisément l’échantillon concerné ; un e-mail ordinaire ne valide pas à lui seul le cas particulier.

Gardez des scénarios isolés pour les messages normaux et ceux qui exercent les chemins d’en-têtes sensibles. Consignez la version de Mailpit, la configuration non secrète, le résultat de capture et le résultat de lecture API. Cette trace facilite la comparaison après une mise à jour et évite qu’un test « vert » dissimule une assertion trop faible.

Un test de capture locale valide seulement le trajet jusqu’au collecteur local et la possibilité d’y lire le message. Il ne démontre pas que le fournisseur externe l’a accepté, que le domaine expéditeur est correctement configuré, que le message a évité les indésirables, ni que son destinataire l’a vu. Quand cette dernière partie fait partie du besoin produit, testez-la séparément dans un environnement autorisé et consignez son résultat comme une autre étape de validation.

La séparation des environnements protège aussi vos données. Pour des essais de conception de courriels d’inscription, de réinitialisation ou de notification, utilisez des destinataires et des contenus de test qui ne révèlent pas l’identité d’un utilisateur réel. Vous pouvez consulter la notice relative aux données de Tmpkey lorsque vous évaluez le traitement des informations associées à un usage de réception temporaire. Pour les tests autorisés de votre propre produit, prenez également connaissance des règles d’utilisation de Tmpkey.

Questions fréquentes

L’application signale un envoi réussi, mais Mailpit reste vide : que vérifier ?

Commencez par relever l’hôte SMTP ou l’adresse API réellement utilisée par le processus de test, puis comparez-la à l’instance Mailpit ouverte dans le navigateur. Consultez ensuite la réponse d’envoi et les journaux de cette instance. Une fonction appelée ou une assertion réussie ne prouve pas, à elle seule, que le message a été accepté et enregistré par le collecteur visé.

Comment reconnaître un message que Mailpit n’a pas pu analyser ?

Les notes officielles de la version 1.33.1 indiquent que les messages impossibles à analyser sont rejetés, au lieu d’être silencieusement ignorés. Conservez un message reproductible et la réponse du serveur, puis vérifiez les journaux de l’instance et la version effectivement exécutée. N’inférez pas un code d’erreur précis si la réponse ou la documentation consultée ne le fournit pas.

Pourquoi l’API Mailpit ne trouve-t-elle pas le message récent ?

Vérifiez d’abord dans l’interface si le message existe. S’il y figure, le problème se situe probablement dans la requête ou dans le test : adresse utilisée, filtre, instance interrogée ou identifiant récupéré. Comparez ensuite votre appel avec les routes et les formes d’identifiant documentées pour l’API de la version installée, sans supposer que le dernier message correspond toujours à votre envoi.

La présence du message dans Mailpit prouve-t-elle sa livraison externe ?

Non. Mailpit sert ici de collecteur de test local : sa capture permet de vérifier que le message est arrivé à l’instance de test et d’inspecter ce qu’elle a enregistré. Elle ne démontre ni la livraison à un fournisseur externe, ni le classement dans la boîte de réception plutôt que dans les indésirables. Pour cela, testez séparément le parcours externe autorisé.

Choisissez un collecteur adapté à la preuve recherchée

Quand vous devez seulement vérifier que votre propre application produit un message lisible dans un environnement contrôlé, un collecteur local comme Mailpit permet d’inspecter cette partie du parcours sans faire passer le test pour une validation de livraison externe. Si vous avez plutôt besoin d’une boîte de réception temporaire distincte pour examiner un message réel de test, Tmpkey peut constituer une autre option à évaluer. Vérifiez sur le service les fonctions actuellement proposées et les limites applicables avant de l’intégrer à votre procédure ; ne supposez pas qu’un message sera toujours livré. Les tests d’inscription, de conception ou de code de vérification restent ainsi séparés de votre boîte personnelle, tandis que la preuve recueillie correspond exactement à l’étape que vous avez testée.