Como usar HTTP API para enviar e-mails

Envie e rastreie e-mails sem a necessidade de codificação adicional.

April 20 2017

As tecnologias de comunicação evoluíram a um ponto, no qual não é mais suficiente usar um ou dois canais. O fato é: cada canal tem suas vantagens e desvantagens. Você pode usar push para atingir e contatar usuários numa localização específica. Já o SMS, possui maior taxa de leitura. O Viber é interativo e divertido. E os e-mails respeitam o horário do cliente.

De qualquer forma, o ecossistema que temos hoje, ou seja, centrado no consumidor, demanda a adaptação de suas estratégias de comunicação às necessidades do cliente. A maioria deles tem um canal de preferência. Já usa Gmail, Facebook Messenger ou Viber Outlook e uma série de outros aplicativos. Mas principal ponto é que eles usam cada um desses canais para um propósito específico.

Por exemplo, alguns podem usar o Messenger para conversar em tempo real e, ao mesmo tempo, receber newsletters de suas marcas favoritas pelo Gmail. Outros podem preferir ser contatados via SMS, já que esse ainda é o canal de comunicação mais confiável que existe. Alguns podem optar por receber ligações em caso de alertas importantes.

Por que e-mail?

Devido à sua natureza única, o e-mail é parte essencial das comunicações omnichannel. Ele é um dos canais com melhor custo benefício e menos invasivos que existe. É por isso, que é a escolha mais frequente dos usuários para se relacionar com uma marca. Nós mencionamos newsletters, mas há uma série de casos, nos quais o e-mail funciona. Desde e-mails para verificação de conta até reconfiguração de senha e recuperação de contas.

É por isso que os e-mails geram bilhões e bilhões de mensagens por dia. De acordo com a Ericsson, até 2020, 70% da população mundial estarão usando smartphones e 90% estarão cobertas por redes de celular de banda larga. Também é importante ressaltar que mais de 50% dos e-mails são abertos em dispositivos móveis ao invés do desktop e esses números continuam aumentando. Isso significa que os usuários serão capazes de acessar suas contas de e-mail a qualquer hora.

Nossa HTTP API garante o envio de e-mails de forma simples e repleta de recursos. Você poderá enviar e-mails HTML com anexos e checar relatórios de entrega e o histórico de e-mails. Mas, antes de começar a enviar e-mails, você precisa obter uma conta válida da Infobip..

Como criar uma conta?

Se você já usa nossos outros serviços API, você já possui uma conta válida da Infobip e pode usar a mesma para enviar e-mails.

Pense antecipadamente sobre seu domínio, pois o nome do remetente do e-mail está ligado ao nome de domínio, assim como o endereço IP. Isso só se torna um problema quando você se torna um “mau” remetente, pois isso pode afetar muito o seu domínio. Ao se tornar um mau remetente, você terá dificuldades de reconquistar a confiança do cliente. Por isso, considere separar domínios, de acordo com o tipo de mensagens que você quer enviar.

Se não tiver certeza a princípio sobre seu plano de domínio, não se preocupe. Você pode usar o nosso domínio teste para testar o serviço e usar o seu próprio domínio depois. Assim que escolher seu domínio preferido, fale com seu gerente de contas, para que possamos integra-lo à nossa plataforma. Depois que receber as instruções adicionais sobre a configuração DNS e como estabelecer um canal de comunicação apropriado entre o seu domínio e a sua plataforma, você poderá seguir os próximos passos e enviar um e-mail com sucesso.

Em caso de dúvidas, entre em contato pelo e-mail: support@infobip.com.

Enviando um email

Após configurar a conta, você está pronto para enviar e-mails. Você pode enviar uma simples mensagem de e-mail ou um e-mail repleto de recursos. Se decidir enviar um e-mail simples, você enviará um único e-mail para apenas um destinatário com uma solicitação:


curl -s --user user:password \
https://api.infobip.com/email/1/send \
-F from='company@somecompany.com' \
-F to='john.smith@somedomain.com' \
-F subject='Mail subject text' \
-F text='Mail body text'

Mas você também pode enviar um e-mail cheio de recursos com uma mensagem com anexo(s), que pode ser enviada para um ou mais destinatários:

curl -s --user user:password \
https://api.infobip.com/email/1/send \
-F from='Jane Smith ' \
-F to='john.smith@somedomain.com' \
-F to='tom.smith@somedomain.com' \
-F subject='Mail subject text' \
-F text='Mail body text' \
--form-string html='<h1>Html body</h1><p>Rich HTML message body.</p>' \
-F attachment=@files/image1.jpg

With a response:

{
 "messages": [
   {
     "to": "john.smith@somecompany.com",
     "messageCount": 1,
     "messageId": "9129e972-be85-49ed-b0e9-f51fbd2b27c0",
     "status": {
       "groupId": 1,
       "groupName": "PENDING",
       "id": 7,
       "name": "PENDING_ENROUTE",
       "description": "Message sent to next instance"
     }
   },
   {
     "to": "tom.smith@somecompany.com",
     "messageCount": 1,
     "messageId": "cd0c5682-42e2-481a-be95-15ed72450646",
     "status": {
       "groupId": 1,
       "groupName": "PENDING",
       "id": 7,
       "name": "PENDING_ENROUTE",
       "description": "Message sent to next instance"
     }
   }
 ]
}

