Comment envoyer un email transactionnel dans une application NodeJS en utilisant l’API de Mailgun

Non seulement vous pouvez obtenir un ré-engagement puissant basé sur des déclencheurs, des actions et des modèles, mais vous pouvez également communiquer des informations importantes automatiquement entre votre plateforme et un client.

Il est fort probable que vous ayez à envoyer des emails transactionnels automatisés au cours de votre carrière, si ce n’est pas déjà fait, tels que :

• Emails de confirmation
• Rappels de mot de passe

… et bien d’autres types de notifications.

Dans ce tutoriel, nous allons apprendre comment envoyer des emails transactionnels en utilisant l’API de Mailgun et une bibliothèque d’aide NodeJS.

• Envoyer un seul email transactionnel
• Envoyer une newsletter à une liste de contacts
• Ajouter des adresses email à une liste
• Envoyer une facture à une seule adresse email

Lors de l’envoi d’emails depuis une application Node.js, vous pouvez utiliser un client SMTP direct ou une API d’email. Traditionnellement, l’équipe de développement utilisait une bibliothèque comme Nodemailer pour configurer une connexion directe à un serveur SMTP. Bien que le SMTP vous donne du contrôle, il s’accompagne de plusieurs inconvénients, tels qu’une configuration complexe et une mauvaise délivrabilité. 

L’approche par API, comme celle utilisée par Mailgun, simplifie l’ensemble du processus. Au lieu de gérer le protocole sous-jacent, vous effectuez une simple requête HTTP. L’infrastructure robuste de Mailgun gère la communication SMTP pour vous, offrant une meilleure délivrabilité et des fonctionnalités intégrées telles que les statistiques et la validation des emails. 

Cette section vous guidera dans la configuration de votre projet et l’exécution de votre application. 

Nous supposons que vous avez installé et savez comment utiliser l’environnement NodeJS. 

La première chose que nous allons faire est de générer un fichier package.json dans un nouveau répertoire (/mailgun_nodetut, dans mon cas). Ce fichier contient des détails tels que le nom du projet et les dépendances requises. 

                                

                                    {
  "name": "mailgun-node-tutorial",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "express": "4",
    "jade": "*",
    "mailgun-js": "0.5"
  }
}
                                
                            

Comme vous pouvez le voir, nous allons utiliser expressjs pour la structure de notre application web, avec jade comme langage de templating, et enfin, une bibliothèque pour Node contribuée par la communauté par bojand. 

Dans le même dossier où vous avez créé le fichier package.json, créez deux dossiers supplémentaires : views/ js/ 

Tout est prêt, il vous suffit de vous connecter à Mailgun (c’est gratuit si ce n’est pas déjà fait), et d’obtenir votre clé API sur la première page du panneau de contrôle. 

Enregistrez le code ci-dessous sous app.js dans le répertoire racine de votre application (où se trouve package.json) 

                                

                                    //We're using the express framework and the mailgun-js wrapper
var express = require('express');
var Mailgun = require('mailgun-js');
//init express
var app = express();

//Your api key, from Mailgun’s Control Panel
var api_key = 'MAILGUN-API-KEY';

//Your domain, from the Mailgun Control Panel
var domain = 'YOUR-DOMAIN.com';

//Your sending email address
var from_who = 'your@email.com';

//Tell express to fetch files from the /js directory
app.use(express.static(__dirname + '/js'));
//We're using the Jade templating language because it's fast and neat
app.set('view engine', 'jade')

//Do something when you're landing on the first page
app.get('/', function(req, res) {
//render the index.jade file - input forms for humans
res.render('index', function(err, html) {
if (err) {
// log any error to the console for debug
console.log(err); 
}
else { 
//no error, so send the html to the browser
res.send(html)
};
});
});

// Send a message to the specified email address when you navigate to /submit/someaddr@email.com
// The index redirects here
app.get('/submit/:mail', function(req,res) {

//We pass the api_key and domain to the wrapper, or it won't be able to identify + send emails
var mailgun = new Mailgun({apiKey: api_key, domain: domain});

var data = {
//Specify email data
from: from_who,
//The email to contact
to: req.params.mail,
//Subject and text data  
subject: 'Hello from Mailgun',
html: 'Hello, This is not a plain-text email, I wanted to test some spicy Mailgun sauce in NodeJS! <a href="http://0.0.0.0:3030/validate?&apos; + req.params.mail + &apos;">Click here to add your email address to a mailing list</a>'
}

//Invokes the method to send emails given the above data with the helper library
mailgun.messages().send(data, function (err, body) {
//If there is an error, render the error page
if (err) {
res.render('error', { error : err});
console.log("got an error: ", err);
}
//Else we can greet    and leave
else {
//Here "submitted.jade" is the view file for this landing page 
//We pass the variable "email" from the url parameter in an object rendered by Jade
res.render('submitted', { email : req.params.mail });
console.log(body);
}
});

});

app.get('/validate/:mail', function(req,res) {
var mailgun = new Mailgun({apiKey: api_key, domain: domain});

var members = [
{
address: req.params.mail
}
];
//For the sake of this tutorial you need to create a mailing list on Mailgun.com/cp/lists and put its address below
mailgun.lists('NAME@MAILINGLIST.COM').members().add({ members: members, subscribed: true }, function (err, body) {
console.log(body);
if (err) {
res.send("Error - check console");
}
else {
res.send("Added to mailing list");
}
});

})

