Estatísticas de e-mail API

O API de estatísticas de e-mail retorna os agregados exibidos no painel de Métricas, além do veredito de saúde de envio calculado a partir deles. Use-o para criar dashboards, exportar dados ou monitorar a saúde do e-mail. Eles exigem uma chave API com acesso de leitura ao escopo emails.

Métodos tipados estão disponíveis nos SDKs de TypeScript, Python, PHP e Go em email.stats e email.health, a bird CLI os expõe como bird email stats e bird email health, e um agente os acessa pelas ferramentas MCP email_stats_* e email_health. Os esquemas completos de requisição e resposta estão na referência API.

O agregado e a série temporal

Três endpoints cobrem o topo do painel:

GET /v1/email/stats/summary retorna uma linha agregada para toda a janela. Inclui contagens de ciclo de vida para aceitos, entregues, rejeitados, reclamados, abertos, clicados e seus subtipos. Também inclui os valores derivados delivery_rate, bounce_rate, complaint_rate, open_rate e click_rate. Percentis de latência de processamento, entrega e total cobrem p50, p95 e p99. Passe compare=previous_period e a resposta também inclui a janela anterior de mesmo comprimento e a variação em relação a ela.
GET /v1/email/stats/daily e GET /v1/email/stats/hourly retornam as mesmas contagens com uma linha por dia ou por hora, preenchidas com linhas zero para que um gráfico nunca tenha lacunas.

Toda taxa é retornada como uma fração entre 0 e 1, então um delivery_rate de 0.9939 equivale a 99,39%. Uma taxa cujo denominador é zero é null, que é como um período sem entregas reporta open_rate em vez de exibir 0. As taxas usam o horário do evento para atribuição. O horário de envio não afeta em qual janela um evento é incluído, então engajamento que chega durante a janela referente a uma mensagem anterior é incluído. A fórmula exata por trás de cada uma, incluindo como um bounce out-of-band tardio remove um destinatário da contagem de entregues, está documentada por campo na referência do resumo.

Toda resposta ecoa a janela contra a qual foi calculada, mais data_as_of: o instante até o qual os números estão atualizados. A agregação é atualizada a cada poucos segundos, então a resposta é quase em tempo real, não ao vivo. Rotule seu próprio dashboard com data_as_of em vez de apresentar os números como sendo precisos ao segundo.

Escolhendo a janela

from e to aceitam um dia de calendário (YYYY-MM-DD) ou um instante RFC 3339, e as formas aceitas variam por endpoint:

Endpoint	Limites	Janela máxima
/summary	Ambos dias, ou ambos instantes	365 dias, ou 720 horas com instantes
/daily	Dias de calendário	365 dias
/hourly	Instantes RFC 3339	720 horas (30 dias)

Limites em instantes têm granularidade de hora, o que torna um "last 24 hours" deslizante uma única solicitação. Em /summary, misturar um dia com um instante retorna um 422.

Defina timezone como um identificador IANA, como America/New_York, para que os limites de dia e hora e os valores padrão usados quando você omite from e to sejam calculados nesse fuso em vez de UTC. Enquanto timezone estiver definido, from e to não podem incluir um deslocamento UTC próprio.

Desagregações

Os 13 endpoints de desagregação dividem os mesmos números de entrega e engajamento por uma dimensão:

Remetentes: /sending-domains, /sending-ips e /recipient-domains (o domínio da caixa de correio para o qual você enviou).
Onde chegou: /mailbox-providers (Gmail, Outlook etc.) e /mailbox-provider-regions.
O que você enviou: /tags (as tags que você definiu no momento do envio, o corte mais flexível), /categories, /templates e /broadcasts.
Contexto de engajamento: /locations (geografia do destinatário) e /clients (o cliente de e-mail que renderizou a abertura).
Falhas: /bounce-codes (agrupadas pela resposta do servidor receptor) e /complaint-types.

Todos estão sob /v1/email/stats/. As linhas são retornadas classificadas em ordem decrescente por uma métrica sort e limitadas a limit (padrão 50, máximo 200). A resposta também inclui total, o número de valores distintos da dimensão na janela. Compare total com a contagem de linhas retornadas para identificar um resultado truncado. Linhas cuja métrica de ordenação é uma taxa com denominador zero ficam por último.

O padrão de sort de cada endpoint é a métrica pela qual ele existe para classificar:

