Após o checkout, sua aplicação tem um pedido e um destinatário que precisa de um recibo. Ela usa uma API de e-mail para enviar a mensagem. Ela registra a resposta vinculada ao pedido.
O envio é apenas o primeiro passo. Sua aplicação também precisa de uma forma de tentar novamente uma solicitação. Ela precisa saber o que aconteceu com a mensagem após o envio.
Como um evento da aplicação se transforma em um e-mail?
Sua aplicação transforma uma transação concluída ou uma solicitação de conta em uma operação de envio. O serviço de e-mail cuida da entrega após o envio.
Para um recibo, a sequência é:
- Sua aplicação confirma que o pedido está pronto para um recibo.
- Ela seleciona o destinatário e fornece os detalhes do pedido como conteúdo ou valores de template.
- Ela envia a solicitação e salva o ID de mensagem retornado vinculado ao pedido.
- Ela atualiza o registro de envio quando os eventos de entrega chegam.
Uma API de e-mail pode suportar tanto mensagens transacionais quanto de marketing. Usar uma API não torna conteúdo promocional transacional nem remove obrigações do CAN-SPAM.
O que significa uma resposta de sucesso?
Uma resposta de sucesso ao envio registra o que o serviço aceitou. Ela é separada da decisão posterior do servidor de e-mail receptor.
O status 202 de HTTP significa que a solicitação foi aceita para processamento. O processamento não terminou, então essa resposta não confirma a entrega.
A resposta exata depende da API. O endpoint de envio de Bird, por exemplo, retorna uma mensagem enfileirada com um id. Guarde esse ID junto ao pedido ou evento de conta para que resultados posteriores possam ser vinculados à solicitação original.
Se a validação falhar, Bird retorna 422 com um erro explicando por que a solicitação foi rejeitada.
Como as novas tentativas evitam mensagens duplicadas?
Uma chave de idempotência identifica uma operação lógica de envio entre novas tentativas. Uma API que a suporte pode reconhecer uma solicitação repetida em vez de criar outro envio.
Por exemplo, um recibo do pedido 8472 pode usar a chave receipt/order-8472. Tente novamente a mesma solicitação com essa chave se a conexão cair antes de você receber a resposta.
Uma chave nova identifica uma operação diferente. Portanto, sua aplicação precisa preservar a chave original entre suas próprias tentativas e reinicializações.
A idempotência tem uma janela de retenção definida pelo provedor. Quando essa janela expira, a mesma chave pode ser processada como uma nova solicitação.
Como os webhooks reportam a entrega?
Um webhook envia um evento para sua aplicação quando o estado da mensagem muda. Ele permite que sua aplicação atualize seus registros após a resposta inicial da API.
Os eventos de e-mail de Bird distinguem estes resultados:
| Evento | O que ele confirma |
|---|---|
email.delivered | O servidor de e-mail receptor aceitou a responsabilidade pela mensagem |
email.deferred | Uma falha temporária de entrega será tentada novamente |
email.bounced | O servidor receptor recusou a entrega |
email.rejected | A mensagem não chegou a uma tentativa de entrega |
A aceitação pelo servidor não confirma a chegada à caixa de entrada nem a leitura. Um servidor receptor também pode reportar um bounce posterior após aceitar a mensagem.
Seu handler de webhook deve verificar a assinatura do remetente e lidar com entregas duplicadas. O contrato de webhook de Bird exige deduplicação usando webhook-id.
O que os templates mudam?
Um template armazenado separa o conteúdo reutilizável da mensagem dos valores fornecidos em cada envio. Sua aplicação pode fornecer um número de pedido e o nome do cliente sem montar o corpo completo do e-mail.
Com os templates de Bird, um envio nomeia um template publicado e fornece seus parâmetros. O template fornece o assunto e o corpo.
Um template não decide quando um pedido está concluído ou se uma redefinição de senha está autorizada. Essas decisões permanecem na sua aplicação.
Qual é a diferença em relação ao relay SMTP ou a uma plataforma de marketing?
Uma API HTTP e um relay SMTP são interfaces de envio diferentes. Uma plataforma de marketing também gerencia o trabalho de campanhas, como selecionar uma audiência e agendar um envio.
| Interface ou produto | O que sua aplicação fornece |
|---|---|
| API de e-mail | Uma solicitação HTTP estruturada contendo destinatários e conteúdo ou um template |
| Relay SMTP | Uma conversa SMTP enviando destinatários e uma mensagem de e-mail formatada |
| Plataforma de marketing | Conteúdo de campanha, seleção de audiência e instruções de envio |
SMTP define a troca para enviar uma mensagem e seus destinatários. Pode transportar e-mail transacional ou de marketing.
O relay SMTP de Bird e HTTP API usam o mesmo produto de entrega, incluindo eventos e tratamento de supressão. Escolher SMTP não remove essas capacidades.
Como você envia e-mail transacional pelo Bird?
Você chama POST /v1/email/messages com um remetente verificado, destinatários e conteúdo inline ou um template publicado. Defina category: "transactional" para e-mail operacional. A resposta é 202 Accepted com um ID de mensagem; a entrega prossegue de forma assíncrona.
Use uma Idempotency-Key para cada envio lógico. Bird mantém uma resposta concluída por três horas. Uma nova tentativa após essa janela pode criar outra mensagem, então mantenha seu próprio registro de eventos de negócio concluídos.
Inscreva-se nos eventos de e-mail e vincule email_id e recipient_id aos seus registros. Uma mensagem com múltiplos destinatários tem resultados separados para cada destinatário.
Para seleção de provedor, o checklist de serviço de e-mail transacional cobre as capacidades de entrega e operacionais a comparar.