Analítica
Las rutas siguientes son relativas a /v1/workspaces/{workspaceId} para claves de API. El GET /analytics existente devuelve agregados del transporte separados por producto y requiere emails:read. La interacción propia tiene un contrato separado: no sumes sus conteos con las aperturas y clics del proveedor.
curl "$SENDIRO_API_BASE/v1/workspaces/$SENDIRO_WORKSPACE_ID/analytics?period=last_7_days&mode=provider" \
-H "Authorization: Bearer $SENDIRO_API_KEY"Selecciona períodos y contexto
period admite all_time (predeterminado), last_7_days, last_30_days, current_month y custom. Con custom, aporta from y to como YYYY-MM-DD; ambos días se incluyen en UTC. No envíes esas fechas con otros períodos.
Últimos 7 o 30 días incluye hoy UTC y los 6 o 29 días anteriores. Este mes empieza el día 1 UTC y termina al finalizar el día UTC actual.
mode admite all (predeterminado), provider o simulation. Puedes añadir un solo contexto: broadcastId, automationId o emailId. Combinar varios, repetir parámetros o enviar filtros desconocidos devuelve error.
La analítica del transporte selecciona por acceptedAt e incluye filtros efectivos, rango UTC, scope y dateBasis. Un contexto de Marketing no cambia la cuota de Transactional ni el mes original de las reservas.
Reporte de interacción propia
curl "$SENDIRO_API_BASE/v1/workspaces/$SENDIRO_WORKSPACE_ID/analytics/engagement?period=last_7_days&mode=provider&product=marketing&view=filtered&dateBasis=acceptedAt" \
-H "Authorization: Bearer $SENDIRO_API_KEY"GET /analytics/engagement admite los filtros base de período, modo y contexto, además de:
| Filtro | Valores | Predeterminado |
|---|---|---|
product |
all, marketing, transactional |
all |
view |
all, filtered |
filtered |
dateBasis |
acceptedAt, observedAt |
acceptedAt |
acceptedAt selecciona una cohorte; la actividad posterior puede contar para esos correos. observedAt selecciona la recepción de solicitudes y devuelve tasas null porque no tiene un denominador equivalente de entregas. Las series siempre se agrupan por día UTC de observación. Los correos únicos se calculan para toda la selección; sumar los únicos diarios produce un total de únicos incorrecto.
El objeto data implementa ApiEngagementAnalytics, con schemaVersion: 1 y source: "sendiro_tracking":
| Campo | Significado |
|---|---|
totals, all, filtered |
Totales seleccionados y canales completo/filtrado. El filtro excluye automation_suspected y proxy_indicated; no certifica que la actividad desconocida sea humana. |
openRequests, clickRequests |
Observaciones HTTP capturadas distintas, incluidas solicitudes repetidas. |
openedEmails, clickedEmails |
Correos emitidos con alguna señal, no personas únicas. |
eligibleOpenDelivered, eligibleClickDelivered |
Denominadores separados de la cohorte entregada y medible. |
openRate, clickRate |
Fracción entre 0 y 1; el numerador intersecta correos entregados, elegibles y con señal. null significa que no existe un denominador válido. |
firstObservedAt, lastObservedAt |
Instantes anulables para ese canal y selección. |
coverage |
Conteos de correos medidos, desactivados, del proveedor y caducados; openTrackedEmails/clickTrackedEmails separados, measurementWindowDays: 90, measurementExpiredEmails, límite de retención y estado de disponibilidad. |
processing |
Observaciones pendientes y en cuarentena; valores mayores que cero indican proyección incompleta. |
series |
Días UTC de actividad con solicitudes y únicos por correo/día. |
links |
Detalle de correo/enlace/posición, URL segura para mostrar y conteos. La primera/última observación del enlace describe todas sus solicitudes capturadas, independientemente de view. No se devuelve la capacidad de destino. |
classifications |
Distribución de categorías del clasificador en la vista completa, útil para compararla con los totales filtrados. |
devices, operatingSystems, clients, locations |
Dimensiones derivadas, acotadas y aproximadas de la vista elegida. |
limits |
linksTruncated, locationsTruncated y disponibilidad autorizada del detalle de enlaces. Las tablas principales de enlaces/ubicación se limitan a 100 filas; los totales cubren la selección conservada completa. |
La cobertura es available, partial, disabled, no_eligible_messages o unavailable. Muestra guiones cuando no existe medición en vez de ceros exitosos. partial conserva los valores retenidos pero indica cobertura incompleta por historial caducado o plazos de medición que no se superponen con un período finito de actividad. retainedSince y expiredEmails describen el límite del historial; measurementExpiredEmails describe por separado los plazos de medición terminados. Una consulta histórica no promete conservar datos para siempre. La medición termina 90 días después de preparar el correo (measurementWindowDays), de forma independiente a conservar cada observación detallada 90 días desde su recepción y los agregados 13 meses. La elegibilidad de actividad intersecta el período consultado con el plazo de medición del correo; measurementExpiredEmails identifica los correos cuya medición terminó antes de ese período de actividad. En cohortes de aceptación y consultas históricas sin período, este conteo informa qué plazos terminaron hasta ahora y no elimina la elegibilidad histórica. Las observaciones históricas conservadas siguen disponibles. La redirección de enlaces tiene una política de retención independiente.
Las claves requieren emails:read. Las sesiones humanas requieren reports:read; el filtro emailId y el detalle de enlaces también requieren emails:read. Quien solo consulta agregados no recibe enlaces por correo. El DTO agregado no incluye identidad del contacto.
Historial de interacción por correo
curl "$SENDIRO_API_BASE/v1/workspaces/$SENDIRO_WORKSPACE_ID/emails/$SENDIRO_EMAIL_ID/engagement" \
-H "Authorization: Bearer $SENDIRO_API_KEY"GET /emails/{emailId}/engagement requiere emails:read y events:read; las sesiones humanas necesitan además reports:read. Su data es ApiEngagementHistory: observations, nextCursor, source y detailRetentionDays. Devuelve hasta 50 observaciones conservadas, de la más reciente a la más antigua. Envía el cursor recibido sin modificarlo como ?cursor=...; está vinculado al workspace y al correo.
Una observación tiene id estable, emailId, kind, linkId anulable, observedAt, processedAt anulable, procedencia y clasificación versionada. La clasificación incluye motivos acotados, indicios de proxy y dispositivo/SO/cliente/país/región derivados. Desconocido significa falta de evidencia, no actividad humana confirmada. La ubicación y dispositivo de un proxy no se atribuyen al destinatario. Por defecto no se conservan la IP ni el User-Agent completos.
El historial puede incluir observaciones capturadas pendientes de proyección. No es un flujo de eventos SMTP y no debe determinar aceptación, entrega, reservas, reintentos ni consentimiento.
Política de seguimiento
Las sesiones humanas consultan GET /analytics/tracking-policy con reports:read y la cambian mediante PATCH /analytics/tracking-policy con sending:manage. Estas operaciones no se ofrecen a claves de API. Las mutaciones usan las protecciones de CSRF, idempotencia y concurrencia del dashboard; proporciona la revisión actual If-Match: "rN".
{
"marketing": {"opens": true, "clicks": true},
"transactional": {"opens": false, "clicks": false}
}El DTO incluye revision numérica, updatedAt anulable, detailRetentionDays: 90 y aggregateRetentionMonths: 13. Ambos productos comienzan desactivados. La autoridad (sendiro, provider, disabled) y los indicadores efectivos se congelan al preparar cada correo. Los cambios no actualizan mensajes pendientes ni vistas previas. El seguimiento propio se aplica inicialmente a Kumo; SES conserva la autoridad del proveedor hasta una activación explícita que resuelva la doble instrumentación.
El HTML usa un píxel y redirecciones registradas para enlaces públicos elegibles. Los enlaces elegibles del texto plano también usan redirecciones; una alternativa del HTML reutiliza los mismos enlaces lógicos y conserva las exclusiones explícitas. El texto plano no tiene píxel de apertura. Se excluyen bajas, preferencias, autenticación, verificación, invitación, pagos y otras capacidades. La exclusión explícita por enlace y el contrato de preparación se documentan en la arquitectura de interacción del repositorio. Los encabezados independientes de baja y el pie visible de marketing siguen disponibles cuando el tracking está apagado.
Eventos y webhooks
La interacción propia emite los eventos existentes email.opened y email.clicked con un objeto opcional engagement que contiene source: "sendiro_tracking", classification, classifierVersion y, en clics, linkId. Los eventos históricos del proveedor conservan su procedencia.
La distribución se limita a la primera apertura filtrada por correo y al primer clic filtrado por correo/enlace. Las solicitudes adicionales siguen en reportes e historial, sin generar un webhook por cada solicitud de imagen. Los IDs de evento son estables ante replay del procesador. Se conservan el sobre y los reintentos habituales de webhooks. Las automatizaciones usan la misma exclusión de automatización sospechada y proxies indicados. Un webhook es una observación, nunca prueba de lectura, consentimiento, autenticación o pago.
Comportamiento público
GET /t/v1/o/{token}.gif devuelve una imagen transparente de 1×1; GET /t/v1/c/{token} redirige temporalmente a un destino registrado. No requieren sesión, cookies ni JavaScript. El manejo explícito de HEAD no captura actividad. El visitante no puede aportar un destino, y Sendiro no lo solicita desde el servidor.
Un fallo de medición no bloquea la redirección después de resolver y validar el destino. Si falla la resolución, no se puede redirigir de forma segura y se informa por separado. Las respuestas usan no-store y una política de referrer que no envía el token al destino. Los proxies pueden aun así almacenar imágenes, precargar contenido u ocultar interacciones reales. Los registros de CDN/plataforma pueden ver las rutas URL; el operador debe configurar su redacción y retención.
Conversiones futuras
V1 no tiene SDK ni endpoint de conversiones. Un contrato futuro debe incluir un ID de evento del emisor para idempotencia, nombre versionado, fecha del suceso, workspace autenticado, referencia de atribución verificada de forma independiente y propiedades permitidas. Antes de publicarse debe definir ventanas de atribución, consentimiento, eliminación y replay; una apertura no puede demostrar que ocurrió una conversión.
Lee las métricas
Aceptación de Sendiro, aceptación del transporte, entrega y observaciones de interacción son etapas distintas. Una entrega no garantiza bandeja principal; aperturas y clics pueden depender de privacidad y precarga de los clientes de correo. Un resultado incierto no equivale a fallo conocido.
Una selección vacía del transporte produce ceros; una consulta fallida es indisponibilidad. La interacción necesita además cobertura válida antes de mostrar un cero. Para investigar un mensaje usa su detalle y eventos.
La salud de recepción y recuperación de eventos requiere sesión humana; no se ofrece a claves en /analytics/health ni /provider-events. Consulta analítica de Marketing.