Para quem não sabe, e-mails transacionais são mensagens eletrônicas que recebemos quando esquecemos uma senha ou quando o status de uma compra online é alterado.

No ambiente de nuvem, é muito comum utilizarmos um serviço de e-mail transacional, para dispararmos essas mensagens individualmente e não termos que nos preocupar com a administração de um servidor de e-mail. Isso ocorre por dois motivos:

1. Pode ser um custo muito alto, considerando que estamos começando e o volume de mensagens é baixo.
2. Torna-se muito complexo quando o site já cresceu e o volume de mensagens disparadas aumenta.

Dessa forma, você contrata um serviço para disparar e-mails individualmente e paga de acordo com o volume de mensagens que enviar. Outra vantagem de utilizar um serviço de e-mail transacional é a disponibilidade de alguns recursos que não são encontrados em servidores de e-mail padrões. Hoje falaremos de alguns lançados recentemente: webhook e o envio por API.

API

É difícil encontrar um desenvolvedor web hoje que não saiba o que seja uma API. Apesar de o protocolo SMTP ser muito utilizado, de forma que qualquer linguagem de programação possua ao menos uma biblioteca padrão para fazer uso desse protocolo para o envio de e-mails, a partir de agora também é possível efetuar os disparos das mensagens por meio de um webservice RESTfull.

Para isso, o primeiro passo é solicitar a geração do token de autenticação no painel do produto e enviá-lo em cada requisição através do parâmetro x-auth-token no cabeçalho. A API utiliza o formato JSON codificado em UTF-8 para receber e retornar dados através de HTTPS.

Webhooks

No nosso caso, webhooks têm a finalidade de emitir alertas em tempo real sobre erros no envio de mensagens aos usuários. Com ele é possível, portanto, registrar uma URI de callback que vai disparar uma requisição para o endereço cadastrado toda vez que um determinado evento acontecer, e assim fornecer mais informações sobre o evento em questão.

É possível, também, registrar a URI do webhook da nossa aplicação no painel do produto, de forma que o SMTP Locaweb irá disparar uma requisição do tipo POST toda vez que ocorrer um erro no envio de uma mensagem por meio do serviço.

O content-type que virá na requisição será do tipo x-www-form-urlencoded. Os parâmetros serão enviados no corpo da mensagem com o mesmo encode e de forma análoga ao que aconteceria caso você recebesse o resultado do envio de um formulário web nesse mesmo endereço. A estrutura de parâmetros segue a tabela abaixo:

Parâmetro	Descrição
bounce_description=[bounce_description]	Tipo do erro
bounce_code=[bounce_code]	Código do erro
sender=[sender]	Remetente
to=[to]	Destinatário
subject=[subject]	Assunto da mensagem
x-smtplw=[x-smtplw]	Cabeçalho da mensagem

 

Um exemplo de requisição válida seria:

POST http://dominio.com/webhook.php

content-type: application/x-www-form-urlencoded

bounce_description=Desconhecido&bounce_code=5.0.0&sender=remetente%40domain.com&to=destinatario%40domain.com&subject=assunto+qualquer&x-smtplw=valor+qualquer+(opcional)

Dessa maneira, a aplicação tem todas as condições de tratar os dados enviados e iniciar as ações mais pertinentes, de acordo com o que foi recebido. Tudo vai depender do contexto da aplicação que está usando o SMTP Locaweb.

Um exemplo de uso seria exibir dentro do dashboard da aplicação um aviso de que o e-mail cadastrado pelo usuário está retornando um erro, permitindo que ele corrija o endereço errado ou cadastre outro e-mail.

Outro caso seria disparar um aviso para que um time administrativo entre em contato com esse cliente que pode ter cadastrado um e-mail inválido por engano. A criatividade fica por conta dos desenvolvedores e estamos muito ansiosos para ver o que vocês criarão com essa nova funcionalidade. 🙂

Saiba mais

No próximo artigo, daremos mais exemplos de como utilizar esses recursos.

Para ter acesso a documentação completa para desenvolvedores, basta acessar este link.