Registros de Correo Electrónico

Busque, filtre e inspeccione registros detallados de entrega para cada correo electrónico enviado a través de Mail.Land

Esta página lista solo mensajes transaccionales: el correo de campañas y automatizaciones (incluidos los mensajes de sistema sys_*) queda excluido. Use el endpoint de destinatarios de campaña (vea Campañas) para el historial de envíos de marketing/automatización.

Listar Correos Electrónicos

GET https://api.mail.land/v1/transactional/logs

List emails

curl "https://api.mail.land/v1/transactional/logs?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Parámetros de Consulta

Parámetro	Tipo	Predeterminado	Descripción
`cursor`	string	-	Cursor opaco del `nextCursor` de la página anterior. Omitir para la primera página. Un cursor malformado o alterado devuelve `400 INVALID_CURSOR`.
`limit`	int	20	Elementos por página
`status`	string	-	Filtrar por estado (ver abajo)
`search`	string	-	Buscar por destinatario, asunto o ID de mensaje
`from`	datetime	Hace 30 días	Fecha de inicio
`to`	datetime	Ahora	Fecha de fin
`refresh`	bool	false	Evitar una página desactualizada: ya no existe una caché de recuento que omitir

Filtros de Estado

Valor	Coincidencia
`queued`	Esperando en cola
`sent`	Aceptado por MTA
`deferred` o `retrying`	Retrasado temporalmente
`delivered`	Entregado exitosamente
`bounced`	Rebote permanente
`failed`	Error del sistema o rebote administrativo
`opened`	El destinatario abrió el correo electrónico
`clicked`	El destinatario hizo clic en un enlace
`complained`	El destinatario reportó spam

Email logs response

