Sign inGet Started

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, novas 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 tentamos enviá-la novamente (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}.

O envelope do evento

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.

Exemplo de código
{
  "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,
    "brand_id": null
  }
}

Todo evento de saída no nível do destinatário inclui email_id, recipient_id, workspace_id, o endereço recipient e seu recipient_role de envelope (to, cc ou bcc). Ao enviar, armazene um mapeamento do espaço de trabalho e do ID da mensagem para seus próprios registros. tags e metadata trazem o contexto do envio quando disponível. Eles são nulos quando nenhum contexto foi fornecido e em email.unsubscribed e email.list_unsubscribed originados de links de cancelamento de inscrição Bird de envios individuais. Eventos de cancelamento de inscrição de broadcast também podem retornar nulo quando o contexto deles não está disponível.

broadcast_id nomeia o broadcast do qual um envio fez parte e é nulo em um envio sem broadcast por trás. 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 nulo independentemente de um broadcast ter enviado o e-mail. Trate nulo em email.unsubscribed e email.list_unsubscribed como inconclusivo. broadcast_id chega a você apenas no webhook: a API de eventos abaixo retorna cada evento sem ele. Os tipos de evento adicionam campos descritos nas seções a seguir.

Os webhooks de e-mails enviados também incluem o campo opcional brand_id. A API de eventos de mensagens omite esse campo.

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.

Eventos de ciclo de vida

email.accepted

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.

email.processed

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 nosso 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.

email.delivered

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.

email.deferred

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.

Eventos de falha

email.bounced

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.

email.out_of_band_bounce

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.

email.rejected

A mensagem destinada ao destinatário nunca chegou ao servidor de e-mail remoto, portanto nenhuma entrega foi tentada. Isso distingue uma rejeição de um bounce, no qual é o servidor receptor que recusa a mensagem. Payload: rejection_reason, também presente no registro do destinatário:

rejection_reasonSignificado
recipient_suppressedO destinatário está bloqueado pela lista de supressão ou por uma preferência declarada, então a entrega nunca foi tentada
transmission_failedA mensagem não pôde ser transmitida para entrega
generation_failureA mensagem não pôde ser construída para entrega devido a um problema de template ou conteúdo
policy_rejectionA política de envio recusou a mensagem
domain_unverifiedO domínio de envio não foi verificado
quota_exceededA cota de envio da organização foi atingida
recipient_not_allowedO destinatário não era permitido para este envio; envios em um domínio de onboarding compartilhado alcançam apenas membros verificados do seu espaço de trabalho
workspace_suspendedO espaço de trabalho está suspenso, portanto este e-mail não foi enviado nem será enviado após a reativação

Bird adiciona motivos de rejeição com o tempo, então um webhook ou registro de destinatário pode conter um motivo que ainda não aparece nesta tabela. Trate um motivo desconhecido como uma rejeição com causa não listada e preserve o valor para consultá-lo depois.

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.

email.complained

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 bloqueia e-mail de marketing para a Brand à qual foi atribuída, ou em todo o espaço de trabalho quando não há atribuição confiável de Brand. Mantenha sua taxa de reclamação baixa: provedores limitam remetentes que acumulam relatórios.

Eventos de engajamento

email.opened

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.

email.clicked

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.

email.unsubscribed

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.

email.list_unsubscribed

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.

Eventos de nível de mensagem

Dois eventos descrevem a mensagem inteira, em vez de um destinatário. Seu data contém, portanto, email_id, workspace_id, brand_id, tags e metadata, mas nenhuma identidade de destinatário. Ambos pertencem ao envio agendado.

email.scheduled

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.

email.canceled

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.

Eventos de entrada e caixa de correio

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.

Classificação de bounce

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:

bounce_classbounce_typeSignificado
1undeterminedA resposta do servidor receptor foi ambígua
10, 30hardFalha permanente: endereço inválido ou domínio inexistente
20 a 24, 40, 70, 100softFalha temporária: caixa de correio cheia, servidor temporariamente indisponível, problema de DNS ou roteamento
25adminRecusa administrativa: retransmissão negada, domínio em lista de bloqueio
50 a 54blockO servidor receptor recusou o IP de envio

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.

Supressão automática

Hard bounces criam supressões em todo o espaço de trabalho. Reclamações de spam com atribuição confiável de Brand registram preferências de e-mail protegidas para essa Brand; reclamações sem atribuição confiável criam supressões em todo o espaço de trabalho.

EventoResultadoO que bloqueia
email.bounced ou email.out_of_band_bounce com bounce_type: "hard"Supressão com reason: hard_bounceTodas as categorias em todas as Brands
email.complained com atribuição de Brand confiávelPreferência com origin: complaintE-mail não transacional dessa Brand
email.complained sem atribuição de Brand confiávelSupressão com reason: complaintE-mail não transacional em todas as Brands

email.complained continua sendo o evento de reclamação no nível da mensagem. Uma reclamação de Brand que altera a preferência efetiva para revogada também emite preference.revoked, com preference_id e brand_id. Reclamações repetidas não precisam produzir outra transição de preferência. Consulte a preferência para ver a origem e o status atuais e o complaint_message_id retido.

Assine preference.revoked, preference.granted e preference.deleted ao sincronizar as escolhas dos destinatários, mesmo em um espaço de trabalho com uma única Brand. Use-os para atualizar a preferência atual e seu escopo de canal, identificador, Brand, remetente e tópico. Os timestamps de preferência descrevem o momento efetivo do consentimento, não a ordem das alterações; ordená-los não reconstrói o status nem a cobertura atuais. Confirme exclusões por meio de reconciliação, mantendo as preferências independentes e as supressões do espaço de trabalho.

Uma reclamação restrita a uma Brand não emite email_suppression.created. Esse evento descreve adições à lista de supressão do espaço de trabalho, com suppression_id, email, reason e workspace_id. Remoções de supressão não têm webhook para clientes, então um espelho também precisa de reconciliação periódica da lista paginada completa. As supressões por reclamação já existentes no espaço de trabalho mantêm seu escopo. Siga a receita de sincronização do guia de migração, incluindo tentar novamente leituras que falham ou que ainda não refletem uma alteração.

email.unsubscribed e email.list_unsubscribed também registram preferências. Links de cancelamento de inscrição explica o efeito deles. Supressões explica como inspecionar a proteção contra reclamações e registrar um opt-in individual mais recente.

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.

Próximos passos