Saltar al contenido principal

Actividad de aperturas

GET/v1/activities/opens

Para desarrolladores

Descripción​

Lista las aperturas de sus correos, por evento, por destinatario o por mensaje según group_by:

  • none (default): una fila por cada apertura.
  • mail_id: una fila por destinatario.
  • msg_id: una fila por mensaje, que suma todos sus destinatarios.

Los filtros se aplican antes de agrupar. El conteo de cada fila sale de las aperturas dentro del rango, así que coincide con la suma del detalle.

Guía relacionada​

Autenticación​

Authorizationbearer tokenheaderobligatorio
API key con scope mail:read. Formato: Bearer <API_KEY>.
X-Instance-Slugstringheaderobligatorio
Identificador de su instancia. Ver Autenticación.

Request​

Query params:

start_datestring (date, `YYYY-MM-DD`) | null
Fecha local de inicio.
end_datestring (date, `YYYY-MM-DD`) | null
Fecha local de fin.
tzstring (zona IANA) | null
Zona para interpretar las fechas.
pageinteger
Número de página; la primera es la 1. Default: 1.
page_sizeinteger
Tamaño de página, 1–100. Default: 20.
group_bystring, enum: `none | mail_id | msg_id`
Nivel de agrupación. Default: none.
msg_idstring | null
Filtra por identificador de mensaje.
mail_idstring | null
Filtra por identificador de correo.
sender_idinteger | null
Filtra por id del remitente.
recipientstring | null
Filtra por email del destinatario, con coincidencia exacta por default. Con recipient_operator=starts_with, la coincidencia pasa a ser por prefijo (ver Filtros de texto).
recipient_operatorstring, enum: `eq | starts_with`
Operador de coincidencia para recipient: eq (exacto, default) o starts_with (el destinatario empieza con el valor dado). Se ignora si recipient no está presente.
custom_msg_idstring | null
Filtra por identificador de mensaje personalizado.
custom_group_codestring | null
Filtra por código de grupo personalizado.
subjectstring | null
Filtra por asunto, con coincidencia parcial e insensible a mayúsculas (ver Filtros de texto).

Response​

200 OKResponde con {data, pagination}. La forma de cada elemento de data depende de group_by.

Por defecto, una fila por apertura

mail_idstringsiempre presente
Identificador del correo.
msg_idstring | null
Identificador del mensaje.
tostringsiempre presente
Email del destinatario.
senderstringsiempre presente
Email del remitente.
opened_atstring (date-time)siempre presente
Fecha y hora de la apertura.
sent_atstring (date-time) | null
Fecha y hora de entrega.
custom_msg_idstring | null
Identificador personalizado del mensaje.
custom_group_codestring | null
Código de grupo personalizado.
Notas
  • pagination.total_items puede venir null. Con group_by=mail_id o group_by=msg_id viene siempre null, porque cada fila es un destinatario o un mensaje y no un evento; con group_by=none, según los filtros. Para paginar, use pagination.has_more, que siempre está presente.
  • Para exportar el mismo listado completo en CSV o JSON, use GET /v1/activities/opens/export.
Request
curl -X GET "https://$API_HOST/v1/activities/opens?group_by=msg_id&start_date=2026-07-01&end_date=2026-07-31" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"
Response
{
"data": [
  {
    "msg_id": "0190...",
    "sender": "[email protected]",
    "subject": "Hello",
    "open_count": 18,
    "recipients_opened": 11,
    "rcpt_count": 25,
    "first_opened_at": "2026-05-08T14:25:47Z",
    "last_opened_at": "2026-05-08T17:02:58Z",
    "custom_msg_id": null,
    "custom_group_code": null
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": null,
  "total_pages": null
}
}