Esse é um exemplo de e-mail com anexo, enviado para dois e-mails destinatários. Se você quiser enviar um e-mail com mais de um anexo, basta adicionar parâmetros de anexos múltiplos na solicitação.

O cabeçalho de resposta com o código de status HTTP para cada solicitação bem-sucedida será 200 OK e, caso tente enviar uma mensagem sem autorização, você receberá erro 401 Não Autorizado.

Relatórios e histórico de entrega de e-mails

Relatórios de entrega de e-mails

Após enviar um e-mail, você pode obter um relatório único de entrega. Os relatórios de entrega confirmam que o e-mail enviado foi entregue com sucesso. Mas só podem ser extraídos uma vez, ou seja, uma vez que você extraia um relatório de entrega, o mesmo relatório não pode ser extraído novamente.

Você pode usar parâmetros para receber relatórios de entrega, mas também pode solicitar sem nenhum parâmetro:


GET /email/1/reports HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

Resultado:

{
 "results": [
   {
     "messageId": "bbcc6960-1fcb-497c-b7ea-83ccba41492e",
     "to": "recipient@infobip.com",
     "sentAt": "2016-08-31T13:25:18.477+0000",
     "doneAt": "2016-08-31T13:25:50.893+0000",
     "messageCount": 1,
     "price": {
       "pricePerMessage": 0,
       "currency": "UNKNOWN"
     },
     "status": {
       "groupId": 3,
       "groupName": "DELIVERED",
       "id": 5,
       "name": "DELIVERED_TO_HANDSET",
       "description": "Message delivered to handset"
     },
     "error": {
       "groupId": 0,
       "groupName": "OK",
       "id": 0,
       "name": "NO_ERROR",
       "description": "No Error",
       "permanent": false
     },
     "channel": "EMAIL"
   }
 ]
}

Um relatório de entrega sem nenhum parâmetro te dará informações detalhadas sobre os e-mails enviados, incluindo status do e-mail, ID da mensagem, horário e dia de envio/recebimento de e-mails, dados sobre erros ocorridos etc.

Além disso, você pode obter relatórios de entrega usando o ID da mensagem:

GET /email/1/reports?messageId=bbcc6960-1fcb-497c-b7ea-83ccba41492e HTTP/1.1

Outra possibilidade é iniciar dois relatórios de entrega:

GET /email/1/reports?limit=2 HTTP/1.1

Ambas as solicitações fornecem detalhes sobre as mensagens, como uma consulta sem parâmetros, mas a diferença é que as solicitações com ID da mensagem extraem informações sobre uma mensagem específica e as com dois relatórios de entrega geram informações sobre as duas primeiras mensagens.

Logs de e-mail

Assim como os relatórios de entrega, os logs de e-mail podem fornecer informações adicionais sobre as mensagens enviadas. A principal diferença é que os logs estão disponíveis nas últimas 48 horas, podendo ser solicitados quantas vezes quiser e você pode ver o resultado das mensagens independentemente do seu status atual.

Resultado:

{
 "results": [
   {
     "messageId": "64c98929-f160-4e2c-b156-ca88cc733547",
     "to": "recipient@infobip.com",
     "from": "sender@infobip.com",
     "text": "Test text",
     "sentAt": "2016-09-01T10:29:00.440+0000",
     "doneAt": "2016-09-01T10:29:01.130+0000",
     "price": {
       "pricePerMessage": 0.0005,
       "currency": "EUR"
     },
     "status": {
       "groupId": 3,
       "groupName": "DELIVERED",
       "id": 5,
       "name": "DELIVERED_TO_HANDSET",
       "description": "Message delivered to handset"
     },
     "channel": "EMAIL"
   }
 ]
}

A resposta contém informação sobre todos os e-mails que foram enviados através da plataforma da Infobip nas últimas 48 horas. Nenhum dos campos de consulta é obrigatório para esse tipo de solicitação, mas se precisar encontrar uma mensagem específica, você pode usar os parâmetros para filtrar.

Por exemplo, os logs podem ser extraídos para somente um ou, neste caso, múltiplos IDs de mensagem:

GET /email/1/logs?messageId=64c98929-f160-4e2c-b156-ca88cc733547,60d586a1-6448-4c5f-860d-be3ddbea16da HTTP/1.1

Além disso, combinar parâmetros vai te ajudar a filtrar as mensagens de forma mais precisa:


GET /email/1/logs?sentSince=2016-08-22T17:42:05.390%2b01:00&generalStatus=DELIVERED HTTP/1.1

Essa solicitação tem dois filtros (parâmetros) – sentSince e generalStatus, que poderiam ser identificados como um único parâmetro e a resposta conteria o histórico da mensagem com todos os e-mails enviados e entregues desde a data inserida na solicitação.

O código de status seria o mesmo para as mensagens enviadas; o cabeçalho da resposta com o código de status HTTP seria 200 OK se fosse bem-sucedida e o histórico de mensagens ou relatórios de entrega seriam retornados. Mas se tentasse enviar a mensagem sem autorização, você receberia uma resresposta com código de status HTTP 401 Não Autorizado.

Esse post deve ajudar com a integração de HTTP API. Mas se houver necessidade de alguma ajuda adicional, visite nosso site para desenvolvedores.

Comece a enviar e-mails agora mesmo

Saiba mais