Webhooks de entrada

Cuando un correo entrante coincide con una ruta cuyas actions incluyen webhook, MailLand envía el correo procesado al webhook de esa ruta como una solicitud POST en JSON. Esta página cubre el formato del payload, la verificación de firma y el comportamiento de entrega.

Payload del webhookCopiar enlace de la sección

MailLand envía una solicitud POST a su URL de webhook con el siguiente cuerpo JSON:

{
  "event": "inbound.received",
  "event_id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "timestamp": "2026-02-17T14:30:00Z",
  "occurred_at": "2026-02-17T14:29:58Z",
  "schema_version": 1,
  "data": {
    "idempotency_key": "k7m2x9q4p1w8z3_r7k3m9q2p4w8x1",
    "email": {
      "id": "k7m2x9q4p1w8z3",
      "received_at": "2026-02-17T14:29:58Z",
      "size_bytes": 48213,
      "envelope": {
        "from": "[email protected]",
        "to": ["[email protected]"]
      },
      "headers": {
        "from": { "address": "[email protected]", "name": "Jane Customer" },
        "to": [{ "address": "[email protected]", "name": null }],
        "cc": [],
        "subject": "Need help with my account",
        "message_id": "<[email protected]>",
        "in_reply_to": null,
        "reply_to": "[email protected]",
        "date": "2026-02-17T14:29:55Z"
      },
      "body": {
        "text_preview": "I need assistance with my account settings.",
        "has_text": true,
        "has_html": true
      },
      "attachments": [
        {
          "id": "a3k7m2q9p4w1x8",
          "file_name": "screenshot.png",
          "content_type": "image/png",
          "size_bytes": 34500,
          "is_inline": false,
          "content_id": null,
          "download_url": "https://r2.example.com/screenshot.png?X-Amz-Signature=..."
        }
      ],
      "authentication": {
        "spf": { "result": "pass" },
        "dkim": { "result": "pass" },
        "dmarc": { "result": "pass" }
      },
      "spam": {
        "score": 1.2,
        "is_spam": false,
        "reason": null
      },
      "source": {
        "ip": "203.0.113.42",
        "hostname": "mail.example.com"
      }
    },
    "matched_route": {
      "id": "r7k3m9q2p4w8x1",
      "name": "Support Inbox"
    }
  }
}

El cuerpo completo del correo nunca se incluye en línea: solo una vista previa truncada en text_preview y los indicadores has_text/has_html. No existe el campo body.html.

Los campos sin valor (name, in_reply_to, content_id, reason, data.matched_route, etc.) se omiten por completo del JSON en lugar de enviarse como null. El ejemplo anterior muestra null por claridad; no dependa de que la clave esté presente.

Campos del payloadCopiar enlace de la sección

AdjuntosCopiar enlace de la sección

El contenido de los adjuntos nunca se incluye en línea. Cada entrada en data.email.attachments lleva un download_url:

GET https://api.mail.land/v1/transactional/inbound/emails/{emailId}/raw

Verificación de firmaCopiar enlace de la sección

Los webhooks de entrada se firman exactamente igual que cualquier otro webhook de MailLand: mismo encabezado, mismo esquema, mismo manejo del secreto. La referencia canónica, con un ejemplo completo y código verificador en ocho lenguajes, es Signature Verification; todo lo indicado allí aplica aquí sin cambios.

En resumen:

X-MLND-Signature: t=1708171200,v1=<hex>

• t es una marca de tiempo Unix en segundos, v1 es un HMAC-SHA256 en hexadecimal minúscula;
• la cadena firmada es {timestamp}.{raw_body}: la marca de tiempo, un punto literal, y luego el cuerpo exactamente como se recibió, antes del análisis JSON;
• la clave es el secreto de firma del webhook, mostrado una sola vez al crearlo;
• compare en tiempo constante y rechace una marca de tiempo con más de 300 segundos de antigüedad.

Comportamiento de entregaCopiar enlace de la sección

Códigos de respuestaCopiar enlace de la sección

Su endpoint debe responder con un código de estado 2xx para confirmar la recepción. Cualquier otra cosa, un estado que no sea 2xx o un tiempo de espera agotado, cuenta como un intento de entrega fallido.

Política de reintentosCopiar enlace de la sección

Un intento fallido se reintenta con el mismo calendario que cualquier otro evento de webhook, hasta un total de 6 intentos por evento: el primer intento y luego reintentos de inmediato, a 1 minuto, 5 minutos, 15 minutos y 1 hora. Después del 6.º intento fallido, la entrega se marca como fallida permanentemente. Puede reenviarla manualmente. Consulte Lógica de reintentos para el calendario completo.

