Intégration Email Mailtrap
Patrons 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 de livraison courants.
Quand activer
- Implémenter une fonctionnalité "envoyer un 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'emails d'un projet
- Réviser du 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 délivrer, utilisée pour le développement/validation afin que les emails de test n'atteignent jamais les boîtes de réception réelles. L'envoi en production utilise un endpoint distinct avec domaine vérifié. Ne jamais pointer un environnement de développement vers l'endpoint d'envoi de production.
Authentification. Les requêtes utilisent un jeton Bearer dans l'en-tête Authorization. Les jetons sont limités par projet ; le sandbox et la production utilisent généralement des jetons différents.
Vérification du 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 délivre à des destinataires réels. Négliger cela entraîne des échecs de livraison silencieux ou un placement dans les spams.
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(`Email send failed: ${response.status}`);
}
return response.json();
}
// Même appel, routé vers le 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 | À la place |
|---|---|---|
| Utiliser l'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 l'endpoint Sandbox |
| Coder en dur les jetons API dans le code source | Risque de fuite d'identifiants si commité dans le contrôle de version | Charger les jetons depuis les variables d'environnement / gestionnaire de secrets |
| Envoyer avant la fin de la vérification du domaine | Les emails échouent silencieusement ou atterrissent dans les spams | Vérifier les enregistrements SPF/DKIM/DMARC avant d'activer l'envoi en production |
| Absence de gestion des erreurs/retentatives sur les échecs d'envoi | Échecs silencieux de notification (ex. l'utilisateur ne reçoit jamais l'email de réinitialisation de mot de passe) | Vérifier le statut de la réponse, enregistrer les échecs, remonter des erreurs exploitables |
Bonnes pratiques
- Conserver les jetons sandbox et production dans des variables d'environnement séparées, ne jamais partager un jeton entre les environnements
- Vérifier les enregistrements DNS du domaine d'envoi avant tout lancement en production impliquant des emails
- Enregistrer les échecs de livraison avec suffisamment de contexte pour le débogage (destinataire, modèle, horodatage, code de réponse)
- Traiter l'envoi d'email comme un appel réseau faillible : encapsuler dans try/catch, ne jamais supposer le succès
Compétences associées
api-and-interface-design, security-and-hardening, ci-cd-and-automation