Como enviar e-mail transacional em um aplicativo NodeJS usando a API do Mailgun

Você não apenas consegue um reengajamento poderoso com base em gatilhos, ações e padrões, mas também pode comunicar informações importantes automaticamente entre a sua plataforma e um cliente.

É muito provável que, trabalhando com desenvolvimento, você precise enviar e-mails transacionais automatizados, se é que ainda não precisou, como:

• E-mails de confirmação
• Lembretes de senha

…e muitos outros tipos de notificações.

Neste tutorial, vamos aprender como enviar e-mails transacionais usando a API do Mailgun e uma biblioteca auxiliar do NodeJS.

• Enviar um único e-mail transacional
• Enviar uma newsletter para uma lista de e-mails
• Adicionar endereços de e-mail a uma lista
• Enviar uma fatura para um único endereço de e-mail

Ao enviar e-mails de um aplicativo Node.js, você pode usar um cliente SMTP direto ou uma API de e-mail. Tradicionalmente, profissionais de desenvolvimento usariam uma biblioteca como o Nodemailer para configurar uma conexão direta a um servidor SMTP. Embora o SMTP ofereça controle, ele traz várias desvantagens, como configuração complexa e entregabilidade ruim. 

A abordagem de API, como a usada pelo Mailgun, simplifica todo o processo. Em vez de gerenciar o protocolo subjacente, você faz uma simples solicitação HTTP. A infraestrutura robusta do Mailgun lida com a comunicação SMTP para você, oferecendo melhor entregabilidade e recursos integrados como análises e validação de e-mail. 

Esta seção guiará você na configuração do seu projeto e na execução do seu aplicativo. 

Vamos supor que você tenha instalado e saiba como operar dentro do ambiente NodeJS. 

A primeira coisa que faremos é gerar um arquivo package.json em um novo diretório (/mailgun_nodetut, no meu caso). Este arquivo contém detalhes como o nome do projeto e as dependências necessárias. 

                                

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

Como você pode ver, usaremos o expressjs para a estrutura do nosso aplicativo web, com o jade como linguagem de modelo e, por fim, uma biblioteca para Node contribuída pela comunidade por bojand. 

Na mesma pasta em que você criou o arquivo package.json, crie duas pastas adicionais: views/ js/ 

Tudo pronto – basta entrar no Mailgun (é gratuito, caso ainda não tenha uma conta), e obter a sua chave de API na primeira página do painel de controle. 

Salve o código abaixo como app.js no diretório raiz do seu aplicativo (onde package.json está localizado) 

                                

                                    //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);
                                
                            

Salve o código abaixo como index.jade no diretório /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")
                                
                            

Salve o código abaixo como error.jade no diretório /views

                                

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

Salve o código abaixo como main.js no diretório /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 fim, crie um arquivo invoice.txt vazio na sua pasta raiz. Este arquivo será enviado como um anexo. 

1. Execute npm install (ou sudo npm install em alguns casos, dependendo dos seus métodos de instalação) para baixar dependências, incluindo o Express. 

2. Concluído isso, execute node app.js 

3. Navegue no seu navegador para localhost:3030 (ou 0.0.0.0:3030) 

Estas três etapas fáceis são o começo para enviar e-mails transacionais sob demanda! 

Este acima é um aplicativo express simples que será executado na sua máquina local na porta 3030. Nós o definimos para usar o expressjs e o wrapper mailgun-js. Estas são bibliotecas muito conhecidas que nos ajudarão a configurar rapidamente um pequeno site que permitirá à base de usuários acionar o envio de e-mails para seus endereços.

Os endpoints

Nós definimos quatro endpoints.

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

Onde :mail é o seu endereço de e-mail válido.

Ao navegar para um endpoint, o Express enviará uma visualização diferente para o navegador.

Em segundo plano, o Express pegará a entrada fornecida pelo navegador e a processará com a ajuda da biblioteca mailgun-js.

No primeiro caso, navegaremos até a raiz, que é localhost:3030/

Você pode ver que há uma caixa de entrada solicitando o seu endereço de e-mail. Ao fazer isso, você enviará um belo e-mail transacional para o seu endereço.

Isso ocorre porque o expressjs pega o seu endereço de e-mail a partir do parâmetro da URL e, usando a sua chave de API e domínio, faz uma chamada de API para o endpoint a fim de enviar e-mails.

Cada endpoint invocará um layout diferente; adicionei o código de layouts básicos abaixo, fique à vontade para adicionar e remover coisas dele.

No nosso exemplo, vimos como você pode enviar um e-mail transacional automaticamente quando o usuário aciona uma ação específica. 

Ao navegar até a raiz localhost:3030/, você verá uma caixa de entrada solicitando o seu endereço de e-mail. Ao fazer isso, você envia para o seu endereço um belo e-mail transacional. 

O endpoint /validate/:mail mostra como adicionar um endereço de e-mail a uma lista de e-mails. Para os fins deste tutorial, você precisa criar uma lista de e-mails em Mailgun.com/cp/lists e colocar o endereço dela no código app.js. 

O endpoint /invoice/:mail mostra como enviar um anexo. Nós importamos o módulo path para encontrar o caminho completo para anexar o arquivo invoice.txt vazio no seu diretório raiz. 

No nosso exemplo, vimos como você pode enviar um e-mail transacional automaticamente quando o usuário aciona uma ação específica, em nosso caso específico, ao enviar o formulário.

Há milhares de aplicativos aos quais você pode adaptar esse cenário. O envio de e-mails pode ser usado para:

• Registrar uma conta em um site e enviar e-mail de mensagem de Olá 
• Redefinir uma senha
• Confirmar compras ou ações críticas (exclusão de uma conta)
• Autenticação de dois fatores com múltiplos endereços de e-mail

Para que você usa e-mails transacionais no seu negócio no dia a dia?

Autor: 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!