Lógica de Reintentos

Cuando una entrega de webhook falla, MailLand reintenta automáticamente con retrasos crecientes. Esta página cubre el calendario de reintentos, los estados de entrega, el manejo de errores y cómo monitorear y reintentar entregas manualmente.

Calendario de ReintentosCopiar enlace de la sección

Esta sección cubre todos los eventos que entrega el durable dispatcher: message.*, suppression.*, account.* e inbound.received. Lo específico de los eventos de entrada está en Entregas Entrantes más abajo.

MailLand reintenta una entrega fallida hasta 6 veces en total, con un retraso creciente antes de cada reintento:

Si el 6.º intento falla, la entrega se marca como fallida permanentemente: no hay más espera ni un 7.º intento.

Reintentable vs No ReintentableCopiar enlace de la sección

Respuestas reintentablesCopiar enlace de la sección

Estos códigos de estado activan reintentos automáticos:

• 408 Request Timeout
• 429 Too Many Requests
• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout
• Errores de red (tiempos de espera, errores de socket, fallos de DNS)

Respuestas no reintentablesCopiar enlace de la sección

Estos códigos de estado se tratan como fallos permanentes, sin reintento:

• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• Todos los demás errores 4xx (excepto 408 y 429)
• Una respuesta de redirección que falla la validación (consulta Redirecciones) o supera el límite de saltos

RedireccionesCopiar enlace de la sección

MailLand no trata tu endpoint como lo haría un navegador. Las redirecciones se siguen manualmente, con un máximo de 3 saltos, y cada salto se revalida antes de enviar nada a él:

• el destino debe ser https://: una redirección a http:// se rechaza, no se degrada;
• el destino debe resolver a una dirección pública: una redirección a una dirección privada, loopback o link-local se rechaza, y la solicitud nunca se emite;
• superar 3 saltos hace fallar la entrega.

Una redirección rechazada se reporta como un fallo de entrega sin código de estado. Si tu endpoint se movió, apunta el webhook a la nueva URL en lugar de depender de una redirección.

Configuración de EntregaCopiar enlace de la sección

Entregas EntrantesCopiar enlace de la sección

inbound.received se entrega con el mismo durable dispatcher que cualquier otro evento, con el mismo calendario de reintentos, el mismo tratamiento de Retry-After, el mismo historial de entregas y la misma pausa automática descritos arriba.

• Deduplique con event_id (igual a X-MLND-Event-Id), como en cualquier otro evento. Es estable por mensaje de entrada y webhook, así que cada intento para el mismo correo lleva el mismo id.
• Un reenvío manual es un evento nuevo: un event_id nuevo, con el original en data.replay_of. data.idempotency_key no cambia.
• La download_url de cada adjunto se firma en cada intento y vale 15 minutos desde ese momento; el id del adjunto es el mismo en cada intento. Consulte Webhooks de entrada.

Ver Historial de EntregasCopiar enlace de la sección

Consulte las entregas anteriores para un webhook:

GET https://api.mail.land/v1/webhooks/{id}/deliveries

curl -X GET "https://api.mail.land/v1/webhooks/wh_abc123/deliveries?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Parámetros de ConsultaCopiar enlace de la sección

{
  "items": [
    {
      "publicId": "p8r2kx7m9wq4rtz",
      "eventType": "message.delivered",
      "messageId": "t_a1b2c3d4e5f6",
      "statusCode": 200,
      "responseTimeMs": 145,
      "success": true,
      "errorMessage": null,
      "createdAt": "2026-02-17T12:34:58.000Z",
      "attemptNumber": 1
    },
    {
      "publicId": "p8r2kx7m3nq1abc",
      "eventType": "message.bounced",
      "messageId": "t_d4e5f6a1b2c3",
      "statusCode": 503,
      "responseTimeMs": 15000,
      "success": false,
      "errorMessage": "Service Unavailable",
      "createdAt": "2026-02-17T12:30:00.000Z",
      "attemptNumber": 3
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Reintentar una Entrega FallidaCopiar enlace de la sección

Reintente manualmente una entrega fallida específica:

POST https://api.mail.land/v1/webhooks/{id}/deliveries/{publicId}/retry

curl -X POST https://api.mail.land/v1/webhooks/wh_abc123/deliveries/p8r2kx7m3nq1abc/retry \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Devuelve 202 Accepted en caso de éxito. El reintento se pone en cola y usa la carga útil del evento original.

Pausa Automática por FallosCopiar enlace de la sección

Cuando un webhook acumula suficientes intentos de entrega fallidos consecutivos, MailLand lo pausa automáticamente. El umbral es el pauseThreshold propio del webhook cuando está configurado en un valor mayor que 0, y en caso contrario el valor por defecto de 10 intentos de entrega fallidos consecutivos:

1. El isActive del webhook se establece en false, y se rellenan pausedAt y pausedReason: pausedReason indica cuántos fallos hubo y cuál fue el último
2. Se crea una notificación en la aplicación
3. No se entregan más eventos hasta que se reanude el webhook

El contador es de intentos, no de eventos: un solo evento que agota toda su escalera de reintentos contribuye con varios fallos.

No hay una notificación de advertencia previa antes de alcanzar el umbral: revisa consecutiveFailures de forma proactiva (ver Buenas Prácticas más abajo) en lugar de esperar a que te avisen.

Reanudar un Webhook en PausaCopiar enlace de la sección

POST https://api.mail.land/v1/webhooks/{id}/resume

curl -X POST https://api.mail.land/v1/webhooks/wh_abc123/resume \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Esto reactiva el webhook: borra el estado de pausa, restablece el contador de fallos consecutivos a cero y lo vuelve a marcar como activo. El siguiente intento de entrega de eventos se realizará normalmente.

Buenas PrácticasCopiar enlace de la sección

• Devuelva 200 rápidamente: procese las cargas útiles de webhook de forma asíncrona. Ponga el evento en cola y devuelva 200 inmediatamente. Los controladores de larga duración corren riesgo de tiempo de espera.
• Use el ID de evento para el consumo idempotente: el encabezado X-MLND-Event-Id (y el campo event_id correspondiente en la carga útil) es estable a través de reintentos y reenvíos: el mismo evento subyacente siempre llega con el mismo ID, sin importar cuántas veces se reenvíe. Almacene los IDs procesados y omita los que ya manejó, de modo que una entrega duplicada sea un no-op de su lado.
• Monitoree los fallos consecutivos: revise el campo consecutiveFailures al listar webhooks. Investigue antes de alcanzar el umbral de pausa automática.
• Maneje correctamente el 429: si su punto de conexión está sobrecargado, devuelva 429 con un encabezado Retry-After. MailLand lo respetará.

Próximos PasosCopiar enlace de la sección

• Verificación de firma: verificar la autenticidad del webhook
• Eventos: referencia completa de tipos de eventos
• Descripción general de webhooks: cree y administre webhooks