Obtener el log de un correo

GET/v1/mails/{mail_id}/logs

Para desarrolladores

Descripción

Devuelve el recorrido de un correo: su estado de entrega, sus aperturas y clics, y la línea de tiempo de sus eventos. Sirve para diagnosticar por qué un correo rebotó o se descartó.

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

Path params:

mail_idstringobligatorio

Identificador del correo. Se obtiene con `GET /v1/mails`.

Response

200 OKDevuelve un objeto con 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.

subjectstring | null

Asunto.

senderstring | null

Email del remitente.

statusinteger | null

Estado de entrega: 1=received, 2=queued, 3=sent, 4=dropped, 5=deferred, 6=bounced, 7=onhold.

sent_atstring (date-time) | null

Fecha y hora de entrega al MX del destinatario.

delaynumber | null

Demora de entrega en segundos, desde la recepción hasta sent_at.

bounced_atstring (date-time) | null

Fecha y hora del rebote, si aplica.

bounce_reasonstring | null

Motivo del rebote reportado por el servidor remoto.

is_hard_bounceboolean | null

true si el rebote es permanente (dirección inexistente o bloqueada); false si es transitorio; null si no hubo rebote.

opensintegersiempre presente

Cantidad de aperturas registradas.

clicksintegersiempre presente

Cantidad de clicks registrados.

timelinearray de objeto `{event, timestamp, status, message, reason}`siempre presente

Línea de tiempo cronológica de los eventos del correo: los de entrega y los del destinatario.

timeline[]:

eventstring

Nombre del evento: received, queued, onhold, deferred, sent, dropped, bounced, opened, clicked, unsubscribed, complained. Un estado de entrega que no tenga nombre en esta lista se emite como status_<n> (con <n> el código numérico). Trate cualquier valor no reconocido como informativo.

timestampstring (date-time)

Fecha y hora del evento. Los eventos del destinatario (opened, clicked, unsubscribed, complained) se registran con precisión de un segundo; el resto, con centésimas. Cuando varios caen en el mismo segundo, el orden del arreglo sigue la secuencia del recorrido del correo, no el valor exacto de este campo.

statusstring, enum: `success | info | warning | error`

Categoría del evento.

messagestring

Descripción legible del evento, en español. En los eventos de entrega es el nombre del estado (p. ej. Enviado, Rebotado), seguido de la respuesta del servidor de destino cuando existe (p. ej. Enviado: 250 2.0.0 Ok). Los eventos del destinatario llevan su propia descripción (p. ej. Correo abierto (2 veces)). Su redacción puede cambiar: para la lógica de su sistema, use event, status y reason, nunca este campo.

reasonstring | null

Motivo declarado por el destinatario, presente solo en unsubscribed y complained. Es la forma estable del dato, y la que debe consumir un cliente: message lo repite como prosa. Los valores de unsubscribed son los de `GET /v1/mail-unsubscribes` y los de complained los de `GET /v1/mail-complaints`; es null cuando el destinatario no declaró ninguno. El vocabulario es abierto: maneje cualquier valor no reconocido con un caso por defecto.

Errores

Código	Cuándo
404	No existe un correo con ese mail_id en la instancia (mail_not_found).
404	El correo existió, pero es anterior a la retención en línea y ya no está disponible (mail_outside_retention).

Detalle en Errores genéricos (not-found) y Errores genéricos (mail-outside-retention).

Request

curl -X GET "https://$API_HOST/v1/mails/0190abc.../logs" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

{
"mail_id": "0190abc...",
"msg_id": "0190abc...",
"to": "[email protected]",
"subject": "Hello from Fidelizador",
"sender": "[email protected]",
"status": 3,
"sent_at": "2026-05-08T14:22:33Z",
"delay": 2.4,
"bounced_at": null,
"bounce_reason": null,
"is_hard_bounce": null,
"opens": 1,
"clicks": 0,
"timeline": [
  {
    "event": "received",
    "timestamp": "2026-05-08T14:22:31Z",
    "status": "info",
    "message": "Recibido / En proceso"
  },
  {
    "event": "queued",
    "timestamp": "2026-05-08T14:22:32Z",
    "status": "info",
    "message": "Procesado / En cola"
  },
  {
    "event": "sent",
    "timestamp": "2026-05-08T14:22:33Z",
    "status": "success",
    "message": "Enviado: 250 2.0.0 Ok: queued as 4XyZ..."
  },
  {
    "event": "unsubscribed",
    "timestamp": "2026-05-09T09:10:00Z",
    "status": "warning",
    "message": "Destinatario desuscrito: No quiero seguir recibiendo estos emails",
    "reason": "no_longer_interested"
  }
]
}