Eventos de Webhook

El catálogo de eventos de MailLand define 21 tipos de eventos en 6 categorías (2 de los 21 son avisos de la plataforma a los que no puedes suscribirte). Cada evento se entrega como una solicitud HTTP POST firmada a tu endpoint de webhook.

Catálogo de eventosCopiar enlace de la sección

Obtén el catálogo completo de eventos de forma programática:

GET https://api.mail.land/v1/webhooks/catalog

curl -X GET https://api.mail.land/v1/webhooks/catalog

{
  "version": 1,
  "products": [
    { "id": "transactional", "name": "Transactional Email", "isActive": true, "comingSoon": false },
    { "id": "marketing", "name": "Marketing Email", "isActive": true, "comingSoon": false },
    { "id": "inbound", "name": "Inbound Email", "isActive": true, "comingSoon": false },
    { "id": "system", "name": "System Events", "isActive": true, "comingSoon": false },
    { "id": "validation", "name": "Email Validation", "isActive": false, "comingSoon": true }
  ],
  "categories": [
    {
      "id": "message",
      "name": "Message Events",
      "events": [
        { "id": "message.sent", "name": "Message Sent", "products": ["transactional", "marketing"] },
        { "id": "message.delivered", "name": "Message Delivered", "products": ["transactional", "marketing"] }
      ]
    }
  ]
}

Este endpoint es público (no requiere autenticación) y siempre devuelve la versión más reciente del catálogo.

Estructura estándar de datosCopiar enlace de la sección

Cada entrega de webhook incluye una estructura externa coherente:

{
  "event": "message.delivered",
  "event_id": "evt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
  "timestamp": "2026-02-17T12:34:56.789Z",
  "occurred_at": "2026-02-17T12:34:56.120Z",
  "schema_version": 1,
  "data": {
    // Event-specific fields
  }
}

El data de cada evento de mensaje también incluye status_version, status, previous_status, complaint_status y reason, consulta Versiones de estado.

Versiones de estadoCopiar enlace de la sección

Cada evento de mensaje incluye data.status_version, data.status, data.previous_status, data.complaint_status y data.reason. status_version aumenta en uno cada vez que MailLand envía un evento por un cambio en el estado del mensaje, en su motivo o en su estado de queja.

Dos excepciones:

• Un mensaje empieza en status_version 0 mientras está queued o sent. El paso de queued a sent no envía ningún evento ni cambia la versión.
• Varios eventos message.deferred pueden compartir una status_version: un retraso repetido no cambia el estado.

Los webhooks pueden llegar desordenados y reintentarse, así que aplícalos por status_version, nunca por orden de llegada.

Un estado puede cambiar después de haber sido final. MailLand informa de lo que sabe cuando lo sabe. Cuando sabe más después, envía el estado nuevo con una status_version mayor:

• un mensaje entregado puede rebotar después, cuando el servidor del destinatario lo rechaza más tarde (un rebote fuera de banda);
• tras un fallo interno, o cuando el servidor de correo de MailLand se recupera, una entrega o un rechazo puede notificarse tarde. Un mensaje failed puede pasar entonces a bounced o delivered, un mensaje bounced puede pasar a delivered, y un mensaje unknown puede pasar a cualquier estado final.

Un mensaje nunca pasa de delivered a failed. MailLand contabiliza estas correcciones.

Plazos de reintentoCopiar enlace de la sección

MailLand reintenta un mensaje diferido hasta su plazo de reintento: unas 5 horas después de entregarlo por primera vez a la cola de entrega en el correo transaccional, y unas 25 horas en el correo de marketing. Pasado el plazo, MailLand no pone el mensaje en cola para ningún intento nuevo. Una copia que ya esperaba una conexión al llegar el plazo todavía puede intentarse después. Son plazos de reintento, no promesas sobre cuándo recibirás el evento final. Recibes cada evento en cuanto el resultado llega a MailLand; ese retraso aún no está medido y puede ser mayor durante una caída interna. Un mensaje que MailLand no pudo entregar a su cola de entrega en 24 horas se termina como expired.

Si guardas el estado actual de un mensaje a partir de los webhooks (acción necesaria)Copiar enlace de la sección

Es un cambio de comportamiento para las integraciones existentes. Una integración que trata message.failed o message.delivered como permanentes, e ignora los eventos posteriores, puede quedarse con un estado incorrecto tras una corrección. Nombres de eventos que ya existen tienen ahora secuencias posibles nuevas.

