Sua aplicação envia dados estruturados para um endpoint HTTP e recebe uma resposta com o resultado da mensagem ou um erro. Essa solicitação e resposta são a superfície de trabalho de uma API de e-mail.
O que uma API de e-mail faz?
Um endpoint de envio aceita destinatários, um assunto e conteúdo em texto ou HTML. Ele também pode aceitar cabeçalhos, tags, templates e anexos quando o provedor os suporta.
Um endpoint de eventos ou webhook relata o que aconteceu após a aceitação. Eventos comuns incluem entrega, rejeição, reclamação, abertura e clique. Uma API de recebimento transforma e-mails recebidos em mensagens estruturadas para sua aplicação, em vez de exigir que você consulte uma caixa de correio.
Qual é a diferença entre uma API de e-mail e SMTP?
SMTP exige que sua aplicação abra uma conexão, autentique, envie comandos e leia códigos de resposta. Uma API de e-mail usa solicitações HTTP, então uma biblioteca cliente pode cuidar da reutilização de conexão, codificação JSON, tentativas de reenvio e análise de respostas.
Escolha uma API quando sua aplicação já usa HTTP, precisa de eventos estruturados ou roda em ambientes onde abrir conexões SMTP é inconveniente. Escolha um relay SMTP quando uma biblioteca de e-mail ou servidor de e-mail existente já fala SMTP. Os dois caminhos podem entregar a mesma mensagem.
| Tarefa | API de envio | Relay SMTP | API de caixa de correio |
|---|---|---|---|
| Enviar uma mensagem | Sim | Sim | Responder ou redigir |
| Receber e-mail processado | Alguns provedores | Não | Sim |
| Ler histórico de conversa | Alguns provedores | Não | Sim |
| Observar entrega | Eventos ou webhooks | Códigos de resposta e eventos | Status da mensagem e eventos |
Produtos usam o termo API de e-mail para conjuntos de funcionalidades diferentes. Verifique o schema do provedor antes de supor que uma única API cobre todas as linhas.
O que uma solicitação de API deve incluir?
Envie os campos que seu provedor exige. Registre o identificador de mensagem retornado. Mantenha sua própria chave de idempotência quando uma nova tentativa não puder criar um envio duplicado. Valide os destinatários antes de enviar. Mantenha segredos no seu servidor.
Um exemplo de solicitação transacional contém from, to, subject, text, category: transactional e uma chave de idempotência mantida no servidor. Use um domínio de envio verificado antes de enviá-la.
A resposta HTTP indica que o serviço aceitou a solicitação. Eventos de entrega, rejeição e reclamação chegam depois, então uma resposta de aceitação não garante a chegada na caixa de entrada.
Use webhooks para eventos posteriores em vez de tratar uma solicitação aceita como prova de que a mensagem chegou à caixa de entrada. Eventos de entrega e reclamação descrevem o que aconteceu após a aceitação.
Como enviar com Bird?
Você chama createEmailMessage API do Bird com sua chave API do espaço de trabalho, remetente, destinatários, conteúdo e metadados opcionais. O guia de envio de e-mail mostra os campos de solicitação e resposta.
Para respostas e e-mails recebidos, crie uma caixa de correio e consuma seus eventos de mensagem e entrega. O guia de caixas de correio cobre esses endpoints e nomes de webhook.
Resumo
- Uma API de e-mail expõe envio e eventos de mensagem via HTTP.
- A resposta confirma a aceitação API, não a chegada na caixa de entrada.
- Chaves de idempotência tornam possível tentar novamente com segurança.
- Bird oferece APIs de envio e de caixa de correio, com guias para cada caminho.