Estadísticas, bounces y audit

Estos tres endpoints te dan visibilidad completa de lo que pasó con tus correos: cuántos se enviaron, cuáles rebotaron, y un registro detallado de cada evento. Úsalos para monitorear la salud de tu deliverability, depurar problemas de entrega y generar reportes de actividad.

Operaciones disponibles

GET /v1/mail/stats

Devuelve métricas agregadas del servidor para el período indicado.

GET https://api.mailerdash.com/v1/mail/stats

Query params:

Parámetro	Tipo	Default	Descripción
hours	integer	24	Ventana de tiempo hacia atrás. Máximo 720 (30 días).
key_id	string	—	Solo admin. Filtra métricas por API key específica.

Ejemplo:

curl https://api.mailerdash.com/v1/mail/stats?hours=48 \
  -H "Authorization: Bearer $MAILERDASH_API_KEY"

---

GET /v1/mail/bounces

Lista los bounces procesados por el sistema, del más reciente al más antiguo.

GET https://api.mailerdash.com/v1/mail/bounces

Query params:

Parámetro	Tipo	Default	Descripción
limit	integer	100	Número de resultados. Máximo 1000.
offset	integer	0	Cursor de paginación.
recipient	string	—	Filtra por dirección de correo del destinatario.
status	string	—	Filtra por código DSN (ej. 5.1.1 para usuario inexistente).
key_id	string	—	Solo admin. Filtra por API key.

Respuesta:

{
  "total": 42,
  "limit": 100,
  "offset": 0,
  "items": [
    {
      "id": 17,
      "recipient": "inexistente@example.com",
      "status": "5.1.1",
      "raw": "User unknown",
      "created_at": "2026-06-21T14:32:00Z"
    }
  ]
}

---

GET /v1/mail/audit

Audit log de envíos y acciones de la cuenta, con soporte para filtros avanzados y exportación a CSV.

GET https://api.mailerdash.com/v1/mail/audit

Query params:

Parámetro	Tipo	Default	Descripción
limit	integer	100	Número de resultados. Máximo 1000.
offset	integer	0	Cursor de paginación.
app	string	—	Filtra por key ID (app en el audit).
event	string	—	Filtra por tipo de evento: sent, failed, queued. Acepta CSV para múltiples: sent,failed.
from	string	—	Timestamp ISO 8601 de inicio del rango (ej. 2026-06-01T00:00:00Z).
to	string	—	Timestamp ISO 8601 de fin del rango.
search	string	—	Búsqueda de substring contra el recipient o el asunto.
sort_by	string	ts	Campo de ordenamiento: ts, event, subject.
sort_dir	string	desc	Dirección: asc o desc.
format	string	json	json (paginado) o csv (descarga completa, ignora limit/offset).

Respuesta JSON:

{
  "total": 1240,
  "limit": 100,
  "offset": 0,
  "items": [
    {
      "id": 998,
      "ts": "2026-06-22T09:15:00Z",
      "event": "sent",
      "app": "<key-id>",
      "recipient": "cliente@example.com",
      "subject": "Tu recibo #4567",
      "message_id": "<abc123@api.mailerdash.com>"
    }
  ]
}

Ejemplo: stats de las últimas 48 horas

curl "https://api.mailerdash.com/v1/mail/stats?hours=48" \
  -H "Authorization: Bearer $MAILERDASH_API_KEY"

Ejemplo: bounces de un destinatario específico

curl "https://api.mailerdash.com/v1/mail/bounces?recipient=usuario@example.com&limit=20" \
  -H "Authorization: Bearer $MAILERDASH_API_KEY"

Ejemplo: audit de envíos fallidos en rango de fechas

curl "https://api.mailerdash.com/v1/mail/audit?event=failed&from=2026-06-01T00:00:00Z&to=2026-06-22T23:59:59Z&sort_dir=asc" \
  -H "Authorization: Bearer $MAILERDASH_API_KEY"

Exporta a CSV con ?format=csv

El parámetro format=csv en /v1/mail/audit descarga el log completo sin límite de paginación. Es ideal para importar a Excel, Google Sheets o procesar offline con herramientas como pandas. Los filtros event, from, to y search funcionan igual que en el modo JSON.

curl "https://api.mailerdash.com/v1/mail/audit?format=csv&from=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -o audit-junio.csv

Referencia

Para el esquema completo de respuestas y códigos de error, consulta la referencia de API transaccional.