• Suscríbete a todos los eventos de mensaje: message.delivered, message.deferred, message.bounced, message.failed, message.complained, message.outcome_unknown y message.retried. Solo así los eventos que recibes contienen cada cambio de estado.
• Guarda status_version junto con el estado. Aplica un evento solo si su status_version es mayor que la guardada; un message.deferred con la misma versión no cambia nada.
• Sigue procesando eventos después de message.failed, message.bounced o message.delivered: un evento posterior con una status_version mayor sustituye al estado anterior.
• Cuando hayas recibido todos los eventos hasta la status_version de la API, tu estado es igual al de la API. La API puede ir por delante de los webhooks recibidos hasta ese momento y, con status_version 0, puede mostrar sent sin ningún evento.

Si te suscribes solo a algunos eventos de mensaje, la status_version más alta que recibiste no es necesariamente el estado actual: un tipo de evento al que no te suscribiste puede haberlo cambiado. Lee el estado actual desde la API, por ejemplo para cada mensaje cuyo último evento recibido sea message.failed, message.bounced o message.outcome_unknown, y concilia.

Si no puedes cambiar tu integración, consulta en la API el estado de los mensajes que te importan. Las integraciones que solo cuentan eventos, o que solo muestran un historial, no necesitan cambios.

Eventos de mensajeCopiar enlace de la sección

message.sentCopiar enlace de la sección

Ilustrativo: aún no se emite. Este evento está catalogado pero hoy no tiene productor.

{
  "event": "message.sent",
  "event_id": "evt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
  "timestamp": "2026-02-17T12:34:56.789Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:34:56.789Z"
  }
}

message.deliveredCopiar enlace de la sección

Se dispara cuando el correo se entrega correctamente al servidor de correo del destinatario.

Este evento también puede llegar como corrección después de un estado final anterior del mismo mensaje. Consulta Versiones de estado.

{
  "event": "message.delivered",
  "event_id": "evt_b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "timestamp": "2026-02-17T12:34:58.123Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:34:58.123Z",
    "smtp_response": "OK",
    "status_version": 1,
    "status": "delivered",
    "previous_status": "sent",
    "complaint_status": "none",
    "reason": null
  }
}

message.deferredCopiar enlace de la sección

Se dispara cuando la entrega se retrasa temporalmente. MailLand reintentará automáticamente.

Un mensaje puede diferirse varias veces. El primer diferimiento aumenta status_version; los siguientes llevan la misma status_version.

{
  "event": "message.deferred",
  "event_id": "evt_c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
  "timestamp": "2026-02-17T12:35:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:35:00.000Z",
    "smtp_response": "Try again later",
    "bounce_reason": "TransientFailure"
  }
}

message.bouncedCopiar enlace de la sección

Se dispara cuando un correo rebota (rebote duro o suave).

Este evento también puede llegar como corrección después de un estado final anterior del mismo mensaje. Consulta Versiones de estado.

{
  "event": "message.bounced",
  "event_id": "evt_d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
  "timestamp": "2026-02-17T12:35:01.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:35:01.000Z",
    "bounce_type": "hard",
    "bounce_reason": "InvalidRecipient",
    "smtp_response": "The email account that you tried to reach does not exist.",
    "status_version": 1,
    "status": "bounced",
    "previous_status": "sent",
    "complaint_status": "none",
    "reason": "InvalidRecipient"
  }
}

bounce_reason es el token de clasificación que MailLand asigna al rebote (por ejemplo, InvalidRecipient, QuotaIssues, SpamBlock), no el texto SMTP crudo, usa smtp_response para eso. bounce_type es uno de hard, soft, blocked o unknown.

smtp_response es el texto de respuesta del servidor destinatario, sin su código de respuesta numérico ni su código de estado extendido. bounce_type indica qué hizo MailLand con la dirección: hard, suprimida para todo el correo; soft, suprimida para el correo de marketing durante 30 días; blocked, el rechazo se refería al envío, no a la dirección (por ejemplo, filtrado de spam, autenticación del remitente, reputación o la política del destinatario), así que no se suprime nada; unknown, sin clasificación, se trata como soft.

message.failedCopiar enlace de la sección

Se dispara cuando MailLand termina un mensaje con pruebas concluyentes de que no se entregó, por un motivo del lado de MailLand y no del destinatario. En los casos descritos en Versiones de estado, puede seguir un message.delivered o un message.bounced con una status_version mayor. El estado del mensaje pasa a Failed, no a Bounced, y reason indica el caso:

• El destinatario no se suprime y el fallo no cuenta para tu tasa de rebote.
• Un mensaje produce como máximo un message.failed. Es el último evento de ese mensaje salvo que MailLand reciba después una entrega o un rechazo; en ese caso sigue un message.delivered o un message.bounced con una status_version mayor.

Un rechazo del servidor de correo receptor se notifica como message.bounced, nunca como message.failed.

