Estadísticas de email API

API de estadísticas de correo electrónico devuelve los agregados que se muestran en el panel de Metrics, más el veredicto de salud de envío calculado a partir de ellos. Úsalo para construir paneles, exportar datos o monitorear la salud del correo electrónico. Requieren una clave API con acceso de lectura al alcance emails.

Los métodos tipados están disponibles en los SDKs de TypeScript, Python, PHP y Go bajo email.stats y email.health, el bird CLI los expone como bird email stats y bird email health, y un agente los alcanza a través de las herramientas de MCP email_stats_* y email_health. Los esquemas completos de solicitud y respuesta están en la referencia de API.

El agregado y la serie temporal

Tres endpoints cubren la parte superior del dashboard:

GET /v1/email/stats/summary devuelve una fila agregada para toda la ventana. Incluye conteos de ciclo de vida para aceptados, entregados, rebotados, reclamados, abiertos, clicados y sus subtipos. También incluye los valores derivados delivery_rate, bounce_rate, complaint_rate, open_rate y click_rate. Los percentiles de latencia de procesamiento, entrega y total cubren p50, p95 y p99. Pasa compare=previous_period y la respuesta también incluye la ventana anterior de igual duración y el cambio respecto a ella.
GET /v1/email/stats/daily y GET /v1/email/stats/hourly devuelven los mismos conteos con una fila por día o por hora, rellenando con filas en cero para que un gráfico nunca tenga huecos.

Cada tasa se devuelve como una fracción entre 0 y 1, así que un delivery_rate de 0.9939 es 99,39 %. Una tasa cuyo denominador es cero es null, que es como un periodo sin entregas reporta open_rate en lugar de mostrar 0. Las tasas usan tiempo de evento para la atribución. El momento de envío no afecta en qué ventana se incluye un evento, así que la interacción que llega durante la ventana para un mensaje anterior sí se incluye. La fórmula exacta detrás de cada una, incluyendo cómo un rebote tardío fuera de banda mueve a un destinatario fuera del conteo de entregados, está documentada por campo en la referencia del resumen.

Cada respuesta repite la ventana contra la que calculó, más data_as_of: el instante hasta el cual las cifras están actualizadas. La agregación se refresca cada pocos segundos, por lo que una respuesta es casi en tiempo real, no en vivo. Etiqueta tu propio dashboard con data_as_of en lugar de presentar los números como si fueran al segundo.

Elegir la ventana

from y to aceptan un día calendario (YYYY-MM-DD) o un instante RFC 3339, y las formas que acepta cada endpoint difieren:

Endpoint	Límites	Ventana máxima
/summary	Ambos días, o ambos instantes	365 días, o 720 horas con instantes
/daily	Días calendario	365 días
/hourly	Instantes RFC 3339	720 horas (30 días)

Los límites con instantes tienen granularidad de hora, lo que permite que un "last 24 hours" móvil sea una sola solicitud. En /summary, mezclar un día con un instante devuelve un 422.

Establece timezone con un identificador IANA como America/New_York para que los límites de día y hora, y los valores por defecto que se usan cuando omites from y to, se calculen en esa zona en lugar de UTC. Mientras timezone esté establecido, from y to no deben incluir un desplazamiento UTC propio.

Desgloses

Los 13 endpoints de desglose dividen los mismos números de entrega e interacción por una dimensión:

Remitentes: /sending-domains, /sending-ips y /recipient-domains (el dominio de buzón al que enviaste).
Dónde llegó: /mailbox-providers (Gmail, Outlook, etc.) y /mailbox-provider-regions.
Qué enviaste: /tags (las etiquetas que estableces al enviar, el corte más flexible), /categories, /templates y /broadcasts.
Contexto de interacción: /locations (geografía del destinatario) y /clients (el cliente de correo que renderizó la apertura).
Fallos: /bounce-codes (agrupados por la respuesta del servidor receptor) y /complaint-types.

