Saltar al contenido principal

Listar correos

GET/v1/mails

Para desarrolladores

Descripción​

Lista los correos de la instancia, uno por destinatario, con su estado de entrega, aperturas y clics. Si no se indica un rango de fechas, devuelve los últimos 3 meses.

Cada elemento de data[] es un destinatario. Una llamada a POST /v1/mails/send genera una fila por cada destinatario de to, cc y bcc. Cada fila tiene su propio mail_id y su to, y todas comparten el mismo msg_id. Para agrupar los correos de una misma llamada, filtre por msg_id o por custom_msg_id.

Guía relacionada​

  • Enviar su primer correo — Haga el primer envío desde su sistema, por la API o por SMTP, con un ejemplo para copiar.

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. Una fecha mal formada devuelve 400.
end_datestring (date, `YYYY-MM-DD`) | null
Fecha local de fin. Una fecha mal formada devuelve 400.
tzstring (zona IANA, ej. `America/Santiago`) | null
Zona con la que se interpretan start_date/end_date. Sin valor: la zona de la instancia, o UTC si la instancia no tiene una configurada. Una zona inválida se ignora (misma resolución que si no se hubiera enviado).
pageinteger
Número de página; la primera es la 1. Default: 1.
page_sizeinteger
Tamaño de página, 1–100. Default: 20.
msg_idstring | null
Filtra por el message_id que devuelve `POST /v1/mails/send`.
mail_idstring | null
Filtra por mail_id.
sender_idinteger | null
Filtra por id del remitente.
recipientstring | null
Filtra por el email del destinatario, con coincidencia exacta (ver Filtros de texto).
custom_msg_idstring | null
Filtra por el identificador personalizado enviado en POST /v1/mails/send.
custom_group_codestring | null
Filtra por el código de grupo personalizado enviado en POST /v1/mails/send.
subjectstring | null
Filtra por asunto, con coincidencia parcial y sin distinguir mayúsculas (ver Filtros de texto).
statusinteger | null
Filtra por estado de entrega (1–7: 1=received, 2=queued, 3=sent, 4=dropped, 5=deferred, 6=bounced, 7=onhold).
openedstring, enum: `all | opened | unopened` | null
opened retorna solo correos con al menos una apertura; unopened retorna entregados sin aperturas; all no filtra. Si se omite, no se filtra.

Response​

200 OKDevuelve una página de resultados: data con los elementos y pagination para pedir la siguiente. Cada elemento tiene los campos que siguen.
mail_idstringsiempre presente
Identificador del correo.
msg_idstring | null
Identificador del mensaje. Lo comparten todos los destinatarios de una misma llamada a `POST /v1/mails/send`.
tostringsiempre presente
Email del destinatario, uno por fila (ver Descripción).
subjectstringsiempre presente
Asunto.
senderstring | null
Email del remitente. null cuando el correo no tiene un remitente registrado.
statusinteger | null
Estado de entrega: 1=received, 2=queued, 3=sent, 4=dropped, 5=deferred, 6=bounced, 7=onhold.
opensintegersiempre presente
Cantidad de aperturas registradas.
clicksintegersiempre presente
Cantidad de clicks registrados.
received_atstring (date-time) | null
Fecha y hora de recepción.
queued_atstring (date-time) | null
Fecha y hora de encolado en el MTA.
sent_atstring (date-time) | null
Fecha y hora de entrega al MX del destinatario.
schedule_atstring (date-time) | null
Siempre es null: el envío programado no está disponible.
delaynumber | null
Demora de entrega en segundos, desde la recepción hasta sent_at.
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 algunas combinaciones de filtros. Para paginar, use pagination.has_more, que siempre está presente (ver Paginación y formato de respuesta).
Request
curl -X GET "https://$API_HOST/v1/mails?start_date=2026-07-01&end_date=2026-07-31&status=3" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"
Response
{
"data": [
  {
    "mail_id": "0190...",
    "msg_id": "0190...",
    "to": "[email protected]",
    "subject": "Hello from Fidelizador",
    "sender": "[email protected]",
    "status": 3,
    "opens": 1,
    "clicks": 0,
    "received_at": "2026-05-08T14:22:31Z",
    "queued_at": "2026-05-08T14:22:32Z",
    "sent_at": "2026-05-08T14:22:33Z",
    "schedule_at": null,
    "delay": 2.4,
    "custom_msg_id": null,
    "custom_group_code": null
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": 1,
  "total_pages": 1
}
}