Padrão	Desagregações
processed	/tags, /categories, /templates, /broadcasts, /sending-domains, /recipient-domains
delivered	/sending-ips, /mailbox-providers, /mailbox-provider-regions
unique_opens	/locations, /clients
bounced	/bounce-codes
complained	/complaint-types

include_trend=true adiciona uma série de taxas por intervalo a cada linha, pronta para sparklines. Aplica-se às desagregações por tag, categoria, template, domínio de envio, IP de envio, domínio do destinatário, provedor de caixa de correio e região do provedor de caixa de correio.

Os endpoints de resumo e série temporal também aceitam um filtro de dimensão por solicitação. Escolha category, sending_domain, sending_ip, recipient_domain, tag ou template. O filtro restringe um agregado a um remetente ou campanha sem mudar para uma desagregação. Passar mais de um retorna um 422.

Saúde de envio

GET /v1/email/health responde à pergunta que os agregados deixam para você: se o seu envio está caminhando para problemas. Ele retorna um veredito para a janela, além de sinais para entrega, aberturas, bounces e reclamações. Cada sinal traz sua taxa e seu veredito. Os sinais de entrega, bounce e reclamação também trazem os limites que definem seus vereditos; a taxa de abertura não tem limites de risco. É isso que permite que um badge de status acompanhe nossas faixas sem uma cópia delas compilada no seu próprio cliente.

Exemplo de código

{
  "period": {
    "data_as_of": null,
    "from": "2026-05-25",
    "to": "2026-06-01"
  },
  "status": "watching",
  "signals": [
    {
      "metric": "delivery_rate",
      "value": 0.995,
      "limit": null,
      "status": "healthy",
      "thresholds": {
        "direction": "below",
        "throttled": 0.984,
        "watching": 0.99
      }
    },
    {
      "metric": "open_rate",
      "value": 0.20100503,
      "limit": null,
      "status": "healthy"
    },
    {
      "metric": "bounce_rate",
      "value": 0.005,
      "limit": 0.005,
      "status": "watching",
      "thresholds": {
        "direction": "above",
        "throttled": 0.006,
        "watching": 0.004
      }
    },
    {
      "metric": "complaint_rate",
      "value": 0.00010050251,
      "limit": 0.003,
      "status": "healthy",
      "thresholds": {
        "direction": "above",
        "throttled": 0.001,
        "watching": 0.0006
      }
    }
  ]
}

Compare cada sinal pelo seu metric. O status de nível superior é o pior entre os vereditos de entrega, bounce e reclamação: healthy, watching ou throttled. open_rate fica fora dessa consolidação, porque uma taxa de abertura alta nunca é um risco, e é o único sinal que pode retornar strong.

Dois campos de um sinal são fáceis de confundir. limit é o limite de referência de entregabilidade para a taxa, e é null nas taxas que não possuem um. thresholds é onde o veredito em si muda: watching e throttled são os dois limites, e direction indica o lado de risco deles, above para taxas de bounce e reclamação e below para taxa de entrega. Os limites são exclusivos, então uma taxa exatamente sobre um deles mantém o status melhor.

Como os limites voltam na resposta, você pode classificar fatias que esse endpoint não calcula: ordene seus remetentes com /sending-domains e depois classifique cada linha com base nos limites de taxa de bounce que a resposta de saúde retornou. O painel de Métricas usa faixas de alerta separadas para taxas de hard-bounce e reclamação. Esse API avalia taxas agregadas de bounce, reclamação e entrega, então o veredito dele pode diferir de um alerta do painel.

Um veredito throttled indica risco de entregabilidade. Ele não pausa o seu envio.

A janela funciona de forma diferente dos endpoints acima. from e to são dias corridos em UTC, não há parâmetro timezone e nenhum filtro de dimensão se aplica. Omita ambos e a janela termina hoje e começa 7 dias antes. O máximo é 365 dias.

Tráfego de teste nos números

Envios para endereços sandbox passam pela mesma agregação, então o tráfego de teste aparece em todos os endpoints aqui exatamente como aparece no painel.

Próximos passos

Métricas de e-mail: como o painel apresenta esses números e quando agir sobre eles
Referência do resumo de estatísticas: cada campo, filtro e fórmula de taxa
Referência de saúde de envio: o veredito, seus sinais por taxa e seus limites
Eventos e webhooks: o fluxo por destinatário quando um agregado não é suficiente

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaGetting started with email Explore a funcionalidadeEmail Siga o percurso de aprendizagemBuild your first integration Guia de implementaçãoSend your first email

Experimente na prática e obtenha um resumo de implementação