{
  "items": [
    {
      "messageId": "t_a1b2c3d4e5f6",
      "recipient": "[email protected]",
      "subject": "Your order has shipped",
      "status": "delivered",
      "sentAt": "2026-02-17T12:34:56Z",
      "deliveredAt": "2026-02-17T12:34:58Z",
      "openedAt": "2026-02-17T13:15:00Z",
      "clickedAt": null,
      "bounceReason": null,
      "openCount": 2,
      "clickCount": 0
    },
    {
      "messageId": "t_d4e5f6a1b2c3",
      "recipient": "[email protected]",
      "subject": "Invoice #1234",
      "status": "bounced",
      "sentAt": "2026-02-17T12:30:00Z",
      "deliveredAt": null,
      "openedAt": null,
      "clickedAt": null,
      "bounceReason": "550 5.1.1 Mailbox not found",
      "openCount": 0,
      "clickCount": 0
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Prioridad de Estado

El campo status refleja el evento de mayor prioridad para cada correo electrónico:

complained (mayor prioridad)
clicked
opened
Estado de entrega: queued → sent → deferred → delivered → bounced → failed

Por ejemplo, si un correo electrónico fue entregado y luego abierto, el estado muestra opened.

Se aplica un rango de fechas predeterminado de 30 días por rendimiento. El parámetro de búsqueda filtra por correo del destinatario, línea de asunto o ID de mensaje (sin distinción de mayúsculas y minúsculas).

Estadísticas de Registros

Obtenga estadísticas agregadas para sus registros de correo electrónico:

GET https://api.mail.land/v1/transactional/logs/stats

Get log stats

curl "https://api.mail.land/v1/transactional/logs/stats" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Parámetro	Tipo	Predeterminado	Descripción
`from`	datetime	Hace 7 días	Fecha de inicio
`to`	datetime	Ahora	Fecha de fin
`emailType`	int	-	`0` = Transaccional, `1` = Marketing. Omitirlo abarca todos los tipos de correo: a diferencia de "Listar correos" más arriba, que solo cubre transaccionales.
`refresh`	bool	false	Omitir caché

Log stats response

{
  "total": 4750,
  "accepted": 4750,
  "sent": 4700,
  "delivered": 4680,
  "opened": 1498,
  "clicked": 195,
  "bounced": 38,
  "complained": 1,
  "failed": 12,
  "queued": 20,
  "deliveryRate": 99.57,
  "openRate": 32.01,
  "clickRate": 13.02,
  "bounceRate": 0.81,
  "complaintRate": 0.021,
  "source": "clickhouse",
  "queryTimeMs": 32
}

Cálculos de tasas:

Tasa	Fórmula
`deliveryRate`	`delivered / sent * 100`
`openRate`	`opened / delivered * 100`
`clickRate`	`clicked / delivered * 100`
`bounceRate`	`bounced / sent * 100`
`complaintRate`	`complained / sent * 100` (3 decimales)

Los encabezados de respuesta indican el estado del caché:

Encabezado	Valores
`X-Cache`	`HIT`, `MISS` o `FRESH`
`X-Stats-Source`	`cache` o `clickhouse`
`Cache-Control`	Siempre `no-store, no-cache, must-revalidate`

Detalle del Correo Electrónico

Obtenga detalles completos de un correo electrónico específico, incluyendo la cronología de eventos:

GET https://api.mail.land/v1/transactional/logs/{messageId}

Get email detail

curl https://api.mail.land/v1/transactional/logs/t_a1b2c3d4e5f6 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Email detail response

{
  "messageId": "t_a1b2c3d4e5f6",
  "recipient": "[email protected]",
  "fromEmail": "[email protected]",
  "subject": "Your order has shipped",
  "status": "opened",
  "sentAt": "2026-02-17T12:34:56Z",
  "deliveredAt": "2026-02-17T12:34:58Z",
  "openedAt": "2026-02-17T13:15:00Z",
  "clickedAt": null,
  "createdAt": "2026-02-17T12:34:55Z",
  "bounceReason": null,
  "bounceCategory": null,
  "ipAddress": null,
  "retryCount": 0,
  "smtpResponse": "250 2.0.0 OK",
  "openCount": 2,
  "clickCount": 0,
  "htmlContent": "<html>...</html>",
  "textContent": "Your order has shipped...",
  "events": [
    {
      "eventType": "delivered",
      "timestamp": "2026-02-17T12:34:58Z",
      "ipAddress": null,
      "userAgent": null,
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": "250 2.0.0 OK",
      "deviceType": null,
      "browser": null,
      "country": null,
      "city": null
    },
    {
      "eventType": "opened",
      "timestamp": "2026-02-17T13:15:00Z",
      "ipAddress": "203.0.113.45",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": null,
      "deviceType": "desktop",
      "browser": "Chrome",
      "country": "US",
      "city": "San Francisco"
    },
    {
      "eventType": "opened",
      "timestamp": "2026-02-17T14:30:00Z",
      "ipAddress": "203.0.113.45",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)",
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": null,
      "deviceType": "mobile",
      "browser": "Safari",
      "country": "US",
      "city": "San Francisco"
    }
  ]
}

El arreglo events proviene de ClickHouse y está ordenado por marca de tiempo. Si ClickHouse no está disponible temporalmente, el detalle del correo electrónico se devuelve desde PostgreSQL pero events será un arreglo vacío.

Campos de Eventos

Campo	Descripción
`eventType`	`delivered`, `opened`, `clicked`, `bounced`, `complained`, y también `accepted`, `sent`, `deferred`, `admin_bounce`, `oob_bounce`, `expired`
`timestamp`	Cuándo ocurrió el evento (UTC)
`ipAddress`	IP del cliente (para aperturas/clics)
`userAgent`	Cadena de agente de usuario del cliente
`linkUrl`	URL clicada (para eventos `clicked`)
`bounceType`	`hard`, `soft` o `unknown` (para eventos `bounced`)
`bounceReason`	Respuesta SMTP (para eventos `bounced`)
`smtpResponse`	Respuesta del servidor remoto (para eventos `delivered`)
`deviceType`	`desktop`, `mobile` o `tablet`
`browser`	Nombre del navegador (Chrome, Safari, Firefox, etc.)
`country`	Código de país ISO
`city`	Nombre de la ciudad

Reintentar un Correo Electrónico Fallido

Reintentar la entrega de un correo electrónico rebotado o fallido:

POST https://api.mail.land/v1/transactional/logs/{messageId}/retry

Retry failed email

curl -X POST https://api.mail.land/v1/transactional/logs/t_a1b2c3d4e5f6/retry \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

El mensaje debe estar en estado Bounced o Failed, y el destinatario no debe estar suprimido.

Estado	Código	Descripción
`200`	-	Reintento aceptado
`400`	`INVALID_REQUEST`	El correo electrónico no está rebotado ni fallido
`400`	`RECIPIENT_SUPPRESSED`	El destinatario está en la lista de supresión
`404`	`RESOURCE_NOT_FOUND`	Mensaje no encontrado: no `EMAIL_NOT_FOUND`
`422`	`DOMAIN_NOT_VERIFIED`	El dominio de envío ya no está verificado
`429`	`MARKETING_PAUSED`	El envío de marketing está actualmente en pausa para este espacio de trabajo
`422`	`RETRY_ATTACHMENTS_UNAVAILABLE`	El mensaje tenía adjuntos que ya no se pueden recuperar; envíelo de nuevo con sus adjuntos
`422`	`RETRY_ATTACHMENTS_UNKNOWN`	El mensaje se envió antes de que se registraran los adjuntos, por lo que un reintento no puede garantizarlos; envíelo de nuevo
`429`	`PLATFORM_CAPACITY_PROTECTION`	El nuevo envío está en pausa breve para proteger la capacidad de la plataforma; no se cambió nada, reintente en breve
`503`	`RETRY_ATTACHMENT_STORAGE_UNAVAILABLE`	No se pudieron leer los adjuntos ahora; no se cambió nada, reintente en breve

El reintento crea un nuevo trabajo de correo electrónico con el contenido original y lo pone en cola para su entrega. Las copias reenviadas se envían sin seguimiento de apertura/clic.

Pasos Siguientes

Descripción general de analíticas: resúmenes de eventos agregados y tasas
Analíticas avanzadas: desgloses geográficos, por dispositivo y por hora del día
Rebotes: comprender el manejo de rebotes y reintentos

Registros de Correo Electrónico

Listar Correos ElectrónicosCopiar enlace de la sección

Parámetros de ConsultaCopiar enlace de la sección

Filtros de EstadoCopiar enlace de la sección

Prioridad de EstadoCopiar enlace de la sección

Estadísticas de RegistrosCopiar enlace de la sección

Detalle del Correo ElectrónicoCopiar enlace de la sección

Campos de EventosCopiar enlace de la sección

Reintentar un Correo Electrónico FallidoCopiar enlace de la sección

Pasos SiguientesCopiar enlace de la sección

En esta página