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. As solicitações exigem acesso de leitura ao escopo emails.

Para relatórios com filtros combinados, métricas selecionadas e séries temporais completas por grupo, use o endpoint de consulta flexível. Para explorar esses relatórios por meio de um assistente, veja Consultar análises de e-mail com IA.

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 solicitaçã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.

As taxas são retornadas como frações, 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. Taxas de abertura e clique podem exceder 1 quando engajamento e entrega caem em janelas diferentes. A fórmula exata por trás de cada taxa, incluindo como um bounce out-of-band tardio altera as entregas efetivas, está documentada por campo na referência do resumo.

As respostas de resumo, diária e horária ecoam a janela e incluem data_as_of, a última atualização bem-sucedida do agregado quando disponível. Ele pode ser nulo, e um timestamp não garante que todos os eventos tenham chegado. O endpoint de consulta flexível sempre retorna data_as_of: null. Exiba um timestamp de atualização disponível no seu dashboard sem apresentá-lo como prova de dados completos.

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:

Limites em instantes têm granularidade de hora, o que torna um "last 24 hours" deslizante uma única requisiçã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 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:

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 requisiçã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.

{
  "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 de calendário 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

• Consultar análises de e-mail com IA: exemplos de prompts para relatórios de entrega, engajamento e latência via MCP
• 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