app.get('/invoice/:mail', function(req,res){
//Which file to send? I made an empty invoice.txt file in the root directory
//We required the path module here..to find the full path to attach the file!
var path = require("path");
var fp = path.join(__dirname, 'invoice.txt');
//Settings
var mailgun = new Mailgun({apiKey: api_key, domain: domain});

var data = {
from: from_who,
to: req.params.mail,
subject: 'An invoice from your friendly hackers',
text: 'A fake invoice should be attached, it is just an empty text file after all',
attachment: fp
};

//Sending the email with attachment109    mailgun.messages().send(data, function (error, body) {
if (error) {
res.render('error', {error: error});
}
else {
res.send("Attachment is on its way");
console.log("attachment sent", fp);
}
});
})

app.listen(3030);
                                
                            

Enregistrez le code ci-dessous sous index.jade dans le répertoire /views

                                

                                    doctype html
html
head
title Mailgun Transactional demo in NodeJS
body
p Welcome to a Mailgun form
form(id="mgform")
label(for="mail") Email
input(type="text" id="mail" placeholder="Youremail@address.com")
button(value="bulk" onclick="mgform.hid=this.value") Send transactional
button(value="list" onclick="mgform.hid=this.value") Add to list
button(value="inv" onclick="mgform.hid=this.value") Send invoice
script(type="text/javascript" src="main.js")
                                
                            

Enregistrez le code ci-dessous sous error.jade dans le répertoire /views

                                

                                    doctype html
html
head
title Mailgun Transactional
body
p Well that's awkward: #{error}
                                
                            

Enregistrez le code ci-dessous sous main.js dans le répertoire /js

                                

                                    var vForm = document.getElementById('mgform');
var vInput = document.getElementById('mail');

vForm.onsubmit = function() {
if (this.hid == "bulk") {
location = "/submit/" + encodeURIComponent(vInput.value);
}
if (this.hid == "list") {
location = "/validate/" + encodeURIComponent(vInput.value);
}
if (this.hid == "inv") {
location = "/invoice/" + encodeURIComponent(vInput.value);
}

return false;
}
                                
                            

Enfin, créez un fichier invoice.txt vide dans votre dossier racine. Ce fichier sera envoyé en pièce jointe. 

1. Exécutez npm install (ou sudo npm install dans certains cas, selon vos méthodes d’installation) pour télécharger les dépendances, y compris Express. 

2. Une fois cela fait, exécutez node app.js 

3. Naviguez avec votre navigateur vers localhost:3030 (ou 0.0.0.0:3030) 

Ces trois étapes simples vous permettent de commencer à envoyer des emails transactionnels à la demande ! 

Ce qui précède est une application express simple qui s’exécutera sur votre machine locale sur le port 3030. Nous l’avons définie pour utiliser expressjs et le wrapper mailgun-js. Ce sont des bibliothèques assez connues qui nous aideront à configurer rapidement un petit site web qui permettra aux utilisateurs de déclencher l’envoi d’emails vers leur adresse.

Les points de terminaison

Nous avons défini quatre points de terminaison.

1. /
2. /submit/:mail
3. /validate/:mail
4. /invoice/:mail

Où :mail est votre adresse email valide.

Lors de la navigation vers un point de terminaison, Express enverra au navigateur une vue différente.

En arrière-plan, Express prendra les données fournies par le navigateur et les traitera à l’aide de la bibliothèque mailgun-js.

Dans le premier cas, nous naviguerons vers la racine qui est localhost:3030/

Vous pouvez voir qu’il y a une zone de saisie demandant votre adresse email. En faisant cela, vous vous envoyez un bel email transactionnel.

Cela s’explique par le fait qu’expressjs prend votre adresse email du paramètre d’URL et, en utilisant votre clé API et votre domaine, effectue un appel API vers le point de terminaison pour envoyer des emails.

Chaque point de terminaison invoquera une mise en page différente, j’ai ajouté le code des mises en page de base ci-dessous, n’hésitez pas à y ajouter ou à en retirer des éléments.

Dans notre exemple, nous avons vu comment vous pouvez envoyer un email transactionnel automatiquement lors du déclenchement d’une action spécifique. 

Lorsque vous naviguez vers la racine localhost:3030/, vous verrez une zone de saisie demandant votre adresse email. En faisant cela, vous vous envoyez un bel email transactionnel. 

Le point de terminaison /validate/:mail montre comment ajouter une adresse email à une liste de contacts. Pour les besoins de ce tutoriel, vous devez créer une liste de contacts sur Mailgun.com/cp/lists et mettre son adresse dans le code app.js. 

Le point de terminaison /invoice/:mail montre comment envoyer une pièce jointe. Nous avons requis le module path pour trouver le chemin complet afin de joindre le fichier vide invoice.txt dans votre répertoire racine. 

Dans notre exemple, nous avons vu comment vous pouvez envoyer un email transactionnel automatiquement lorsqu’une action spécifique est déclenchée, dans notre cas précis, la soumission du formulaire.

Il y a des milliers d’applications auxquelles vous pourriez adapter ce scénario. L’envoi d’emails peut être utilisé pour :

• L’enregistrement d’un compte sur un site et un email de message Hello 
• Réinitialiser un mot de passe
• Confirmer des achats ou des actions critiques (suppression d’un compte)
• L’authentification à deux facteurs avec plusieurs adresses email

À quelles fins utilisez-vous des emails transactionnels dans votre activité quotidienne ?

Auteur·trice: The Sinch Mailgun team The Sinch Mailgun team shares news, best practices, and strategies to take your products and apps to the next level using email. Subscribe to our newsletter to get all the articles in your inbox!