Como enviar emails em Node.js usando o AWS SES (Amazon)

Em outras oportunidades aqui no blog eu já ensinei a enviar emails em Node.js, mas sempre utilizando soluções para pequena escala como Nodemailer, por exemplo. Não que não dê para acoplar o Nodemailer a um bom SMTP Gateway como Sendgrid ou o AWS SES (Simple Email Service) da Amazon para torná-lo profissional, mas a grande questão é que SMTP em si não escala muito bem, é um protocolo bem datado e que, infelizmente, ainda impera para envio de mensagens eletrônicas.

Os próprios fornecedores de SMTP Gateway, como Sendgrid e AWS novamente, sugerem a utilização de suas APIs públicas ao invés de suas configurações SMTP, por serem mais confiáveis. Claro que no fim das contas eles enviarão por SMTP também, mas cuidarão de uma série de preocupações pra gente, principalmente no tocante a confiabilidade de entrega e escala de envio.

Então no tutorial de hoje, eu gostaria de lhe ensinar como usar o serviço da Amazon para envio de emails, o AWS Simple Email Service, ou SES.

Atenção: este é um tutorial intermediário. Se você não tem familiaridade com Node.js dê uma olhada em meus livros e/ou meus cursos.

#1 – Antes de Tudo

O primeiro passo obviamente é você ter uma conta na AWS, se autenticar no seu painel e ir na área de credenciais de segurança, que ficam dentro da sua conta de usuário (o menu com o seu nome no topo).

Uma vez dentro da área de credenciais de segurança, crie chaves de acesso (caso ainda não possua), lembrando que você pode ter até duas chaves apenas e que a Amazon não fornece backup, então guarde-as em um lugar seguro.

As chaves são compostas de um Access Key e de um Access Secret, sendo este último o mais “sensível” e que não deve ser compartilhado com ninguém. Usaremos estas informações mais tarde.

Um dos serviços da Amazon que vamos usar com essas chaves, o SES, permite que a gente envie mensagens de email de maneira profissional e com alta entregabilidade (deliverability), desde que configurado corretamente e sem abusar.

Uma das vantagens de utilizar o SES ao invés de outros serviços de envio é que se você estiver enviando a partir de um servidor EC2 (os VPS da Amazon) existe uma cota mensal gratuita de envios. Além é claro da vantagem mais óbvia de estarmos utilizando uma solução de ponta para envios.

E uma das desvantagens de usar o SES são algumas de suas limitações de uso. Por exemplo, você não pode enviar uma única mensagem para mais de 50 destinatários de uma única vez. Se precisar fazer isso, terá de mandar vários lotes de 50 ou uma a uma. Outra desvantagem é que você não pode ter mais de 10.000 domínios de email registrados na sua conta por região da AWS.

Ou seja, se sua plataforma de email possuir mais de 10 mil domínios ativos, você terá que balancear eles em mais de uma região da AWS. Note que isso não é a mesma coisa que 10.000 contatos na sua lista de emails, mas sim, 10.000 emails diferentes que ENVIAM mensagens pela sua conta na AWS.

Para saber mais sobre as limitações do AWS SES, visite esta página.

Outra questão importante que você saiba é que quando recém cria uma conta na AWS e vai utilizar o SES pela primeira vez, você estará no modo Sandbox, para testes apenas, o que vai te trazer muitas outras limitações. Para sair do modo sandbox, leia este artigo oficial com orientações.

Mas antes de sair usando o SES precisamos configurá-lo. Acesse o console de administração da sua conta e no menu Serviços procure por SES para acessar a área dele.

Poderíamos fazer todas as configurações aqui, manualmente e é o que recomendo que você faça se estiver precisando do SES para enviar emails de apenas alguns domínios diferentes.

Agora se estiver assim como eu, desenvolvendo uma plataforma de email marketing, onde cada cliente terá seu próprio domínio, você vai querer que esta configuração seja automatizada. Então precisaremos fazer este setup inicial todo via código.

Apesar disso, é importante frisar que enviar emails em nome do domínio de outra pessoa vai exigir uma série de configurações adicionais que não podem ser automatizadas e que servem para validar a identidade/autorização do sender, geralmente feita através de registros de DNS na zona do domínio de envio.

