Dev Life
Créer des scénarios d’emails transactionnels pour les confirmations de commande avec l’API de Mailgun
Contrairement aux emails de marketing, les emails transactionnels (tels que les confirmations de commande, les notifications d’expédition et les réinitialisations de mot de passe) sont déclenchés par des actions spécifiques des utilisatrices et fournissent des mises à jour en temps réel sur leurs interactions avec votre plateforme. Ils aident à instaurer la confiance, à réduire les questions adressées au support et à offrir une expérience d’achat fluide.
Les confirmations de commande sont particulièrement importantes, car elles permettent à vos clients de savoir que leur achat a réussi et fournissent à l’utilisatrice un enregistrement des détails de la transaction.
Dans ce tutoriel, vous apprendrez à créer un scénario d’email transactionnel pour les confirmations de commande à l’aide de l’API de Mailgun.
Mettre en œuvre des scénarios d’emails transactionnels pour les confirmations de commande
Avant de débuter, assurez-vous d’avoir Compte Mailgun et Node.js installé sur votre machine.
Une fois que vous vous êtes inscrit et que votre compte est activé, cliquez sur Commencer maintenant, puis sur Créer une clé API pour fournir une courte description de la clé. Une fois qu’elle est générée, copiez et sauvegardez la clé API en lieu sûr.
Cette clé sera utilisée pour authentifier vos requêtes vers l’API de Mailgun.
Pour faire simple, clonez le dépôt d’interface utilisateur suivant et configurez les variables d’environnement en exécutant les commandes npm suivantes :
$ git clone https://github.com/Ikeh-Akinyemi/draftdev-mailgunnerrn$ cd draftdev-mailgunner; npm install rn$ echo -e "MAILGUN_API_KEY=your_api_key_here
MAILGUN_DOMAIN=your_domain_here
PORT=8080" >> .env
Cette commande ajoute les bibliothèques mailgun.js, form-data, cors, dotenv et express pour une utilisation dans le serveur backend et crée des éléments de substitution pour la clé API de Mailgun et le domaine dans un fichier .env que vous mettrez à jour pendant le tutoriel.
Le domaine Mailgun vous donne l’option de configurer votre propre domaine personnalisé ou d’utiliser une sandbox à des fins de test. Vous utiliserez un domaine sandbox dans ce tutoriel. Vous pouvez trouver le domaine sandbox de Mailgun en accédant à Mailgun Send > Envois > Paramètres du domaine sur votre tableau de bord et en cliquant sur le bouton Sélectionner dans l’option d’intégration d’API :
Votre domaine sandbox est inclus dans les modèles de base fournis pour la configuration de Mailgun. N’oubliez pas de mettre à jour la valeur de MAILGUN_DOMAIN (actuellement your_domain_here) dans le fichier .env.
Si vous souhaitez configurer un domaine personnalisé, suivez les instructions détaillées dans ce tutoriel YouTube.
L’interface de l’application
Dans ce scénario, vous travaillerez avec une simple application de panier d’achat construite avec HTML, CSS et JavaScript. L’application permet aux utilisatrices d’ajouter des articles à leur panier, d’ajuster les quantités et de passer à la caisse. Lorsque l’utilisatrice confirme son achat, l’application envoie une requête au backend pour traiter la commande et envoyer un email de confirmation. Pour prévisualiser l’interface utilisateur, ouvrez le fichier ui/index.html dans le navigateur ou exécutez la commande Python python3 -m http.server -d=./ui:
Cette interface utilisateur a un design intuitif, axé sur la fourniture d’une expérience de paiement fluide. Le backend gère le gros du travail, y compris le traitement des commandes et l’envoi d’emails de confirmation.
Configuration de la connexion Mailgun
Pour intégrer Mailgun dans votre backend, vous devez initialiser le client Mailgun à l’aide de votre clé API. Voici comment configurer la connexion dans votre backend Node.js :
const formData = require('form-data');rnconst Mailgun = require('mailgun.js');rnrnconst mailgun = new Mailgun(formData);rnconst mg = mailgun.client({ username: 'api', key: process.env.MAILGUN_API_KEY });rnconst MAILGUN_DOMAIN = process.env.MAILGUN_DOMAIN;
Ce code initialise le client Mailgun, qui sera utilisé pour envoyer des emails transactionnels. Assurez-vous de mettre à jour la valeur de MAILGUN_API_KEY (actuellement your_api_key_here) dans votre fichier .env avant de continuer.
Testez la connexion en envoyant un email de test :
mg.messages.create('<your-domain.com>', {rn from: "Excited User <mailgun@your-domain.com>",rn to: ["test@example.com"],rn subject: "Hello",rn text: "Testing some Mailgun awesomeness!"rn})rn.then(msg => console.log(msg)) // logs response datarn.catch(err => console.error(err)); // logs any error
Vous pouvez utiliser le domaine sandbox fourni par Mailgun pour les tests, mais vous devez ajouter au moins un email vérifié pour les tests (jusqu’à cinq). Pour vérifier votre adresse email de test, accédez à Mailgun Send > Envois > Paramètres du domaine dans votre tableau de bord Mailgun. Ensuite, entrez votre adresse email dans le champ de saisie désigné et cliquez sur Ajouter. Mailgun enverra un email de vérification à cette adresse.
Consultez votre boîte de réception et cliquez sur le lien de vérification J’accepte pour compléter le processus et vous inscrire en tant que destinataire de test autorisé :
Créer le design du modèle d’email
Les emails transactionnels nécessitent souvent un contenu dynamique, comme le nom de l’utilisatrice, les détails de la commande et les informations d’expédition, c’est pourquoi vous devez créer un modèle HTML avec des éléments de substitution pour les données dynamiques. Voici un exemple d’un modèle simple de confirmation de commande :
<!DOCTYPE html>rn<html>rn<head>rn <title>Order Confirmation</title>rn</head>rn<body>rn <h1>Thank you for your order, {{name}}!</h1>rn <p>Your order number is {{orderNumber}}.</p>rn <p>We will ship your items to {{shippingAddress}}.</p>rn</body>rn</html>
Vous pouvez utiliser un moteur de création de modèles comme Handlebars ou EJS pour remplacer les éléments de substitution par des données réelles avant d’envoyer l’email. Vous pouvez également utiliser l’éditeur visuel intuitif de Mailgun pour créer de superbes modèles d’emails en responsive design sans aucune connaissance en codage.
Dans cet article, vous utiliserez la forme la plus simple de création de modèles : l’interpolation de chaînes à l’aide des littéraux de gabarit JavaScript. Cette approche vous permet de configurer un modèle d’email HTML rempli des données dynamiques nécessaires :
function emailTemplate(order) {rn // Format items for emailrn const itemsList = order.items.map(item => {rn return `rn <tr>rn <td style="padding: 10px 0; border-bottom: 1px solid #eee;">rn ${item.name}rn </td>rn <td style="padding: 10px 0; border-bottom: 1px solid #eee; text-align: center;">rn ${item.quantity}rn </td>rn <td style="padding: 10px 0; border-bottom: 1px solid #eee; text-align: right;">rn $${item.price.toFixed(2)}rn </td>rn <td style="padding: 10px 0; border-bottom: 1px solid #eee; text-align: right;">rn $${(item.price * item.quantity).toFixed(2)}rn </td>rn </tr>rn `;rn }).join('');rn};
Ce code itère sur les articles d’une commande pour générer un reçu sous forme de tableau de la commande du client. La valeur renvoyée, itemsList, est une chaîne littérale qui sera utilisée pour construire le reste du modèle d’email comme ceci :
function emailTemplate(order) {rn ...rnrn // Create email HTML templatern const emailHtml = `rn <!DOCTYPE html>rn <html>rn <head>rn <style>rn body { font-family: Arial, sans-serif; line-height: 1.6; color: #333; }rn .container { max-width: 600px; margin: 0 auto; }rn .header { background-color: #f8f9fa; padding: 20px; text-align: center; }rn .content { padding: 20px; }rn .order-details { margin-top: 20px; }rn .order-table { width: 100%; border-collapse: collapse; }rn .order-table th { text-align: left; padding: 10px 0; border-bottom: 2px solid #ddd; }rn .footer { margin-top: 30px; text-align: center; font-size: 14px; color: #777; }rn .total-row { font-weight: bold; }rn </style>rn </head>rn <body>rn <div class="container">rn <div class="header">rn <h2>Order Confirmation</h2>rn <p>Thank you for your purchase!</p>rn </div>rnrn <div class="content">rn <p>Hello ${order.customer.name},</p>rnrn <p>Your order has been confirmed. Here are your order details:</p>rnrn <div class="order-details">rn <p><strong>Order ID:</strong> ${order.id}</p>rn <p><strong>Order Date:</strong> ${new Date(order.createdAt).toLocaleString()}</p>rnrn <table class="order-table">rn <thead>rn <tr>rn <th>Item</th>rn <th style="text-align: center;">Qty</th>rn <th style="text-align: right;">Price</th>rn <th style="text-align: right;">Total</th>rn </tr>rn </thead>rn <tbody>rn ${itemsList}rn <tr>rn <td colspan="3" style="text-align: right; padding-top: 20px;"><strong>Subtotal:</strong></td>rn <td style="text-align: right; padding-top: 20px;"><strong>$${order.subtotal.toFixed(2)}</strong></td>rn </tr>rn <tr>rn <td colspan="3" style="text-align: right;"><strong>Tax:</strong></td>rn <td style="text-align: right;"><strong>$${order.tax.toFixed(2)}</strong></td>rn </tr>rn <tr class="total-row">rn <td colspan="3" style="text-align: right; padding-top: 10px;"><strong>Total:</strong></td>rn <td style="text-align: right; padding-top: 10px;"><strong>$${order.total.toFixed(2)}</strong></td>rn </tr>rn </tbody>rn </table>rn </div>rnrn <div style="margin-top: 30px;">rn <p><strong>Shipping Address:</strong></p>rn <p>rn ${order.shipping.address}<br>rn ${order.shipping.city}, ${order.shipping.state} ${order.shipping.zipCode}rn </p>rn </div>rnrn <div style="margin-top: 30px;">rn <p><strong>Payment Method:</strong> ${order.payment.method} (ending in ${order.payment.last4})</p>rn </div>rnrn <div style="margin-top: 30px;">rn <p>If you have any questions about your order, please contact our customer support.</p>rn <p>Thank you for shopping with us!</p>rn </div>rn </div>rnrn <div class="footer">rn <p>This is an automated email, please do not reply to this message.</p>rn <p>© 2025 Your Company. All rights reserved.</p>rn </div>rn </div>rn </body>rn </html>rn `;rnrn return emailHtml;rn}
Ici, vous combinez le reçu avec le reste d’une chaîne de modèle HTML contenant les détails du client. Le code HTML contient un style de base pour le modèle d’email.
En savoir plus depuis notre Des modèles d’emails transactionnels page, y compris le téléchargement de modèles gratuits.
Mise en œuvre de la fonctionnalité d’envoi d’emails
Maintenant que votre modèle est prêt, il est temps d’écrire la fonction qui envoie l’email à l’aide de l’API de Mailgun. Voici comment vous pouvez mettre en œuvre cette fonctionnalité dans votre backend :
async function sendOrderConfirmationEmail(order) {rn try {rnrn let emailHtml = emailTemplate(order)rnrn // Send email via Mailgunrn const response = await mg.messages.create(MAILGUN_DOMAIN, {rn from: `Your Store <orders@${MAILGUN_DOMAIN}>`,rn to: order.customer.email,rn subject: `Order Confirmation #${order.id}`,rn html: emailHtml,rn 'o:tag': ['order-confirmation'],rn 'o:tracking': truern });rnrn console.log('Email sent successfully:', response);rn return response;rnrn } catch (error) {rn console.error('Error sending confirmation email:', error);rn throw error;rn }rn}
Cette fonction prend un objet de commande, construit le contenu d’email et l’envoie à l’aide de l’API de Mailgun. Les options o:tag et o:tracking vous permettent de suivre la livraison et l’engagement de l’email.
Maintenant, testons l’implémentation avec un simple objet de commande pour voir si cela fonctionne :
const testOrder = {rn id: "TEST123",rn customer: {rn name: "Test User",rn email: "your-verified-email@example.com" // Use one of your verified emails for testingrn },rn items: [rn { name: "Test Product", quantity: 1, price: 29.99 }rn ],rn subtotal: 29.99,rn tax: 2.99,rn total: 32.98,rn shipping: {rn address: "123 Test Street",rn city: "Test City",rn state: "TS",rn zipCode: "12345"rn },rn payment: {rn method: "Credit Card",rn last4: "4242"rn },rn createdAt: new Date()rn};rnrnsendOrderConfirmationEmail(testOrder)rn .then(response => {rn console.log('Test email sent successfully!');rn console.log('Message ID:', response.id);rn console.log('Message status:', response.status);rn })rn .catch(error => {rn console.error('Failed to send test email:', error.message);rn });
Exécutez ce code avec node ./src/server.js et consultez votre boîte de réception (n’oubliez pas d’utiliser un email vérifié pour la valeur testOrder.customer.email si vous utilisez le domaine sandbox de Mailgun). Vous devriez recevoir un email de confirmation de commande de base avec les données de test :
Dans cette configuration, toute erreur qui se produit est remontée à l’appelant, et la méthode .catch l’enregistre sur la sortie standard. Cette approche vous permet d’identifier et de résoudre rapidement les problèmes pouvant survenir lors du processus d’envoi d’emails.
Dans la section suivante, vous allez connecter ceci à votre frontend afin de pouvoir envoyer de vraies données de commande à partir des paiements clients.
Intégration avec les événements de l’application
Pour vous assurer que le scénario d’email est déclenché automatiquement lorsqu’une commande est confirmée, vous devez configurer un écouteur d’événement ou route dans votre application.
Ici, vous allez configurer une application Express.js et définir une route qui gère les confirmations de commande tout en appelant la fonction sendOrderConfirmationEmail :
const express = require('express');rnconst cors = require('cors');rn...rnrn// Load environment variablesrnrequire('dotenv').config();rnrn// Initialize Expressrnconst app = express();rnconst PORT = process.env.PORT || 3000;rnrn// Middlewarernapp.use(cors());rnapp.use(express.json());rnrnconst orders = [];rnrnapp.post('/api/orders', async (req, res) => {rn try {rn // Validate required fieldsrn if (!req.body.items || !req.body.customer || !req.body.customer.email) {rn return res.status(400).json({ rn success: false, rn error: 'Missing required order information' rn });rn }rnrn // Generate order IDrn const orderId = Date.now().toString(36) + Math.random().toString(36).substr(2, 5).toUpperCase();rnrn // Create order objectrn const order = {rn id: orderId,rn ...req.body,rn status: 'confirmed',rn createdAt: new Date()rn };rnrn // Save order (to database in a real app)rn orders.push(order);rnrn // Send confirmation emailrn await sendOrderConfirmationEmail(order);rnrn // Return success responsern res.status(201).json({rn success: true,rn order: {rn id: order.id,rn status: order.status,rn createdAt: order.createdAtrn },rn message: 'Order created successfully and confirmation email sent.'rn });rnrn } catch (error) {rn console.error('Error processing order:', error);rn res.status(500).json({rn success: false,rn error: 'Failed to process order'rn });rn }rn});
La route /api/orders gère les requêtes de commandes entrantes, crée un objet order et envoie un email de confirmation à l’aide de la fonction sendOrderConfirmationEmail. Le reste de la route inclut une logique simple de tableau de bord statistique pour les erreurs, mais en production, vous pourriez vouloir mettre en œuvre un mécanisme de réitération ou un gestionnaire d’erreurs plus robuste.
Tester le scénario
Pour tester la configuration jusqu’à présent, vous devez éditer le fichier /ui/index.html. Tout d’abord, trouvez la ligne de code où l’objet orderData est défini et mettez à jour la propriété d’email du client (orderData.customer.email) pour utiliser l’un de vos emails vérifiés. Vous devez également mettre à jour la constante api pour qu’elle pointe vers l’URL de votre serveur.
Ensuite, ouvrez le fichier /ui/index.html dans un navigateur et déclenchez le processus de paiement en sélectionnant des articles à payer et en cliquant sur le bouton Checkout Selected Items. Cela devrait ouvrir une boîte de dialogue de confirmation où vous pouvez cliquer sur Confirm Purchase pour compléter le processus de paiement :
Vérifiez votre boîte de réception d’emails et vérifiez que l’email a été envoyé et correctement affiché avec le contenu dynamique. Si vous avez utilisé le domaine sandbox, vous devrez peut-être vérifier votre dossier spam :
N’oubliez pas de tester la façon dont votre application gère les erreurs, telles que des adresses email invalides ou des interruptions d’API, en utilisant intentionnellement des valeurs incorrectes et en vérifiant que votre gestion des erreurs fonctionne comme prévu.
Tout le code utilisé dans ce tutoriel est disponible sur GitHub.
Suivi et gestion des emails
Mailgun fournit des statistiques détaillées et des fonctionnalités de suivi qui vous permettent de surveiller la performance de vos emails transactionnels. Vous pouvez suivre les taux de livraison et les taux d’ouverture en plus de gérer les erreurs ou les échecs directement depuis le tableau de bord Mailgun.
Pour accéder aux rapports de chaque email envoyé, accédez à la section Mailgun Send > Tableau de bord statistique > Rapports de votre compte Mailgun. Ici, vous pouvez voir l’horodatage et l’état du service de chaque email envoyé, y compris s’il a été livré, ouvert ou rejeté :
Vous pouvez cliquer sur n’importe quelle entrée de rapport pour afficher tous ses détails, comme geolocation pour les emails ouverts, delivery-status pour les emails livrés, et d’autres :
Vous pouvez également aller dans Mailgun Send > Tableau de bord statistique > Statistiques pour voir une répartition graphique des statistiques clés des emails, y compris le nombre d’emails envoyés, livrés, échoués et ouverts :
Conclusion
Vous venez de créer un scénario de confirmation de commande fonctionnel avec l’API de Mailgun.
Des emails transactionnels comme ceux-ci informent les clients juste après le paiement, ce qui réduit les tickets adressés au support et améliore la confiance sans frais supplémentaires. Les confirmations de commande ne sont pas les seuls scénarios qui comptent pour les consommateurs. Consultez notre tutoriel sur réinitialisations de mots de passe pour continuer à optimiser vos emails transactionnels.
