Eventos de e-mail

Emitimos eventos à medida que cada destinatário avança pela entrega. Um envio para três endereços produz três fluxos independentes, correlacionados por email_id e recipient_id. Esta página define os tipos de evento de e-mail. Consulte Webhooks para assinaturas, tentativas, ordenação e replay.

Todo destinatário começa em email.accepted, depois email.processed. Um destinatário de broadcast é sua própria mensagem, então recebe seu próprio email.accepted também, embora apenas nos eventos API e no log de e-mail, não como webhook. A partir daí a mensagem é aceita pelo servidor receptor (email.delivered), é adiada e retentada (email.deferred, que se resolve como entregue ou devolvida), é recusada pelo servidor receptor (email.bounced), ou nunca recebe uma tentativa de entrega (email.rejected). Após uma entrega, o fluxo pode continuar com email.out_of_band_bounce, email.complained, email.opened, email.clicked, email.unsubscribed e email.list_unsubscribed.

Cada destinatário termina em exatamente um status terminal, delivered, bounced, complained ou rejected, retornado como o status por destinatário de GET /v1/email/messages/{message_id}/recipients. Eventos de engajamento nunca o alteram: um destinatário que abriu ainda é delivered. Um relatório de bounce tardio altera, porque o servidor receptor está retratando uma aceitação que já havia dado, então o destinatário passa de delivered para bounced. A mensagem como um todo tem seu próprio status consolidado e contagens por estado em GET /v1/email/messages/{message_id}.

Os eventos chegam como o envelope de três campos que todo webhook usa: type, timestamp (quando o evento ocorreu, RFC 3339) e um objeto data específico do tipo.

{
  "type": "email.delivered",
  "timestamp": "2026-07-23T14:51:47.107Z",
  "data": {
    "email_id": "em_01ky7qc398fmxraqtxn604zeq9",
    "recipient_id": "er_01ky7qc398fmwsc96nt6anrbqs",
    "workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf",
    "recipient": "delivered@messagebird.dev",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null
  }
}

Todo evento de saída inclui email_id, recipient_id, workspace_id, o endereço recipient e seu recipient_role de envelope (to, cc ou bcc). Ele também repete tags e metadata da solicitação de envio para que você possa correlacionar o evento com seus registros. Cada valor opcional é null quando o envio não tinha nenhum, incluindo broadcast_id: ele nomeia o broadcast do qual um envio fez parte, para que você possa agrupar os eventos de um broadcast sem consultar cada envio, e é null em um envio sem broadcast por trás. Um caso reporta null para um envio que tinha broadcast: um link de cancelamento de inscrição de e-mail enviado antes de adicionarmos o campo não nomeia nenhum broadcast, então um opt-out por esse link reporta null em email.unsubscribed e email.list_unsubscribed independentemente de um broadcast ter enviado o e-mail. Trate null nesses dois eventos como inconclusivo, ou você subcontará os opt-outs de um broadcast. broadcast_id chega a você apenas no webhook: os eventos API abaixo retornam cada evento sem ele. Os tipos de evento adicionam campos descritos nas seções de ciclo de vida, engajamento, supressão e entrada.

Os mesmos eventos podem ser consultados posteriormente em GET /v1/email/messages/{message_id}/events, onde cada um também tem um id (prefixo ev_) e um occurred_at. Use-o para preencher lacunas, fazer replay ou reconciliar com o que seu endpoint recebeu. Alguns campos chegam a você apenas por esse API, não pelo webhook; a descrição do evento relevante identifica cada um.

Aceitamos o envio e começamos a preparar a entrega. Dispara uma vez por destinatário solicitado e é o primeiro evento nesse fluxo. Um destinatário de broadcast também recebe um, porque cada destinatário é sua própria mensagem, mas ele é registrado em vez de entregue: leia-o nos eventos API ou no log de e-mail, não no seu endpoint de webhook. Payload: apenas a base de identidade.

