Listar correos

GET/v1/mails

Descripción

Lista paginada de mails del tenant con datos de entrega y engagement. Sin rango de fechas explícito, devuelve los últimos 3 meses.

Cada elemento de data[] es un destinatario: un envío con N destinatarios (el array to de POST .../send) produce N filas, cada una con su propio mail_id y su to singular, todas compartiendo el mismo msg_id. Para agrupar por envío lógico, usar msg_id (o el filtro custom_msg_id).

Autenticación

Authorizationbearer tokenheaderobligatorio: API key con scope mail:read. Formato: Bearer FD.<key_id>.<token>.
X-Instance-Slugstringheaderobligatorio

Request

Query params:

start_datestring (date, `YYYY-MM-DD`) | null: Fecha local de inicio. Fecha mal formada retorna 400.
end_datestring (date, `YYYY-MM-DD`) | null: Fecha local de fin. Fecha mal formada retorna 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: Página, 1-indexed. Default: 1.
page_sizeinteger: Tamaño de página, 1–100. Default: 20.
msg_idstring | null: Filtra por message ID (el message_id devuelto por `POST .../send`).
mail_idstring | null: Filtra por mail ID.
sender_idinteger | null: Filtra por id del remitente.
recipientstring | null: Filtra por email del destinatario - coincidencia exacta. Ver Filtros de texto.
custom_msg_idstring | null: Filtra por el identificador personalizado enviado en POST .../send.
custom_group_codestring | null: Filtra por el código de grupo personalizado enviado en POST .../send.
subjectstring | null: Filtra por asunto - coincidencia parcial, insensible a 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 mails con al menos una apertura; unopened retorna entregados sin aperturas; all no filtra. Omitido: sin filtro.

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_idstringobligatorio: Identificador del mail.
msg_idstring | null: Identificador del mensaje lógico (compartido entre destinatarios de un mismo envío).
tostringobligatorio: Email del destinatario (uno por fila - ver Descripción).
subjectstringobligatorio: Asunto.
senderstring | null: Email del remitente. null cuando el mail no tiene un remitente registrado.
statusinteger | null: Estado de entrega: 1=received, 2=queued, 3=sent, 4=dropped, 5=deferred, 6=bounced, 7=onhold.
opensintegerobligatorio: Cantidad de aperturas registradas.
clicksintegerobligatorio: 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: Fecha y hora programada de envío, si aplica.
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 en combinaciones de filtro donde el total no se puede resolver de forma económica — ver la semántica general en Paginación y formato de respuesta. pagination.has_more siempre está presente y es la señal confiable para paginar.

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": "alice@example.com",
    "subject": "Hello from Fidelizador",
    "sender": "newsletter@example.com",
    "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
}
}

Descripción​

Autenticación​

Request​

Response​

Descripción

Autenticación

Request

Response