Dev Life
Erstellen von Transaktions-E-Mail-Workflows für Bestellbestätigungen mit der API von Mailgun
Im Gegensatz zu Marketing-E-Mails werden Transaktions-E-Mails (wie Bestellbestätigungen, Versandbenachrichtigungen und das Zurücksetzen von Passwörtern) durch bestimmte Nutzeraktionen ausgelöst und bieten Echtzeit-Aktualisierungen zu ihren Interaktionen mit Ihrer Plattform. Sie helfen dabei, Vertrauen aufzubauen, Support-Anfragen zu reduzieren und sorgen für ein reibungsloses Einkaufserlebnis.
Bestellbestätigungen sind besonders wichtig, da sie Ihre Kunden wissen lassen, dass ihr Kauf erfolgreich war, und dem Nutzer einen Nachweis der Transaktionsdetails bieten.
In diesem Tutorial erfahren Sie, wie Sie mit der API von Mailgun einen Transaktions-E-Mail-Workflow für Bestellbestätigungen erstellen.
Implementierung von Transaktions-E-Mail-Workflows für Bestellbestätigungen
Bevor Sie beginnen, stellen Sie sicher, dass Sie ein Mailgun-Konto und Node.js auf Ihrem Rechner installiert haben.
Sobald Ihr Konto registriert und aktiviert ist, klicken Sie auf Konto erstellen und dann auf API-Schlüssel erstellen, um eine kurze Beschreibung für den Schlüssel anzugeben. Sobald dieser generiert ist, kopieren und speichern Sie den API-Schlüssel an einem sicheren Ort.
Dieser Schlüssel wird verwendet, um Ihre Anfragen an die API von Mailgun zu authentifizieren.
Um es einfach zu halten, klonen Sie das folgende UI-Repository und richten Sie die Umgebungsvariablen ein, indem Sie die folgenden npm-Befehle ausführen:
$ 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
Dieser Befehl fügt die Bibliotheken mailgun.js, form-data, cors, dotenv und express zur Verwendung im Backend-Server hinzu und erstellt einige Platzhalterwerte für den Mailgun-API-Schlüssel und die Domain in einer .env-Datei, die Sie während des Tutorials aktualisieren werden.
Die Mailgun-Domain bietet Ihnen die Möglichkeit, Ihre eigene individualisierbare Domain einzurichten oder eine Sandbox für Testzwecke zu nutzen. In diesem Tutorial werden Sie eine Sandbox-Domain verwenden. Sie finden die Sandbox-Domain von Mailgun, indem Sie in Ihrem Dashboard zu Mailgun Send > Versand > Domain-Einstellungen navigieren und auf den Select-Button in der API-Integrationsoption klicken:
Ihre Sandbox-Domain ist in den für die Mailgun-Einrichtung bereitgestellten Boilerplates enthalten. Denken Sie daran, den Wert von MAILGUN_DOMAIN (derzeit your_domain_here) in der .env-Datei zu aktualisieren.
Wenn Sie eine individualisierbare Domain einrichten möchten, befolgen Sie die detaillierten Anweisungen in diesem YouTube-Tutorial.
Die Oberfläche der Anwendung
In diesem Szenario arbeiten Sie mit einer einfachen Warenkorb-Anwendung, die mit HTML, CSS und JavaScript erstellt wurde. Die Anwendung ermöglicht es Nutzern, Artikel zu ihrem Warenkorb hinzuzufügen, Mengen anzupassen und zur Kasse zu gehen. Wenn der Nutzer seinen Kauf bestätigt, sendet die Anwendung eine Anfrage an das Backend, um die Bestellung zu verarbeiten und eine Bestätigungs-E-Mail zu versenden. Um eine Vorschau der Benutzeroberfläche anzuzeigen, öffnen Sie die Datei ui/index.html im Browser oder führen Sie den Python-Befehl python3 -m http.server -d=./ui: aus.
Diese Benutzeroberfläche wurde mit Fokus auf ein nahtloses Checkout-Erlebnis intuitiv gestaltet. Das Backend übernimmt die Hauptarbeit, einschließlich der Verarbeitung von Bestellungen und dem Versand von Bestätigungs-E-Mails.
Einrichten der Mailgun-Verbindung
Um Mailgun in Ihr Backend zu integrieren, müssen Sie den Mailgun-Client mit Ihrem API-Schlüssel initialisieren. So richten Sie die Verbindung in Ihrem Node.js-Backend ein:
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;
Dieser Code initialisiert den Mailgun-Client, der verwendet wird, um Transaktions-E-Mails zu versenden. Stellen Sie sicher, dass Sie den Wert von MAILGUN_API_KEY (derzeit your_api_key_here) in Ihrer .env-Datei aktualisieren, bevor Sie fortfahren.
Testen Sie die Verbindung, indem Sie eine Test-E-Mail versenden:
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
Sie können die von Mailgun bereitgestellte Sandbox-Domain zum Testen verwenden, müssen jedoch mindestens eine verifizierte E-Mail-Adresse für Testzwecke hinzufügen (bis zu fünf). Um Ihre Test-E-Mail-Adresse zu verifizieren, gehen Sie in Ihrem Mailgun-Dashboard zu Mailgun Send > Versand > Domain-Einstellungen. Geben Sie dann Ihre E-Mail-Adresse in das dafür vorgesehene Eingabefeld ein und klicken Sie auf Add. Mailgun wird eine Verifizierungs-E-Mail an diese Adresse versenden.
Überprüfen Sie Ihren Posteingang und klicken Sie auf den Validierungslink I Agree, um den Vorgang abzuschließen und sich als autorisierter Testempfänger zu registrieren:
Design der E-Mail-Vorlage
Transaktions-E-Mails erfordern oft dynamischen Content, wie den Namen des Nutzers, Bestelldetails und Versandinformationen, weshalb Sie eine HTML-Vorlage mit Platzhaltern für dynamische Daten erstellen müssen. Hier ist ein Beispiel für eine einfache Vorlage für eine Bestellbestätigung:
<!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>
Sie können eine Templating-Engine wie Handlebars oder EJS verwenden, um die Platzhalter durch tatsächliche Daten zu ersetzen, bevor Sie die E-Mail versenden. Sie können auch den intuitiven visuellen Builder von Mailgun verwenden, um schöne, responsive E-Mail-Vorlagen ohne Programmierkenntnisse zu erstellen.
In diesem Artikel verwenden Sie die einfachste Form des Templatings: die String-Interpolation mithilfe von JavaScript-Template-Literalen. Dieser Ansatz ermöglicht es Ihnen, eine HTML-E-Mail-Vorlage einzurichten, die mit den erforderlichen dynamischen Daten gefüllt wird:
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};
Dieser Code durchläuft die Artikel einer Bestellung, um eine tabellenartige Quittung der Bestellung des Kunden zu generieren. Der zurückgegebene Wert, itemsList, ist ein String-Literal, das verwendet wird, um den Rest der E-Mail-Vorlage wie folgt zu erstellen:
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}
Hier kombinieren Sie die Quittung mit dem Rest eines HTML-Vorlagen-Strings, der die Kundendetails enthält. Das HTML enthält ein Basic-Styling für die E-Mail-Vorlage.
Erfahren Sie mehr in unserer Vorlagen für Transaktions-E-Mails Seite, einschließlich des Herunterladens von kostenlosen Vorlagen.
Implementierung der Funktion für den E-Mail-Versand
Nun, da Ihre Vorlage bereit ist, ist es an der Zeit, die Funktion zu schreiben, die die E-Mail mithilfe der API von Mailgun versendet. So können Sie diese Funktionalität in Ihrem Backend implementieren:
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}
Diese Funktion nimmt ein Bestellobjekt entgegen, erstellt den E-Mail-Inhalt und versendet ihn über die API von Mailgun. Die Optionen o:tag und o:tracking ermöglichen es Ihnen, die Zustellung und Interaktion der E-Mail zu verfolgen.
Lassen Sie uns nun die Implementierung mit einem einfachen Bestellobjekt testen, um zu sehen, ob sie funktioniert:
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 });
Führen Sie diesen Code mit node ./src/server.js aus und überprüfen Sie Ihren Posteingang (denken Sie daran, eine verifizierte E-Mail-Adresse für den Wert testOrder.customer.email zu verwenden, wenn Sie die Sandbox-Domain von Mailgun nutzen). Sie sollten eine Basic-Bestellbestätigungs-E-Mail mit den Testdaten erhalten:
Bei dieser Einrichtung wird jeder auftretende Fehler an den Aufrufer weitergegeben, und die .catch-Methode gibt Protokolle auf der Standardausgabe aus. Dieser Ansatz ermöglicht es Ihnen, Probleme, die während des E-Mail-Versands auftreten könnten, schnell zu identifizieren und zu beheben.
Im nächsten Abschnitt werden Sie dies mit Ihrem Frontend verbinden, damit Sie echte Bestelldaten von Kunden-Checkouts versenden können.
Integration mit Anwendungs-Events
Um sicherzustellen, dass der E-Mail-Workflow automatisch ausgelöst wird, wenn eine Bestellung bestätigt wird, müssen Sie einen Event-Listener oder Route in Ihrer Anwendung einrichten.
Hier werden Sie eine Express.js-Anwendung einrichten und eine Route definieren, die Bestellbestätigungen verarbeitet, während sie die Funktion sendOrderConfirmationEmail aufruft:
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});
Die Route /api/orders verarbeitet eingehende Bestellanfragen, erstellt ein order-Objekt und versendet eine Bestätigungs-E-Mail mithilfe der Funktion sendOrderConfirmationEmail. Der Rest der Route enthält eine einfache Logik für das Fehler-Reporting, aber in der Produktion möchten Sie vielleicht einen Wiederholungsmechanismus oder einen robusteren Error-Handler implementieren.
Testen des Workflows
Um die bisherige Einrichtung zu testen, müssen Sie die Datei /ui/index.html modifizieren. Suchen Sie zunächst die Codezeile, in der das orderData-Objekt definiert ist, und aktualisieren Sie die E-Mail-Eigenschaft des Kunden (orderData.customer.email), um eine Ihrer verifizierten E-Mails zu verwenden. Sie müssen auch die Konstante api aktualisieren, damit sie auf die URL Ihres Servers verweist.
Öffnen Sie dann die Datei /ui/index.html in einem Browser und lösen Sie den Checkout-Vorgang aus, indem Sie Artikel für den Checkout auswählen und auf den Button Checkout Selected Items klicken. Dies sollte einen Bestätigungsdialog öffnen, in dem Sie auf Confirm Purchase klicken können, um den Checkout-Prozess abzuschließen:
Überprüfen Sie Ihren E-Mail-Posteingang und vergewissern Sie sich, dass die E-Mail versendet und mit dem dynamischen Content korrekt gerendert wurde. Wenn Sie die Sandbox-Domain verwendet haben, müssen Sie möglicherweise Ihren Spam-Ordner überprüfen:
Denken Sie daran, zu testen, wie Ihre Anwendung mit Fehlern umgeht, wie z. B. ungültigen E-Mail-Adressen oder API-Ausfallzeiten, indem Sie absichtlich falsche Werte verwenden und überprüfen, ob Ihre Fehlerbehandlung wie erwartet funktioniert.
Der gesamte in diesem Tutorial verwendete Code ist verfügbar auf GitHub.
Überwachung und Verwaltung von E-Mails
Mailgun bietet detaillierte Metriken und Tracking-Funktionen, mit denen Sie die Leistung Ihrer Transaktions-E-Mails überwachen können. Zusätzlich zur Bearbeitung von Bounces oder Fehlern können Sie Zustellraten und Öffnungsraten direkt vom Mailgun-Dashboard aus verfolgen.
Um auf die Protokolle jeder versendeten E-Mail zuzugreifen, navigieren Sie in Ihrem Mailgun-Konto zum Abschnitt Mailgun Send > Kampagnenübersicht > Protokolle. Hier können Sie den Zeitstempel und Status jeder versendeten E-Mail sehen, einschließlich der Information, ob sie zugestellt, geöffnet oder abgelehnt wurde:
Sie können auf einen beliebigen Protokolleintrag klicken, um dessen vollständige Details anzuzeigen, wie z. B. geolocation für geöffnete E-Mails, delivery-status für zugestellte E-Mails und andere:
Sie können auch zu Mailgun Send > Kampagnenübersicht > Metrics gehen, um eine grafische Aufschlüsselung der wichtigsten E-Mail-Metriken anzuzeigen, einschließlich der Anzahl der versendeten, zugestellten, fehlgeschlagenen und geöffneten E-Mails:
Zusammenfassung
Sie haben soeben einen funktionierenden Bestellbestätigungs-Workflow mit der API von Mailgun erstellt.
Transaktions-E-Mails wie diese halten Kunden direkt nach dem Checkout auf dem Laufenden, was Support-Tickets reduziert und das Vertrauen ohne zusätzlichen Aufwand stärkt. Bestellbestätigungen sind nicht die einzigen Workflows, die für Verbraucher von Bedeutung sind. Sehen Sie sich unser Tutorial über passwort zurücksetzen an, um Ihre Transaktions-E-Mails weiter zu optimieren.
