Intégration Email Mailtrap
Modèles pour ajouter l'envoi d'emails transactionnels à une application en utilisant l'API Email et le Sandbox de Mailtrap, couvrant l'authentification, la séparation des environnements, et les pièges courants de livraison.
Quand Activer
- Implémenter une fonctionnalité d'« envoi d'email » (confirmation d'inscription, réinitialisation de mot de passe, notifications, reçus)
- Déboguer pourquoi les emails n'arrivent pas en développement/validation
- Mettre en place la première intégration d'envoi d'email d'un projet
- Examiner un code qui appelle une API email directement sans séparation sandbox
Concepts Clés
Séparation Sandbox vs. Production. Mailtrap fournit une API Sandbox qui capture les emails sans les livrer, utilisée pour le développement/validation afin que les emails de test n'atteignent jamais les vraies boîtes de réception. L'envoi en production utilise un endpoint distinct avec domaine vérifié. Ne pointez jamais un environnement de développement vers le endpoint d'envoi de production.
Authentification. Les requêtes utilisent un token Bearer dans l'en-tête Authorization. Les tokens sont limités par projet ; le sandbox et la production utilisent généralement des tokens différents.
Vérification de domaine. L'envoi en production nécessite de vérifier un domaine d'envoi via des enregistrements DNS (SPF, DKIM, DMARC) avant que Mailtrap ne livre aux destinataires réels. Ignorer cela provoque des échecs de livraison silencieux ou un placement dans le spam.
Exemples de Code
// Envoi via l'API Email de Mailtrap (production)
async function sendEmail(to: string, subject: string, html: string) {
const response = await fetch("https://send.api.mailtrap.io/api/send", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.MAILTRAP_API_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
from: { email: "[email protected]", name: "Your App" },
to: [{ email: to }],
subject,
html,
}),
});
if (!response.ok) {
throw new Error(`Échec de l'envoi d'email : ${response.status}`);
}
return response.json();
}
// Même appel, routé vers Sandbox dans les environnements non-production
const MAILTRAP_ENDPOINT = process.env.NODE_ENV === "production"
? "https://send.api.mailtrap.io/api/send"
: `https://sandbox.api.mailtrap.io/api/send/${process.env.MAILTRAP_INBOX_ID}`;
Anti-Patrons
| Anti-Patron | Pourquoi c'est un Problème | Alternative |
|---|---|---|
| Utiliser le endpoint de production en développement/test | De vrais emails de test atteignent de vraies boîtes de réception, risquant des plaintes pour spam et une fuite de données de test | Router les environnements non-production vers le endpoint Sandbox |
| Hardcoder les tokens API dans le code source | Risque de fuite d'identifiants si commité dans le contrôle de version | Charger les tokens depuis des variables d'environnement / gestionnaire de secrets |
| Envoyer avant la vérification de domaine | Les emails échouent silencieusement ou atterrissent dans le spam | Vérifier les enregistrements SPF/DKIM/DMARC avant d'activer l'envoi en production |
| Absence de gestion des erreurs / retry sur les échecs d'envoi | Échecs silencieux des notifications (ex. l'utilisateur ne reçoit jamais l'email de réinitialisation de mot de passe) | Vérifier le statut de la réponse, journaliser les échecs, remonter des erreurs exploitables |
Bonnes Pratiques
- Garder les tokens sandbox et production dans des variables d'environnement séparées, ne jamais partager un token entre environnements
- Vérifier les enregistrements DNS du domaine d'envoi avant tout lancement en production impliquant des emails
- Journaliser les échecs de livraison avec suffisamment de contexte pour déboguer (destinataire, modèle, horodatage, code de réponse)
- Traiter l'envoi d'email comme un appel réseau faillible : envelopper dans try/catch, ne jamais supposer le succès
Compétences Connexes
api-and-interface-design, security-and-hardening, ci-cd-and-automation