Meu primeiro módulo no NPM

javascript 23 de Jun de 2015

smtp-locaweb-nodejs

Eu nunca tinha feito um módulo para o NPM, mas gosto muito de NodeJS e sempre que posso tento estudar um pouco. Aproveitei o fato de que a API do SMTP Locaweb tinha acabado de ser lançada para estudar, ao mesmo tempo que entrego algo útil para meu empregador. Foi uma experiência bem interessante e não importa o quão simples seja o código, me apaixono mais por JavaScript e NodeJS a cada dia.

Uma boa prática em qualquer sistema, principalmente web, é lidar com o envio de emails de forma assíncrona, uma vez que o disparo síncrono de mensagens pode causar sérios problemas ao bloquear a execução da sua thread enquanto espera a resposta de um servidor, que pode estar (e passar) há muitos nós de distância na Internet. Se o volume de mensagens crescer, você pode ter um grandes problema de performance. A vantagem de usar NodeJS para o disparo de emails transacionais é que o Node é assíncrono por padrão e você não precisa se preocupar com isso, ficando livre para focar apenas no conteúdo e em quando serão enviadas as mensagens aos seus usuários.

Trata-se de uma biblioteca para facilitar o uso da API do email transacional da Locaweb. Com ela fica muito mais fácil utilizar o serviço.

Instalação

O primeiro passo é instalar a biblioteca. Para isso, use o NPM na pasta raiz do seu aplicativo:

npm i smtp-locaweb-nodejs

Em seguida, também na pasta raiz, crie um arquivo .env com seu token de acesso a API, seguindo o modelo abaixo:

TOKEN=yourAccountToken

O token pode ser encontrado dentro do painel do produto em https://smtplw.com.br/panel/settings/api.

Utilização

Após efetuar os passos acima, é hora de fazer importar o módulo em seu código fonte. Para isso, basta utilizar:

var locaweb = require('smtp-locaweb-nodejs');

Daí em diante podemos criar um objeto email utilizando o construtor da biblioteca, definindo os atributos com os métodos na sequência:

var email = new locaweb.Email();
 
email.addTo('destinatario@email.com');
email.addSubject('Um título bem legal!!!');
email.addFrom('remetente@seudominio.com.br');
email.addBody('O conteúdo da mensagem.');
email.addCc('copia_opcional@email.com');
email.addBcc('bcc_opcional@email.com');
email.addHeaders({Conten-type: 'text/plain'});

Para fazer a requisição a API, basta utilizar o método locaweb.sendmail passando o objeto criado anteriormente:

locaweb.sendMail(email);

Outra opção válida é criar um objeto previamente e utilizá-lo como argumento para gerar um novo objeto da classe Email; enviando em seguida, como no exemplo abaixo:

mensagem = {
    to: ['destinatario1@email.com', 'destinatario2@email.com', 'destinatarioN@email.com'],
    subject: 'Um título bem legal!!!',
    from: 'remetente@seudominio.com.br',
    body: 'O conteúdo da mensagem.',
    cc: ['copia_opcional@email.com'],
}

var email = new locaweb.Email(mensagem);
 
locaweb.sendMail(email);

Alguns detalhes que devem ser observados:

  1. O remetente das mensagem deve ter sido validado anteriormente dentro do painel do produto, caso contrário seria possível enviar uma mensagem em nome de qualquer endereço (e não é isso que queremos, certo? :-P).
  2. O destinatário da mensagem pode ser tanto uma "string" quanto um "array" de strings com mais de um endereço.
  3. Apenas os campos to, subject, body e from, são obrigatórios.
  4. O campo headers diz respeito aos headers que serão incluídos no email a ser disparado, não na requisição à API.
  5. As aspas duplas (") em conteúdo HTML devem ser escapadas com uma barra invertida (\). Caso contrário, o JSON enviado poderá ficar inválido.

Resposta

Caso a requisição à API seja bem sucedida, ela retornará um

201 Created
{status: ok}

com o atributo Location no header. O Location trará a URL com o ID da mensagem enviada para que você possa fazer a consulta do status da mesma, de forma a saber se ela foi enviada, obteve "bounce", etc.

Por isso mesmo, o método locaweb.sendMail retorna esse valor, de forma que você pode utilizá-lo da maneira como quiser, salvando em uma variável ou armazenando em seu banco de dados, por exemplo.

Conclusão

Como é possível ver, espero que a biblioteca torne a vida de alguns desenvolvedores mais fácil, tornando a tarefa de enviar emails transacionais algo trivial.

O código fonte é aberto e está disponível no Github sob a licença MIT: https://github.com/locaweb/smtp-locaweb-nodejs

Feedbacks e pull requests são sempre bem vindos! :-)

Para saber mais sobre a plataforma de emails transacionais da Locaweb, consulte a página do produto.

Você também pode consultar a documentação para desenvolvedores no site http://developer.locaweb.com.br/documentacoes/smtp.

Marcadores

Kemel Zaidan

Recomendado para você