Reenviar un webhookCopiar enlace de la sección

Vuelva a entregar el webhook de un correo entrante específico:

POST https://api.mail.land/v1/transactional/inbound/emails/{id}/replay-webhook

curl -X POST https://api.mail.land/v1/transactional/inbound/emails/k7m2x9q4p1w8z3/replay-webhook \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "emailId": "k7m2x9q4p1w8z3",
  "queued": true,
  "webhookUrl": "https://yourapp.com/webhooks/support",
  "message": "Webhook replay queued successfully"
}

Esto pone en cola una entrega duradera al webhook de la ruta coincidente y devuelve 202 Accepted una vez confirmada esa fila; no envía de forma síncrona. La reproducción recibe un ID de evento nuevo (un event_id y un X-MLND-Event-Id nuevos) y lleva el ID de la entrega original en data.replay_of, de modo que su deduplicación la trata como un evento nuevo y aun así puede vincularla con el original. data.idempotency_key se mantiene igual que en la entrega original. La solicitud incluye X-MLND-Source: inbound y X-MLND-Inbound-Email-Id, y cualquier download_url de adjunto en el payload se firma en el momento del envío: es válida durante 15 minutos desde entonces, no desde que llamó a la reproducción.

Deduplicar eventosCopiar enlace de la sección

La entrega de webhooks entrantes es al menos una vez (at-least-once): un reintento, un timeout de su lado después de haber procesado ya la solicitud o un traspaso entre workers puede entregar el mismo evento más de una vez. Los receptores deben deduplicar.

• Todo webhook entrante lleva un ID de evento estable en event_id y en el encabezado X-MLND-Event-Id. Es determinista por mensaje entrante y webhook, así que todos los intentos de entrega del mismo mensaje al mismo webhook tienen el mismo ID.
• Deduplique por ese ID. Guarde los IDs procesados y omita cualquier ID ya visto.
• Una reproducción manual es un evento nuevo. Tiene un event_id nuevo y un campo data.replay_of con el ID original. Si quiere que se ignore una reproducción cuando el original ya se procesó, compare también data.replay_of con sus IDs almacenados.

app.post("/webhooks/support", express.raw({ type: "application/json" }), async (req, res) => {
  // 1. Verify X-MLND-Signature first (see Signature Verification).
  const eventId = req.header("X-MLND-Event-Id");
  const client = await db.connect();
  try {
    await client.query("BEGIN");
    // 2. Record the event id; the unique constraint makes this atomic.
    const inserted = await client.query(
      "INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT (event_id) DO NOTHING",
      [eventId],
    );
    // 3. Only a first-time id enqueues work, in the SAME transaction (jobs table).
    if (inserted.rowCount > 0) {
      await client.query("INSERT INTO jobs (kind, payload) VALUES ($1, $2)", [
        "process-inbound-email",
        req.body.toString(),
      ]);
    }
    await client.query("COMMIT");
    res.sendStatus(200); // new or duplicate: acknowledge
  } catch (err) {
    await client.query("ROLLBACK"); // id and job are both undone, so the retry is not a "duplicate"
    res.sendStatus(500);
  } finally {
    client.release();
  }
});

Registrar el ID y encolar el trabajo en una sola transacción es importante: si el ID se guardara primero y el encolado fallara, el reintento de MailLand se omitiría como duplicado y el correo se perdería.

Conserve los IDs procesados al menos tanto como su ventana de reintentos más larga, más cualquier reproducción que pueda lanzar.

Encabezados del webhookCopiar enlace de la sección

Cada solicitud de webhook incluye estos encabezados:

Buenas prácticasCopiar enlace de la sección

• Responda rápido: confirme el webhook con 200 de inmediato y procese el correo de forma asíncrona en un trabajo en segundo plano.
• Verifique las firmas: valide siempre el encabezado X-MLND-Signature para evitar payloads falsificados.
• Gestione los duplicados: la entrega es al menos una vez, así que deduplique por X-MLND-Event-Id (el event_id del payload). Una reproducción manual tiene un ID nuevo y data.replay_of apunta al original; consulte Deduplicar eventos.
• Descargue los adjuntos de inmediato: cada download_url expira 15 minutos después de generarse el payload; después de eso, obtenga el mensaje original.
• Use HTTPS: las URLs de webhook deben usar HTTPS en producción para una entrega segura del payload.

Respuestas de errorCopiar enlace de la sección

Próximos pasosCopiar enlace de la sección

• Inbound Overview: configurar los ajustes de entrada y ver los correos
• Inbound Routes: configurar reglas de enrutamiento para la entrega de webhooks
• Webhooks: configuración de webhooks salientes para eventos de correo