Ou seja, para que você possa enviar emails através do domínio @exemplo.com.br por exemplo, você precisa ter acesso à zona de DNS deste domínio, para informar lá algumas configurações que o AWS SES exige. Na verdade qualquer SMTP Gateway sério vai te exigir isso, tanto por uma questão de segurança quanto por uma questão de entregabilidade. Servidores de email moderno marcam como spam mensagens que não tenham sido enviadas por um domínio sem validação de DNS.

#2 – Setup do AWS SES

Se você for utilizar apenas um domínio para envio, tudo que você precisa fazer é acessar o AWS SES na sua conta da AWS e clicar na opção de “Verify a new Domain”, como mostra a imagem abaixo.

Pule para a seção seguinte se este for o seu caso.

Agora, se você quiser automatizar esta atividade, como eu, que estou construindo uma ferramenta de email marketing onde cada cliente terá seu próprio domínio de email, vamos precisar criar um script de setup de domínio. Para isso, crie um projeto Node.js e instale as seguintes dependências nele.


npm i aws-sdk dotenv

npm i aws-sdk dotenv

O AWS SDK é um pacote NPM que contém classes e funções para uso de todos os serviços da AWS, inclusive o SES, o que facilitará muito a construção da nossa prova de conceito.

Já o dotenv é um velho conhecido do pessoal de Node e serve para gerenciar mais facilmente variáveis de ambiente. Como o AWS SDK exige uma série de configurações para funcionar, vamos armazenar todas elas em um arquivo .env na raiz do projeto com o seguinte conteúdo.


AWS_ACCESS_KEY_ID=<SEU ACCESS KEY AQUI>
AWS_SECRET_ACCESS_KEY=<SEU KEY SECRET AQUI>
AWS_REGION=<SUA REGIÃO AQUI>

AWS_ACCESS_KEY_ID=<SEU ACCESS KEY AQUI>

AWS_SECRET_ACCESS_KEY=<SEU KEY SECRET AQUI>

AWS_REGION=<SUA REGIÃO AQUI>

As configurações são bem diretas, mas só para reforçar:

o AWS_ACCESS_KEY_ID é a o seu key ID, gerado na parte de security credentials da sua conta da AWS. Se não fez esse passo, volte à seção #1 deste tutorial.
o AWS_SECRET_ACCESS_KEY é o secret do seu key ID.
o AWS_REGION é a região que está utilizando os demais serviços da AWS, a minha, por exemplo, é “us-east-1” (sigla para o datacenter do Norte da Virgínia). Esta informação é bem simples de obter, basta ver no canto superior direito o datacenter que está selecionado.

Neste projeto que você criou, crie um arquivo sesClient.js que conterá as funções para utilização do SES, como abaixo (explico na sequência) onde criei uma função para criação de novo domínio.


require("dotenv").config();
const AWS = require("aws-sdk");
AWS.config.update({ region: process.env.AWS_REGION });

//para criar um novo domínio de email na AWS, use a função abaixo
async function addEmailIdentity(domain) {
    const ses = new AWS.SESV2();
    const params = { EmailIdentity: domain };
    const response = await ses.createEmailIdentity(params).promise();
    console.log(response);
}

require("dotenv").config();

const AWS = require("aws-sdk");

AWS.config.update({ region: process.env.AWS_REGION });

//para criar um novo domínio de email na AWS, use a função abaixo

async function addEmailIdentity(domain) {

const ses = new AWS.SESV2();

const params = { EmailIdentity: domain };

const response = await ses.createEmailIdentity(params).promise();

console.log(response);

}

Aqui, começamos importando as configurações do dotenv e o pacote da AWS. Com este último, realizamos uma rápida configuração definindo a região que vamos estar manipulando.

Com uma variável ses instanciada a partir de uma classe presente no AWS-SDK (SESV2), nós criamos um objeto com as configurações da chamada que vamos fazer (bem simples, apenas o domínio que quero cadastrar na minha conta) e chamamos a função createEmailIdentity do objeto ses para cadastrar o domínio na nossa conta da AWS.

O retorno desta chamada estou convertendo para Promise usando uma função da própria biblioteca da AWS, a fim de podermos utilizar Async/Await como fiz no exemplo. Para esta finalidade, também precisei definir que esta função é async.

Para rodar, chame esta função em algum arquivo JS seu, mas atenção: guarde o objeto que ele vai retornar em algum lugar, algo parecido com a imagem abaixo.

Aquela configuração DkimAttributes é necessária para que este domínio que cadastramos na nossa conta seja devidamente validado, como explicarei a seguir. Simplesmente não é possível automatizar toda a configuração e validação de domínios, a menos que seu DNS também esteja dentro da AWS e você seja administrador dos DNS dos domínios que for utilizar para enviar emails.