A mensagem foi construída e enfileirada para entrega ao servidor de e-mail do destinatário. Payload: apenas a base de identidade pelo webhook; os eventos API adicionam mailbox_provider e mailbox_provider_region, a classificação do sistema de e-mail receptor (por exemplo gmail, NA), presente quando pôde ser determinada e null caso contrário. Comparar o timestamp deste evento com o de email.accepted fornece o tempo de processamento em um envio individual. Um broadcast não tem esse intervalo: sua aceitação e seu processamento carregam o mesmo instante de despacho, então os dois timestamps coincidem em vez de delimitar qualquer processamento, e a aceitação chega a você apenas pelos eventos API, como occurred_at.

O servidor de e-mail receptor aceitou a mensagem e assumiu a responsabilidade por ela. Este evento não confirma posicionamento na caixa de entrada nem leitura. Inbox Insights fornece estimativas amostradas de posicionamento; eventos de abertura e clique registram solicitações de rastreamento. Payload: apenas a base de identidade pelo webhook; os eventos API adicionam sending_ip, o endereço de origem da mensagem, o que importa quando um problema de entregabilidade está ligado a um IP, além de mailbox_provider e mailbox_provider_region.

Uma falha temporária: o servidor receptor pediu para tentarmos novamente mais tarde (caixa de correio cheia, greylisting, limitação de requisições). Tentamos novamente automaticamente, e o destinatário eventualmente se resolve como email.delivered ou email.bounced, então este evento é informativo e não terminal, e um destinatário pode ser adiado várias vezes antes. Payload: bounce_type, bounce_class, defer_reason (o motivo que o servidor informou) e sending_ip pelo webhook; os eventos API adicionam mailbox_provider e mailbox_provider_region.

Uma falha permanente no momento de SMTP: o servidor receptor recusou a mensagem e o status terminal do destinatário passa a ser bounced. Payload: bounce_type (veja a tabela de classificação), bounce_class, bounce_code (o código de resposta SMTP, por exemplo 550), bounce_description (o motivo que o servidor informou) e sending_ip pelo webhook; os eventos API adicionam mailbox_provider e mailbox_provider_region. Um hard bounce suprime o endereço.

Um bounce tardio: o servidor receptor aceitou a mensagem no momento de SMTP e depois enviou um relatório de bounce. Ele tem a mesma classificação de email.bounced (bounce_type, bounce_class, bounce_code, bounce_description, sending_ip pelo webhook; mailbox_provider e mailbox_provider_region dos eventos API). Quando o relatório é classificado como bounce (qualquer classe na tabela), o servidor retratou sua aceitação anterior, então o destinatário passa de delivered para bounced. Relatórios cuja classe não está na tabela, como respostas automáticas, são registrados na linha do tempo e não alteram o status. Um hard out-of-band bounce também suprime o endereço.

O destinatário nunca chegou ao servidor de e-mail remoto, então nenhuma tentativa de entrega foi feita. É isso que diferencia uma rejeição de um bounce, onde o servidor receptor é quem diz não. Payload: rejection_reason, também no registro do destinatário, um dos seguintes:

Os eventos API também adicionam mailbox_provider e mailbox_provider_region quando o sistema de e-mail receptor pôde ser classificado antes da rejeição.

O destinatário marcou a mensagem como spam e o provedor de caixa de correio reportou isso por meio do seu feedback loop. Reclamações chegam após a entrega e definem o status terminal como complained. Payload: feedback_type, o tipo de relatório que o provedor enviou, como abuse ou fraud, e null quando o provedor não informou, além de mailbox_provider e mailbox_provider_region dos eventos API. Uma reclamação suprime o endereço para e-mail de marketing. Mantenha sua taxa de reclamação baixa: provedores limitam remetentes que acumulam relatórios.

