Cómo enviar emails transaccionales en una aplicación NodeJS usando la API de Mailgun
No solo puedes conseguir una potente reactivación basada en disparadores, acciones y patrones, sino que también puedes comunicar información importante automáticamente entre tu plataforma y un cliente.
Es muy probable que, como desarrollador/a, alguna vez tengas que enviar emails transaccionales automatizados (si no lo has hecho ya), como:
- Emails de confirmación
- Recordatorios de contraseña
… y muchos otros tipos de notificaciones.
En este tutorial aprenderemos cómo enviar emails transaccionales usando la API de Mailgun y una biblioteca auxiliar de NodeJS.
Cubriremos diferentes escenarios:
- Enviar un único email transaccional
- Enviar una newsletter a una lista de contactos
- Añadir direcciones de email a una lista
- Enviar una factura a una única dirección de email
Enviar emails: SMTP frente a API
A la hora de enviar emails desde una aplicación de Node.js, puedes usar un cliente SMTP directo o una API de email. Tradicionalmente, se solía usar una biblioteca como Nodemailer para configurar una conexión directa a un servidor SMTP. Aunque el protocolo SMTP te da control, tiene varios inconvenientes, como una configuración compleja y una mala entregabilidad.
El uso de una API, como en el caso de Mailgun, simplifica todo el proceso. En lugar de gestionar el protocolo subyacente, puedes realizar una sencilla solicitud HTTP. La sólida infraestructura de Mailgun gestiona la comunicación SMTP por ti para ofrecer una mejor entregabilidad y funcionalidades integradas, como analíticas y validación de emails.
Primeros pasos con tu aplicación de Node.js
Esta sección te guiará para configurar tu proyecto y poner en marcha tu aplicación.
Paso 1: Inicialización del proyecto
Suponemos que has instalado NodeJS y sabes cómo usar su entorno.
Lo primero que haremos será generar un archivo package.json en un directorio nuevo (/mailgun_nodetut, en mi caso). Este archivo contiene detalles como el nombre del proyecto y las dependencias requeridas.
{
"name": "mailgun-node-tutorial",
"version": "0.0.1",
"private": true,
"scripts": {
"start": "node app.js"
},
"dependencies": {
"express": "4",
"jade": "*",
"mailgun-js": "0.5"
}
}
Como puedes ver, usaremos expressjs para la estructura de nuestra aplicación web, jade como lenguaje de plantillas y, por último, una biblioteca para Node aportada por la comunidad de la mano de bojand.
En la misma carpeta donde has creado el archivo package.json, crea otras dos: views/ js/
Todo listo; solo tienes que iniciar sesión en Mailgun (es gratis, por si aún no lo has hecho) y obtén tu clave de API en la primera página del panel de control.
Paso 2: Configurar una aplicación sencilla de ExpressJS
Guarda el siguiente código como app.js en el directorio raíz de tu aplicación (donde se encuentra 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?' + req.params.mail + '">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);
Paso 3: Crear la vista y los archivos de JavaScript:
Guarda el siguiente código como index.jade en el directorio /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")
Guarda el siguiente código como error.jade en el directorio /views
doctype html
html
head
title Mailgun Transactional
body
p Well that's awkward: #{error}
Guarda el siguiente código como main.js en el directorio /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;
}
Por último, crea un archivo invoice.txt vacío en la carpeta raíz. Este archivo se enviará como adjunto.
Paso 4: Ejecutar la aplicación
- Ejecuta
npm install(osudo npm installen algunos casos, según tus métodos de instalación) para descargar las dependencias, incluida Express.
- Una vez hecho esto, ejecuta
node app.js
- Ve en el navegador a
localhost:3030(o0.0.0.0:3030)
¡Con estos tres sencillos pasos podrás empezar a enviar emails transaccionales bajo demanda!
Entender cómo funciona la aplicación
Lo anterior es una aplicación sencilla de Express que se ejecutará en tu equipo local en el puerto 3030. La hemos definido para usar expressjs y el wrapper mailgun-js. Se trata de bibliotecas bastante conocidas que nos ayudarán a configurar rápidamente un pequeño sitio web que permitirá a los usuarios desencadenar el envío de emails a sus direcciones.
Los puntos de conexión
Hemos definido 4 puntos de conexión.
//submit/:mail/validate/:mail/invoice/:mail
Donde :mail es tu dirección de email válida.
Al navegar a un punto de conexión, Express enviará al navegador una vista diferente.
En segundo plano, Express tomará la entrada proporcionada por el navegador y la procesará con ayuda de la biblioteca mailgun-js.
En el primer caso, navegaremos a la raíz, que es localhost:3030/
Puedes ver que hay un cuadro de entrada donde se te pide tu dirección de email. Al hacerlo, te envías un buen email transaccional.
Esto se debe a que expressjs toma tu dirección de email del parámetro de la URL y, al usar tu clave de API y tu dominio, hace una llamada a la API al punto de conexión para enviar emails.
Cada punto de conexión invocará un diseño distinto. He añadido el código de los diseños básicos a continuación; siéntete libre de añadir o quitar elementos.
Ejemplos prácticos: enviar emails con la API de Node.js de Mailgun
En nuestro ejemplo hemos visto cómo se puede enviar un email transaccional automáticamente cuando el usuario desencadena una acción específica.
Enviar un único email transaccional
Al navegar a la raíz localhost:3030/, verás un cuadro de entrada donde se te pide tu dirección de email. Al hacerlo, te envías un buen email transaccional.
Añadir direcciones de email a una lista
El punto de conexión /validate/:mail muestra cómo añadir una dirección de email a una lista de contactos. Para este tutorial, necesitas crear una lista de contactos en Mailgun.com/cp/lists y poner su dirección en el código de app.js.
Enviar una factura con un adjunto
El punto de conexión /invoice/:mail muestra cómo enviar un adjunto. Hemos requerido el módulo path para encontrar la ruta completa y adjuntar el archivo vacío invoice.txt en tu directorio raíz.
Dar los últimos toques a tu remitente de emails en Node.js
En nuestro ejemplo hemos visto cómo se puede enviar un email transaccional de forma automática cuando el usuario desencadena una acción específica (en nuestro caso, enviar el formulario).
Hay miles de aplicaciones a las que podrías adaptar este escenario. El envío de emails puede usarse para:
- Registrar una cuenta en un sitio web y un email con el mensaje Hola
- Restablecer una contraseña
- Confirmar compras o acciones críticas (eliminar una cuenta)
- Autenticación en dos fases con múltiples direcciones de email
¿Para qué usas los emails transaccionales en el día a día de tu negocio?