Todos están bajo /v1/email/stats/. Las filas se devuelven ordenadas de forma descendente por una métrica sort y limitadas a limit (por defecto 50, máximo 200). La respuesta también incluye total, la cantidad de valores de dimensión distintos en la ventana. Compara total con el número de filas devueltas para identificar un resultado truncado. Las filas cuya métrica de ordenación es una tasa con denominador cero van al final.

El valor por defecto de sort de cada endpoint es la métrica para la cual existe ese desglose:

Por defecto	Desgloses
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 añade una serie de tasas por intervalo a cada fila, lista para sparklines. Se aplica a los desgloses de tag, category, template, sending-domain, sending-IP, recipient-domain, mailbox-provider y mailbox-provider-region.

Los endpoints de resumen y series temporales también aceptan un filtro de dimensión por solicitud. Elige category, sending_domain, sending_ip, recipient_domain, tag o template. El filtro limita un agregado a un remitente o campaña sin cambiar a un desglose. Pasar más de uno devuelve un 422.

Salud de envío

GET /v1/email/health responde la pregunta que los agregados te dejan a ti: si tu envío se encamina a problemas. Devuelve un veredicto para la ventana más señales de entrega, aperturas, rebotes y quejas. Cada señal incluye su tasa y veredicto. Las señales de entrega, rebote y queja también incluyen los límites que determinan sus veredictos; la tasa de apertura no tiene límites de riesgo. Esto permite que una insignia de estado siga nuestras bandas sin necesidad de compilar una copia de ellas en tu propio cliente.

Ejemplo 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
      }
    }
  ]
}

Compara cada señal por su metric. El status de nivel superior es el peor de los veredictos de entrega, rebote y queja: healthy, watching o throttled. open_rate queda fuera de esa agregación, porque una tasa de apertura alta nunca es un riesgo, y es la única señal que puede tener el valor strong.

Dos campos de una señal son fáciles de confundir. limit es el límite de referencia de entregabilidad para la tasa, y es null en las tasas que no tienen uno. thresholds es donde cambia el veredicto en sí: watching y throttled son los dos límites, y direction indica el lado de riesgo, above para las tasas de rebote y queja y below para la tasa de entrega. Los límites son exclusivos, así que una tasa que cae exactamente en uno conserva el mejor estado.

Como los límites vienen en la respuesta, puedes calificar segmentos que este endpoint no calcula: ordena tus remitentes con /sending-domains y luego clasifica cada fila contra los límites de tasa de rebote que devolvió la respuesta de salud. El panel de Metrics usa bandas de advertencia separadas para las tasas de rebote duro y de queja. Este API evalúa las tasas agregadas de rebote, queja y entrega, así que su veredicto puede diferir de una advertencia del panel.

Un veredicto throttled informa sobre el riesgo de entregabilidad. No pausa tu envío.

La ventana funciona de manera diferente a los endpoints anteriores. from y to son días calendario en UTC, no existe el parámetro timezone y no se aplica ningún filtro de dimensión. Si omites ambos, la ventana termina hoy y comienza 7 días antes. El máximo es 365 días.

Tráfico de prueba en los números

Los envíos a direcciones de sandbox pasan por la misma agregación, así que el tráfico de prueba aparece en cada endpoint exactamente como lo hace en el panel.

Próximos pasos

Métricas de correo electrónico: cómo el panel presenta estos números y cuándo actuar sobre ellos
Referencia de resumen de estadísticas: cada campo, filtro y fórmula de tasa
Referencia de salud de envío: el veredicto, sus señales por tasa y sus límites
Eventos y webhooks: el flujo por destinatario cuando un agregado no es suficiente

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Ver la guíaGetting started with email Explorar la funcionalidadEmail Seguir la ruta de aprendizajeBuild your first integration Guía de implementaciónSend your first email

Prueba el ejercicio y obtén un resumen de implementación