GET /api/v1/campaigns/{campaignId}/stats
Cómo ha funcionado la campaña: las mismas cifras que muestra la pantalla Estadísticas.
| Campo | Descripción |
|---|---|
sent | Correos realmente despachados |
delivered | sent menos bounced |
bounced | Envíos rechazados por el lado receptor |
uniqueOpens / openRate | Contactos que abrieron al menos una vez, y su proporción sobre delivered |
uniqueClicks / clickRate | Contactos que hicieron clic al menos una vez, y su proporción sobre delivered |
unsubscribed / unsubscribeRate | Bajas atribuidas a esta campaña, y su proporción sobre delivered |
topicOptOuts | Destinatarios que desactivaron un tema a través de esta campaña: siguen suscritos |
clicksByLink | Por URL: {url, uniqueClicks, totalClicks} |
clicksOverTime | Por día: {date, clicks}, date en formato YYYY-MM-DD |
opensOverTime | Por día: {date, opens}, date en formato YYYY-MM-DD |
clicksByHour / opensByHour | Por hora desde el envío: {hour, clicks} / {hour, opens}, hour de 0 a 47 |
sentAt y siempre lleva las 48 franjas, incluidas las horas sin actividad. Las aperturas cuentan primeras aperturas, una por destinatario como máximo.
unsubscribed y topicOptOuts cuentan dos salidas distintas y nunca se solapan. Quien se da de baja deja de recibir todo lo tuyo; quien desactiva un tema sigue recibiendo el resto. Leerlos juntos te dice si una campaña perdió audiencia o solo perdió interés en un tema. topicOptOuts solo cubre las campañas enviadas desde que empezaron a registrarse las desactivaciones de tema; las más antiguas marcan 0.
Las tasas son proporciones sobre delivered, no sobre sent: una dirección que rebotó nunca tuvo la oportunidad de abrir. Mientras no se haya entregado nada, el denominador es cero y todas las tasas marcan 0, nunca NaN: consulta progress en la propia campaña para saber si el envío ha terminado antes de sacar conclusiones. Una campaña de otra organización responde 404, como un id que no existe.
Autorización
| Rol en la organización | Este endpoint |
|---|---|
OWNER | Permitido |
ADMIN | Permitido |
MEMBER | Permitido |
Ejemplo
bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
"https://www.agentsmail.io/api/v1/campaigns/$CAMPAIGN_ID/stats"Respuesta
200 OK: la llamada tuvo éxito.401 Unauthorized: clave ausente o no válida, o su propietario dejó la organización.404 Not Found: no existe ese recurso, o pertenece a otra organización. La API nunca confirma que un id existe a quien no tiene derecho sobre él.429 Too Many Requests: más de 120 solicitudes en un minuto para esta clave.
Campos de la respuesta
| Campo | Tipo | Descripción |
|---|---|---|
success | boolean | Indica si la operación tuvo éxito |
data.sent | number | Correos entregados al proveedor |
data.delivered | number | Aceptados por el servidor receptor |
data.bounced | number | Rechazados de forma permanente: la dirección pasa a la lista de supresión |
data.uniqueOpens | number | Destinatarios que cargaron el píxel de seguimiento al menos una vez |
data.openRate | number | Calculada sobre los entregados, no sobre los enviados |
data.uniqueClicks | number | Destinatarios que siguieron al menos un enlace con seguimiento |
data.clickRate | number | Misma base |
data.unsubscribed | number | Destinatarios que se dieron de baja a través de esta campaña |
data.unsubscribeRate | number | Misma base |
data.topicOptOuts | number | Destinatarios que desactivaron un tema a través de esta campaña, siguen suscritos |
data.clicksByLink | array | Una entrada por URL con seguimiento |
data.clicksOverTime | array | Clics agrupados por tiempo |
Ejemplo de respuesta
json
{
"success": true,
"data": {
"sent": 12,
"delivered": 12,
"bounced": 12,
"uniqueOpens": 12,
"openRate": 12,
"uniqueClicks": 12,
"clickRate": 12,
"unsubscribed": 12,
"unsubscribeRate": 12,
"topicOptOuts": 3,
"clicksByLink": [
{
"url": "https://example.com",
"clicks": 42
}
],
"clicksOverTime": [
{
"at": "2026-08-23T11:00:00.000Z",
"clicks": 12
}
]
}
}