{
  "event": "message.failed",
  "event_id": "evt_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "timestamp": "2026-09-28T02:00:19.1047332Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-09-28T02:00:18.2522997Z",
    "reason": "dkim_revoked",
    "smtp_response": "Next delivery time PT3.028008S > PT1S",
    "status_version": 1,
    "status": "failed",
    "previous_status": "sent",
    "complaint_status": "none"
  }
}

message.outcome_unknownCopiar enlace de la sección

Se dispara cuando MailLand no puede determinar si un mensaje llegó a su cola de entrega, por ejemplo porque la entrega a la cola se interrumpió y no pudo establecerse después. Se envía algún tiempo después del plazo de reintento del mensaje, actualmente 7 días, si para entonces no ha llegado ninguna prueba. No es un estado final. El estado pasa a unknown. Si MailLand conoce el resultado más tarde, recibes message.delivered, message.bounced o message.failed con una status_version mayor.

{
  "event": "message.outcome_unknown",
  "event_id": "evt_0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d",
  "timestamp": "2026-10-08T17:05:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-10-08T17:05:00.000Z",
    "status_version": 1,
    "status": "unknown",
    "previous_status": "queued",
    "complaint_status": "none",
    "reason": "handoff_undetermined"
  }
}

message.retriedCopiar enlace de la sección

Se dispara cuando reintentas un mensaje rebotado o fallido y MailLand lo vuelve a poner en cola. El estado pasa a queued y status_version aumenta; los eventos de la copia reintentada llegan después con versiones mayores. No es un estado final.

{
  "event": "message.retried",
  "event_id": "evt_1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e",
  "timestamp": "2026-10-01T18:00:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-10-01T18:00:00.000Z",
    "attempt": 1,
    "status_version": 2,
    "status": "queued",
    "previous_status": "bounced",
    "complaint_status": "none",
    "reason": null
  }
}

Eventos de interacciónCopiar enlace de la sección

message.openedCopiar enlace de la sección

Ilustrativo: no disponible.

{
  "event": "message.opened",
  "event_id": "evt_f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "timestamp": "2026-02-17T13:15:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T13:15:00.000Z"
  }
}

message.clickedCopiar enlace de la sección

Ilustrativo: no disponible.

{
  "event": "message.clicked",
  "event_id": "evt_g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1",
  "timestamp": "2026-02-17T13:16:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T13:16:00.000Z"
  }
}

message.unsubscribedCopiar enlace de la sección

Se emite cuando un destinatario se da de baja de un mensaje que enviaste: mediante su cabecera List-Unsubscribe o dirección mailto:, el POST de un clic, su enlace de baja o la página de preferencias. No se emite por las bajas que haces tú mismo desde la API o el panel, ni por quejas de spam (message.complained). Se envía una vez por mensaje, en el mismo momento en que se da de baja al destinatario, a cada endpoint suscrito a él. Como todo evento de mensaje, data incluye además los campos de estado actuales del mensaje (consulta Versiones de estado).

{
  "event": "message.unsubscribed",
  "event_id": "evt_h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2",
  "timestamp": "2026-02-17T14:00:00.000Z",
  "data": {
    "message_id": "m_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T14:00:00.000Z",
    "status_version": 3,
    "status": "delivered",
    "previous_status": "queued",
    "complaint_status": "none",
    "reason": null
  }
}

Eventos de supresiónCopiar enlace de la sección

message.complainedCopiar enlace de la sección

Se dispara cuando un destinatario marca el correo como spam (bucle de retroalimentación del ISP).

{
  "event": "message.complained",
  "event_id": "evt_i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3",
  "timestamp": "2026-02-17T15:00:00.000Z",
  "data": {
    "message_id": "m_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T15:00:00.000Z",
    "feedback_type": "abuse"
  }
}

suppression.addedCopiar enlace de la sección

Ilustrativo: aún no se emite. Este evento está catalogado pero hoy no tiene productor.

{
  "event": "suppression.added",
  "event_id": "evt_j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4",
  "timestamp": "2026-02-17T15:00:01.000Z",
  "data": {
    "email": "[email protected]",
    "type": "complaint",
    "scope": "global",
    "reason": "Spam complaint via ISP feedback loop"
  }
}

suppression.removedCopiar enlace de la sección

Ilustrativo: aún no se emite. Este evento está catalogado pero hoy no tiene productor.

{
  "event": "suppression.removed",
  "event_id": "evt_k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5",
  "timestamp": "2026-02-17T16:00:00.000Z",
  "data": {
    "email": "[email protected]",
    "type": "manual",
    "scope": "global"
  }
}

Eventos entrantesCopiar enlace de la sección

inbound.receivedCopiar enlace de la sección

