Tutoriels · 2026
2026 Mailgun Inbox Placement Test API : comment l’intégrer à la CI ?
Ce guide s’adresse aux personnes qui automatisent les envois de leur propre produit avec Mailgun. Il explique comment associer un test Inbox Placement à une requête Send API, éviter les doublons lors des nouvelles tentatives et vérifier séparément la réception réelle et le parcours métier.
2026 Mailgun Inbox Placement Test API : comment l’intégrer à la CI ?Ce guide s’adresse aux personnes qui automatisent les envois de leur propre produit avec Mailgun. Il explique comment associer un test Inbox Placement à une requête Send API, éviter les doublons lors des nouvelles tentatives et vérifier séparément la réception réelle et le parcours métier.
Sommaire de l’article
Votre pipeline signale un envoi réussi, mais vous ne savez pas si cela signifie que le rapport de placement est prêt ni si le courriel est réellement lisible dans une boîte de réception de test.
Action à faire cette semaine : si Inbox Placement est activé pour votre compte, ajoutez o:inbox-placement-test-key à la requête normale de votre produit envoyée par le Mailgun Send API. Réutilisez la même clé pour les nouvelles tentatives de la même exécution. Le rapport obtenu décrit le résultat dans les boîtes de test du programme de graines ; il ne prouve pas, à lui seul, que votre courriel métier, son lien de validation ou son parcours utilisateur fonctionne.
Cet article est destiné aux responsables de CI qui automatisent les courriels de leur propre application ou d’un environnement d’envoi autorisé.
Il aidera les ingénieurs QA à séparer les résultats du test de graines de la réception effective, et les développeurs indépendants à éviter les exécutions dupliquées.
Dernière vérification : 20 novembre 2026. Les comportements et limites décrits ci-dessous ont été vérifiés dans la documentation officielle du Send API et les guides Inbox Placement de Mailgun.
Avant le pipeline, choisissez ce que le test doit prouver
Un contrôle de courriel peut désigner plusieurs vérifications qui ne donnent pas les mêmes preuves. Si vous les regroupez sous un seul statut « e-mail OK », votre CI risque d’afficher un succès alors qu’une partie importante du parcours n’a pas été testée.
| Objectif | Méthode adaptée | Ce que le résultat permet d’affirmer | Ce qu’il ne prouve pas |
|---|---|---|---|
| Vérifier que votre application construit et soumet le bon message | Test applicatif ou envoi contrôlé avec le Send API | La logique testée a produit une requête et obtenu une réponse d’envoi | Que le message est arrivé dans une boîte précise ou que le lien fonctionne |
| Observer le placement dans les boîtes de test | Paramètre Inbox Placement et rapport associé | Le résultat observé par le test de graines pour cette configuration | Le placement de tous les courriels chez tous les fournisseurs ou pour tous les destinataires |
| Valider le parcours réel de votre produit | Réception sur une adresse contrôlée, puis vérification du contenu et de l’action | Le message est lisible dans ce scénario de réception et l’étape métier choisie est vérifiable | Une garantie générale de placement auprès de vos utilisateurs |
Comment déclencher le test depuis le Mailgun Send API ? Vous associez à la requête d’envoi normale le paramètre o:inbox-placement-test-key, après avoir confirmé que Inbox Placement est disponible et activé pour le compte utilisé. Selon la documentation de Mailgun, le message de test est envoyé aux graines associées au test ; ce mécanisme n’est pas une promesse d’arrivée dans toutes les boîtes de réception des utilisateurs. Consultez la documentation du paramètre Send API et le guide officiel d’exécution d’un test Inbox Placement via le Send API.
Avant de modifier le pipeline, vérifiez aussi que l’envoi concerne votre propre produit ou un environnement dont vous êtes autorisé à gérer les messages. Un environnement de préproduction convient, à condition que sa configuration permette de tester le chemin d’envoi voulu. En revanche, ne dirigez pas une campagne de test vers des comptes tiers et ne considérez pas les graines comme des destinataires de recette métier.
Pour une application qui envoie des courriels de validation, le critère de réussite peut donc avoir plusieurs étapes : la requête est acceptée, le rapport de graines devient consultable, puis une adresse contrôlée reçoit un message dont le lien mène au bon environnement. Ces étapes sont liées, mais aucune ne remplace automatiquement les autres.
À l’intégration, associez une clé stable à la requête
Le paramètre o:inbox-placement-test-key sert à rattacher un envoi à un test Inbox Placement. La valeur doit être construite pour identifier l’activité ou l’exécution logique que vous souhaitez suivre, plutôt que générée à nouveau à chaque tentative réseau. Mailgun documente aussi un comportement d’idempotence : réutiliser une même clé dans un délai de sept jours ne crée pas un nouveau test. Cette durée est indiquée dans le guide Send API de Mailgun sur Inbox Placement.
Vous pouvez ainsi garder une clé stable pour les reprises techniques d’un même envoi, et créer une clé distincte lorsque vous voulez réellement lancer une nouvelle série de mesure. Ne mettez pas un identifiant aléatoire dans la clé à chaque nouvelle tentative : vous transformeriez une reprise de requête en demande de test différente.
Le principe ci-dessous illustre le placement du champ dans une requête à votre propre endpoint d’envoi. Remplacez les variables par les valeurs de votre environnement ; ne stockez ni clé d’API ni donnée personnelle directement dans le dépôt.
curl --request POST "$MAILGUN_SEND_ENDPOINT" \
--user "api:$MAILGUN_API_KEY" \
--form "from=$MAIL_FROM" \
--form "to=$CONTROLLED_RECIPIENT" \
--form "subject=$SUBJECT" \
--form "text=$BODY" \
--form "o:inbox-placement-test-key=$PLACEMENT_TEST_KEY"
Le nom exact de l’endpoint, les paramètres nécessaires et les conditions du compte doivent être vérifiés dans la référence officielle du Send API. L’extrait ne définit pas votre politique de livraison et ne constitue pas une configuration prête à copier sans adaptation. Si votre application utilise déjà un module d’envoi, ajoutez le champ à la requête construite par ce module plutôt que de créer un chemin séparé réservé au CI : vous testerez ainsi le code réellement utilisé par le produit.
Conservez ensemble l’identifiant du pipeline, le commit, l’environnement, la clé de test et l’identifiant de la réponse d’envoi. Évitez d’inclure dans les journaux des secrets, des liens de validation utilisables ou des adresses personnelles. Pour préparer des données de test sans exposer de renseignements réels, vous pouvez aussi consulter les principes de protection des données de test.
Pendant l’exécution, séparez les reprises des nouveaux tests
Une réponse positive au Send API atteste le traitement de la requête selon la réponse reçue ; elle ne signifie pas que le rapport est déjà disponible ou que les graines ont toutes reçu le message. Votre tâche CI devrait donc conserver des états distincts, par exemple « requête envoyée », « rapport en attente », « rapport consulté » et « réception métier vérifiée ». Évitez de transformer la réponse HTTP en assertion globale « placement réussi ».
| Événement dans le pipeline | Clé à utiliser | Action attendue | Erreur à éviter |
|---|---|---|---|
| La connexion a échoué et le résultat de l’envoi est incertain | La clé de l’activité en cours | Reprendre la requête avec la même clé et conserver la trace de la tentative | Créer immédiatement une clé neuve et déclencher un test distinct |
| La requête a été acceptée, mais le rapport n’est pas encore disponible | La clé déjà associée à l’envoi | Attendre, puis vérifier le rapport correspondant à cette exécution | Déclarer l’échec du placement sur la seule base d’un rapport momentanément absent |
| Vous lancez volontairement une nouvelle campagne de test | Une nouvelle clé logique | Enregistrer la nouvelle exécution et son contexte | Réutiliser une clé précédente en supposant qu’elle produira toujours un rapport neuf |
Comment empêcher les nouvelles tentatives CI de créer des tests en double ? Faites dépendre la clé d’un identifiant stable de l’activité logique, comme l’exécution de recette ou le scénario concerné, et non du numéro de tentative réseau. La documentation précise que la même clé réutilisée pendant sept jours ne crée pas un nouveau test. Une nouvelle clé est pertinente quand vous voulez une nouvelle mesure, pas simplement parce qu’un appel a expiré ou qu’un agent CI a redémarré.
Mailgun indique également qu’un compte ne peut conserver qu’un nombre limité de clés. Comme cette limite peut influencer les tests fréquents, vérifiez la règle en vigueur dans les instructions officielles d’envoi d’un test de graines avant d’augmenter la fréquence ou de générer des clés sans politique de rétention. Les sources consultées établissent l’existence de cette limite ; ne supposez pas qu’un nouveau nom de clé contournera une capacité de compte atteinte.
Au contrôle du rapport, examinez les preuves dans l’ordre
Quand un rapport n’apparaît pas, commencez par les faits enregistrés, pas par une nouvelle exécution aveugle. Vérifiez que le compte a bien accès à Inbox Placement, que la requête comportait le champ attendu, et que la clé n’a pas déjà été utilisée dans la période d’idempotence. Puis contrôlez la réponse d’envoi et l’état d’acheminement vers le test de graines.
Que vérifier lorsque le rapport Inbox Placement de Mailgun ne contient pas encore de résultat ? Vérifiez d’abord si vous interrogez la bonne exécution et la bonne clé, puis si les messages destinés aux graines ont terminé leur envoi. La documentation de Mailgun distingue les résultats disponibles des états où une graine n’a pas encore reçu le message ; un statut Missing ne prouve donc pas, à lui seul, une perte définitive. Appliquez le délai et les critères de décision décrits dans le guide officiel de test de graines, au lieu de faire échouer le pipeline dès la première consultation.
Consignez au minimum les éléments suivants, avec les secrets retirés des journaux :
- la clé logique de l’activité et son environnement ;
- l’heure de la requête et sa réponse Send API ;
- le moment où le rapport a été consulté, ainsi que son état ;
- les résultats par graine, lorsque le rapport les expose ;
- le résultat séparé de la réception contrôlée et du contrôle métier.
La documentation du rapport Inbox Placement décrit l’accès aux informations de rapport. Utilisez-la pour interpréter les champs réellement disponibles dans votre compte. Évitez de déduire une panne de votre application à partir d’un champ isolé sans vérifier le chemin d’envoi et l’état de réception des graines.
Le résultat est circonscrit à la configuration du test et à son environnement de graines. Il peut révéler un problème de placement dans ce cadre, mais ne constitue pas une mesure exhaustive de la réception de tous vos destinataires. Pour les paramètres qui influencent la distribution, la documentation d’Inbox Placement fournit également les instructions d’envoi associées au test ; elles doivent être lues avec le guide de rapport, et non interprétées comme une garantie universelle.
À l’acceptation, reliez le rapport au parcours réel
Une intégration fiable suit une chronologie de preuves, plutôt qu’un seul indicateur final. Au début, le journal CI établit quel code et quelle configuration ont lancé le scénario. Ensuite, la réponse Send API confirme le traitement de la requête. Le rapport Inbox Placement apporte une observation distincte des boîtes de test. Enfin, une réception contrôlée permet de vérifier que le message attendu est lisible et que l’action métier fonctionne.
Si les graines montrent une réception, faut-il encore tester le courriel de validation ? Oui, si votre objectif est de valider l’inscription ou la récupération de compte. Le rapport de graines ne démontre pas que votre application a généré le bon lien, que celui-ci pointe vers le bon environnement, qu’il modifie l’état du compte, ni que la page de destination s’ouvre correctement. Ces contrôles nécessitent un scénario de bout en bout distinct.
Pour une validation d’inscription, un scénario de recette peut donc : créer un compte de test dans l’environnement autorisé, déclencher l’envoi par le chemin normal du produit, attendre le rapport de graines sans confondre cette attente avec la réception métier, puis contrôler l’arrivée du message sur une adresse de test et suivre le lien dans le navigateur de test. Si le courriel contient un jeton à usage unique, ne l’imprimez pas dans les journaux CI et invalidez ou réinitialisez le compte de test selon les règles de votre application.
Une adresse temporaire peut être utile pour cette réception contrôlée si le scénario ne demande ni suivi durable ni réponse depuis la boîte. Elle ne doit pas remplacer l’adresse associée à un compte important qui nécessitera une récupération ultérieure. Avant de l’intégrer à un test récurrent, examinez aussi la durée de conservation nécessaire : ce guide consacré à la durée de vie d’une boîte de réception temporaire aide à distinguer une vérification ponctuelle d’un besoin d’archivage ou de réutilisation.
Pour décider de la portée de votre porte de CI, séparez les critères : faites échouer le contrôle d’envoi si la requête est rejetée, le contrôle de rapport si l’état ne satisfait pas le seuil défini pour votre test, et le contrôle métier si le message ou le lien de validation est incorrect. Une absence momentanée de rapport peut appeler une attente et une nouvelle consultation ; elle ne devrait pas être traitée automatiquement comme un échec métier. À l’inverse, un rapport consultable ne doit pas masquer un lien cassé.
Après la recette, conservez une politique de test explicite
Les avantages de cette approche sont la traçabilité des exécutions, la réduction des doublons causés par les reprises et une séparation claire entre placement observé et expérience réelle. Sa limite est tout aussi importante : le rapport de graines n’est pas un reçu de livraison individuel pour chaque utilisateur. Il faut donc définir ce que votre équipe considère comme preuve suffisante, et garder la réception contrôlée pour les fonctions qui engagent l’utilisateur.
Dans votre configuration, documentez le propriétaire du test, l’environnement autorisé, la règle de création d’une nouvelle clé et les conditions de reprise. Précisez aussi si un rapport incomplet bloque une fusion, déclenche une nouvelle vérification ou requiert un examen humain. Ce choix dépend du rôle du courriel : un message informatif peut avoir un seuil différent d’un lien nécessaire à l’activation d’un compte.
Si votre contrôle porte uniquement sur la réception ponctuelle d’un courriel de test, Mailtock peut être une option à examiner pour disposer d’une boîte temporaire séparée de votre adresse de travail. Vérifiez les modalités affichées avant d’en faire une dépendance automatisée ; ne confondez jamais cette réception indépendante avec les graines Inbox Placement de Mailgun, ni avec une garantie de placement. Pour une vérification manuelle distincte de votre envoi de test, vous pouvez consulter Mailtock.
Cet article propose des conseils pour gérer les e-mails liés aux achats et ne remplace pas les instructions du commerçant concernant les commandes, les désinscriptions ou la confidentialité. Les démarches et délais applicables sont ceux définis par le service concerné.