Se você olhar agora no console da Amazon, na área de domínios da sua conta, verá que o domínio que cadastrou está aparecendo lá, mas com o status de não verificado.

#3 – Validando o domínio

Você não poderá enviar emails em nome deste domínio usando o AWS SES antes de reinvindicar a propriedade deste domínio. Estas configurações envolvem adicionar registros de DNS e deve ser feita manualmente, a menos que a zona esteja na AWS (Route53) e sob sua administração, aí sim poderia ser feito de maneira automatizada, mas isso foge ao escopo deste tutorial.

O primeiro passo é usarmos as chaves DKIM (Domain Keys Identified Email) que foram geradas pela AWS quando cadastramos o nosso domínio no passo anterior.

DKIM é um padrão muito utilizado para validar remetentes/senders idôneos e diminuir a incidência de spam, hoaxes e Email Spoofing, um ataque bem popular de envio de emails em nome de outras pessoas. Basicamente ele te obriga a incluir algumas chaves na zona de DNS do domínio que vai utilizar para enviar emails, assim, quando um servidor de email recebe uma mensagem sua, ele bate no seu DNS para verificar se foi você que realmente mandou ela.

O que você deve saber agora é que, as chaves DKIM retornadas pela execução do setup.js devem ser adicionadas na sua zona de DNS como registros CNAME, usando a seguinte estrutura.

Tipo de registro: CNAME
Nome do registro: <CHAVE_DKIM>._domainkey.<DOMINIO>
Valor do registro: <CHAVE_DKIM>.dkim.amazonses.com

Na data que escrevo este artigo, a Amazon exige o cadastro de 3 chaves DKIM, então repita o processo acima para cada uma das chaves.

Se você não salvou o resultado do setup.js, você pode obter novamente estas chaves no seu painel de administração do domínio, dentro da área do AWS SES, ou através do AWS-SDK também, existem funções específicas para retornar informações, como a que criei abaixo.


//para retornar novamente as informações de DKIM de um domínio, use a função abaixo
async function getEmailIdentity(domain) {
    const ses = new AWS.SESV2();
    const params = { EmailIdentity: domain };
    const response = await ses.getEmailIdentity(params).promise();
    console.log(response);
}

//para retornar novamente as informações de DKIM de um domínio, use a função abaixo

async function getEmailIdentity(domain) {

const ses = new AWS.SESV2();

const params = { EmailIdentity: domain };

const response = await ses.getEmailIdentity(params).promise();

console.log(response);

}

Além do DKIM, o AWS SES exige algumas configurações adicionais para provar que você é o dono deste domínio, novamente envolvendo DNS. Você terá de adicionar mais um registro na sua zona de DNS usando a seguinte estrutura.

Tipo de registro: TXT
Nome do registro: _amazonses.<DOMINIO>
Valor do registro: <CHAVE GERADA PELA AWS>

Note no entanto que o valor deste registro DNS é uma chave, que pode ser obtida pelo próprio painel da AWS como abaixo.

Caso queira obter esta chave de maneira automatizada, a função a seguir faz isso.


async function getIdentityVerificationAttributes(domain){
    const ses = new AWS.SES();
        const params = { Identities: [domain] };
        const response = await ses.getIdentityVerificationAttributes(params).promise();
        console.log(response);
}

async function getIdentityVerificationAttributes(domain){

const ses = new AWS.SES();

const params = { Identities: [domain] };

const response = await ses.getIdentityVerificationAttributes(params).promise();

console.log(response);

}

Note que esta função usa a classe AWS.SES ao invés de AWS.SESV2. De fato esta função getIdentityVerificationAttributes não existe na V2 da API. O retorno desta chamada, passando um domínio já cadastrado na sua conta, pode ser vista abaixo.

Repare no campo VerificationToken, é ele que você precisa adicionar como valor do registro TXT no DNS.

Vale apontar aqui que, se você não está habituado com configurações de DNS, elas podem demorar de segundos até 72h para passar a surtirem efeito, dependendo da abrangência do seu provedor de DNS.

Com estas configurações realizadas, você está quase apto a enviar emails usando o AWS SES, mas como este tutorial já está bem longo, leia a segunda parte aqui!

Quer aprender a fazer isso tudo em um projeto real de plataforma de email marketing, desenvolvendo não apenas o backend mas também o front-end? Clique no banner abaixo!