Se dispara cuando se recibe un correo entrante en uno de tus dominios.

{
  "event": "inbound.received",
  "event_id": "evt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "timestamp": "2026-02-17T12:00:00.000Z",
  "occurred_at": "2026-02-17T12:00:00.000Z",
  "schema_version": 1,
  "data": {
    "idempotency_key": "r7n2k5x9m1p4w6_s5m3x8k1p7n4w2",
    "email": {
      "id": "r7n2k5x9m1p4w6",
      "received_at": "2026-02-17T12:00:00.000Z",
      "size_bytes": 4521,
      "envelope": {
        "from": "[email protected]",
        "to": ["[email protected]"]
      },
      "headers": {
        "from": { "address": "[email protected]", "name": "Jane Doe" },
        "to": [{ "address": "[email protected]" }],
        "subject": "Help with my order",
        "message_id": "<[email protected]>",
        "date": "2026-02-17T11:59:50.000Z"
      },
      "body": {
        "text_preview": "Hi, I need help with...",
        "has_text": true,
        "has_html": true
      },
      "attachments": [],
      "authentication": {
        "spf": { "result": "pass" },
        "dkim": { "result": "pass" },
        "dmarc": { "result": "pass" }
      },
      "spam": {
        "score": 0.1,
        "is_spam": false,
        "reason": null
      },
      "source": {
        "ip": "203.0.113.10",
        "hostname": "mail.external.com"
      }
    },
    "matched_route": {
      "id": "s5m3x8k1p7n4w2",
      "name": "Support inbox"
    }
  }
}

Eventos de cuentaCopiar enlace de la sección

account.webhook_pausedCopiar enlace de la sección

Se dispara cuando un webhook se pausa automáticamente por fallos consecutivos.

{
  "event": "account.webhook_paused",
  "event_id": "evt_m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7",
  "timestamp": "2026-02-17T18:00:00.000Z",
  "data": {
    "webhook_id": "z8m3p1k6x4w2n7",
    "webhook_name": "Production Events",
    "consecutive_failures": 10,
    "last_error": "Connection refused"
  }
}

account.domain_verifiedCopiar enlace de la sección

Ilustrativo: aún no se emite. Este evento está catalogado pero hoy no tiene productor.

{
  "event": "account.domain_verified",
  "event_id": "evt_n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8",
  "timestamp": "2026-02-17T10:15:00.000Z",
  "data": {
    "domain_id": "q3z8v1k6m9p2x5",
    "domain": "yourdomain.com"
  }
}

account.domain_failedCopiar enlace de la sección

Ilustrativo: aún no se emite. Este evento está catalogado pero hoy no tiene productor.

{
  "event": "account.domain_failed",
  "event_id": "evt_o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9",
  "timestamp": "2026-02-17T10:15:00.000Z",
  "data": {
    "domain_id": "q3z8v1k6m9p2x5",
    "domain": "yourdomain.com",
    "reason": "DKIM record not found for selector mlnd"
  }
}

account.quota_warningCopiar enlace de la sección

Ilustrativo: aún no se emite. Este evento está catalogado pero hoy no tiene productor.

{
  "event": "account.quota_warning",
  "event_id": "evt_p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0",
  "timestamp": "2026-02-17T20:00:00.000Z",
  "data": {
    "used": 45000,
    "limit": 50000,
    "percentage": 90
  }
}

account.quota_exceededCopiar enlace de la sección

Ilustrativo: aún no se emite. Este evento está catalogado pero hoy no tiene productor.

{
  "event": "account.quota_exceeded",
  "event_id": "evt_q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1",
  "timestamp": "2026-02-17T22:00:00.000Z",
  "data": {
    "used": 50000,
    "limit": 50000,
    "percentage": 100
  }
}

Resumen de eventosCopiar enlace de la sección

"Disponible" es el indicador availableNow del catálogo: si algo emite hoy realmente el evento. Solo los eventos disponibles pueden incluirse en una suscripción.

Eventos futurosCopiar enlace de la sección

Cuando includeFutureEvents es true (valor por defecto), tu webhook recibe automáticamente los nuevos tipos de eventos a medida que se añaden a tus productos suscritos. Ponlo en false para fijar tu suscripción al conjunto actual de eventos.

Los eventos marcados como "Aún no" arriba se vuelven suscribibles cuando sus productores se publiquen: los nombres de eventos y las estructuras de datos documentadas aquí no cambiarán en ese momento.

Próximos pasosCopiar enlace de la sección

• Verificación de firma: verifica que los eventos provienen de MailLand
• Lógica de reintentos: entiende el comportamiento de reintento
• Resumen de webhooks: crea y gestiona webhooks