O pixel de rastreamento no corpo da mensagem foi carregado. Payload: ip_address e user_agent quando conhecidos; os eventos API adicionam is_prefetched, country (ISO 3166-1 alpha-2, derivado do IP do cliente), mailbox_provider e mailbox_provider_region. Verifique is_prefetched antes de contar uma abertura. Ele é true quando um recurso de privacidade da caixa de entrada buscou o pixel automaticamente em vez de uma pessoa abrir a mensagem, e contar esses casos infla sua taxa de abertura. Rastreamento de abertura e clique cobre a instrumentação.

O destinatário clicou em um link rastreado. Payload: url (o link clicado), ip_address e user_agent quando conhecidos; os eventos API adicionam country, mailbox_provider e mailbox_provider_region. Cliques são geralmente um sinal de engajamento mais forte do que aberturas, porque proxies de privacidade podem carregar pixels de rastreamento automaticamente.

O destinatário usou o link de cancelamento de inscrição no corpo da mensagem. Payload: apenas a base de identidade pelo webhook; os eventos API adicionam mailbox_provider e mailbox_provider_region. Registra uma preferência de opt-out que bloqueia e-mail de marketing. Links de cancelamento de inscrição cobre como o link é inserido no seu e-mail.

O destinatário usou o botão de cancelamento de inscrição com um clique que o provedor de caixa de correio exibe em sua própria interface, acionado pelos cabeçalhos List-Unsubscribe da mensagem. Payload: apenas a base de identidade pelo webhook (mais mailbox_provider e mailbox_provider_region dos eventos API); o mecanismo é o próprio tipo de evento, por isso é separado de email.unsubscribed. Também registra uma preferência de opt-out que bloqueia e-mail de marketing.

Dois eventos descrevem a mensagem como um todo em vez de um destinatário, então seu data tem email_id, workspace_id, tags e metadata, mas nenhuma identidade de destinatário. Ambos pertencem ao envio agendado.

Aceitamos um envio com um scheduled_at no futuro. Payload: a base de nível de mensagem mais scheduled_at. Quando esse momento chega, o ciclo de vida por destinatário começa em email.accepted.

Uma mensagem agendada foi cancelada antes de ser enviada, então não produz nenhum evento de ciclo de vida de destinatário. Payload: apenas a base de nível de mensagem.

email.received cobre e-mail de entrada. Dispara quando recebemos e analisamos uma mensagem de entrada. Seu payload inclui o inbound_message_id, endereçamento, assunto e vereditos de autenticação. Configuração, payload e o API de consulta estão em Recebimento de e-mail. Uma caixa de correio tem sua própria família email_mailbox.* além disso, coberta no guia de caixas de correio.

bounce_class é a classificação numérica de bounce incluída em email.bounced, email.out_of_band_bounce e email.deferred. Ela se agrupa no bounce_type genérico e mantém o código detalhado, para que você ainda possa distinguir uma caixa de correio cheia de uma falha de roteamento mesmo que ambos sejam reportados como soft:

Qualquer classe fora desta lista é mapeada para undetermined. Apenas bounces hard suprimem o endereço; soft, block, admin e undetermined não, porque o endereço ainda pode ser entregável.

Dois eventos adicionam um destinatário à lista de supressão do espaço de trabalho automaticamente, e bloqueiam tipos diferentes de e-mail:

Um hard bounce bloqueia tudo porque o próprio endereço não existe mais. Uma reclamação bloqueia apenas marketing, porque alguém que reportou sua newsletter como spam ainda precisa receber a redefinição de senha.

email.unsubscribed e email.list_unsubscribed bloqueiam e-mail da mesma forma que uma reclamação, apenas marketing, mas por meio de um registro diferente: em vez de adicionar uma supressão, registram o opt-out do destinatário como uma preferência declarada. O que um opt-out faz cobre esse registro em detalhes.

Cada adição dispara um evento email_suppression.created que contém o suppression_id, o email suprimido, o reason e o workspace_id. O esquema completo do registro e como gerenciar entradas manualmente estão no Guia de supressões.

Envios posteriores para um endereço suprimido são rejeitados de imediato como email.rejected com rejection_reason: "recipient_suppressed", e nunca contam contra sua entregabilidade.