Entregabilidad y rebotes mediante API y MCP

El panel de TrekMail muestra dos tipos de datos de rebotes en la pestaña Estadísticas de cada dominio:

1. Un resumen de 30 días: cantidades de enviados, entregados, rebotes suaves y rebotes duros, además de las tasas de entrega y rebote.
2. Una lista por destinatario: los últimos 50 rebotes salientes con el código de estado y la respuesta SMTP del receptor, para que puedas ver por qué falló un mensaje concreto.

Ambos están disponibles mediante REST API y el servidor MCP. Un agente puede obtener los motivos de los rebotes, resumir el estado de la reputación y alimentar procesos de higiene de listas sin abrir el panel.

Datos disponibles

Las tres requieren domains:read (o mailboxes:read para la lista limitada al buzón). Son de solo lectura. No necesitan clave de idempotencia.

La API usa los mismos datos de entregabilidad que las tarjetas de estadísticas del panel, por lo que ambas vistas se mantienen sincronizadas.

REST API: ejemplos rápidos

Resumen del dominio

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/deliverability?days=30" | jq .

{
  "data": {
    "from": "2026-04-26T00:00:00+00:00",
    "to":   "2026-05-26T23:59:59+00:00",
    "sent": 4180,
    "delivered": 4112,
    "soft_bounce": 22,
    "hard_bounce": 46,
    "forwarding_bounces_excluded": 7,
    "delivery_rate": 0.9837,
    "bounce_rate": 0.0163,
    "status": "good"
  }
}

status es la misma señal de tres estados que presenta el panel:

• good: tasa de rebote inferior al 2%.
• warning: tasa de rebote entre el 2% y el 5%.
• poor: tasa de rebote igual o superior al 5%. Revisa y limpia la lista de envío.

forwarding_bounces_excluded indica cuántos rebotes relacionados con el reenvío se excluyeron del cálculo de las tasas (al igual que en el panel, que los considera incidencias de enrutamiento y no problemas de la lista del remitente).

Lista de rebotes por destinatario

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/bounces?days=7&type=hard&limit=50" | jq .

{
  "data": [
    {
      "id": 994821,
      "occurred_at": "2026-05-26T18:14:02+00:00",
      "recipient_email": "lost@example.com",
      "event_type": "hard_bounce",
      "smtp_status_code": "550",
      "smtp_response": "5.1.1 The email account that you tried to reach does not exist.",
      "mailbox_id": 7741,
      "domain_id": 123
    }
  ],
  "pagination": { "total": 17, "limit": 50, "offset": 0 }
}

Parámetros de consulta

Lista limitada al buzón

Para analizar la reputación por remitente, limita la consulta a un buzón:

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/mailboxes/7741/bounces?days=14&type=soft" | jq .

La respuesta tiene la misma estructura que en el endpoint del dominio.

Privacidad de las respuestas SMTP

TrekMail elimina la información de diagnóstico interna antes de devolver una respuesta SMTP. El mensaje restante es el mismo que se muestra al propietario de la cuenta en el panel y sirve para ayudar a diagnosticar la entrega, no para exponer datos internos del servidor.

Herramientas MCP

Las tres herramientas aceptan los mismos parámetros que los endpoints REST. Son de solo lectura y no cambian el correo ni la configuración de la cuenta.

get_domain_deliverability

{
  "name": "get_domain_deliverability",
  "arguments": {
    "domain_id": 123,
    "days": 30
  }
}

list_domain_bounces

{
  "name": "list_domain_bounces",
  "arguments": {
    "domain_id": 123,
    "type": "hard",
    "days": 7,
    "limit": 100
  }
}

list_mailbox_bounces

{
  "name": "list_mailbox_bounces",
  "arguments": {
    "mailbox_id": 7741,
    "recipient": "@example.com",
    "limit": 50
  }
}

Encabezados de entregabilidad para remitentes masivos

Si envías correo de marketing o masivo por suscripción, los principales proveedores de buzones pueden exigir encabezados de cancelación con un clic. Google aplica esta regla a los mensajes de marketing y suscripción de remitentes que superan su umbral de envío masivo; la regla de un clic no se aplica a mensajes transaccionales. Hay dos formas de adjuntar los encabezados:

Por mensaje (granular). Pásalos mediante el campo headers de POST /api/v1/messages/send:

{
  "to": ["recipient@example.com"],
  "subject": "...",
  "body": {"text": "..."},
  "headers": {
    "List-Unsubscribe": "<mailto:bounces@mydomain.com?subject=unsubscribe>, <https://mydomain.com/u/abc123>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

El campo headers acepta una pequeña lista permitida: List-Unsubscribe, List-Unsubscribe-Post, Reply-To y cualquier encabezado de seguimiento personalizado X-*. La inyección de encabezados (CR/LF) y los encabezados gestionados (From, Subject, Date, Message-Id, Authentication-Results, DKIM-Signature, etc.) se rechazan con 422.

En toda la cuenta (configurar una vez). Si todos los mensajes salientes de esta cuenta están automatizados, puedes activar auto_list_unsubscribe en la cuenta. Cuando está activada, la plataforma añade un encabezado List-Unsubscribe solo con mailto a cada mensaje saliente que no tenga ya uno. No añade List-Unsubscribe-Post, por lo que esta opción alternativa no ofrece cancelación con un clic según RFC 8058. Para cumplir los requisitos de cancelación con un clic de los proveedores, proporciona ambos encabezados por mensaje con tu propio endpoint HTTPS de cancelación, como en el ejemplo anterior. Los encabezados proporcionados por el solicitante siempre tienen prioridad. La opción está desactivada de forma predeterminada y las cuentas existentes no cambian.

Para el correo personal entre dos personas, deja la opción desactivada. Gmail puede mostrar un botón Cancelar suscripción junto al remitente cuando este encabezado está presente, lo que normalmente no es adecuado para una conversación.

Patrones para agentes de IA

Algunos flujos útiles que permiten estos endpoints:

• Resumen semanal de reputación. Cada lunes, llama a get_domain_deliverability para cada dominio de la cuenta y publica un resumen en Slack/Teams. Destaca solo los dominios cuyo status sea warning o poor.
• Higiene de listas basada en rebotes. Llama a list_domain_bounces?type=hard&days=14, elimina duplicados de recipient_email y después suprime esas direcciones de tu lista de envío. Los rebotes duros suelen indicar que la dirección del destinatario ya no existe, y volver a enviar consume el margen de entregabilidad.
• Análisis por remitente. Cuando el bounce_rate de un buzón aumenta repentinamente, llama a list_mailbox_bounces para ese buzón y agrupa los resultados por smtp_status_code. Muchos códigos 550 pueden indicar que la lista de direcciones quedó obsoleta; muchos códigos 421 pueden indicar que el servidor receptor limitó tu frecuencia.
• Investigación de atención al cliente. Cuando un usuario informa que no llegó un correo, pide al agente que llame a list_domain_bounces?recipient=<their-address>. La respuesta SMTP puede indicar la siguiente acción, como un buzón del destinatario lleno, un bloqueo del destinatario o un rechazo DMARC.

Versionado

Estos endpoints siguen el mismo contrato de versiones que el resto de la API v1: solo cambios aditivos, sin cambios incompatibles de nombres de campo fuera de un espacio de nombres v2/.

Contenido relacionado

• Métricas de spam: telemetría de protección contra spam entrante (get_spam_metrics, get_spam_summary).
• Verificador de correo: limpieza de listas antes del envío para evitar los rebotes.
• Descripción general de la API: autenticación, ámbitos, límites de frecuencia e idempotencia.