Webhooks y eventos
Los resultados de entrega, en su propia aplicación
Mail.Land envía un evento firmado a su endpoint cuando un mensaje se entrega, se aplaza, rebota o termina en fallo, cuando un destinatario presenta una queja y cuando llega correo entrante, con un registro de cada intento.
import crypto from "node:crypto";
// header: X-MLND-Signature: t=1708171200,v1=<hex>
export function verify(rawBody, header, secret) {
if (typeof header !== "string" || header === "") return false;
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const age = Math.abs(Date.now() / 1000 - Number(parts.t));
if (!parts.t || !parts.v1 || age > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Eventos a los que puede suscribirse hoy
Hay ocho tipos de evento activos. Suscríbase a todos o solo a los que necesite.
| Se envía cuando | |
|---|---|
| message.delivered | El servidor de correo del destinatario aceptó el mensaje |
| message.deferred | La entrega se retrasó por ahora; Mail.Land sigue intentándolo |
| message.bounced | El servidor del destinatario rechazó el mensaje, con el tipo de rebote y su respuesta |
| message.failed | Mail.Land marcó el mensaje como fallido por un motivo interno o de política; este evento no suprime al destinatario |
| message.complained | El destinatario marcó el mensaje como spam mediante un circuito de retroalimentación |
| message.outcome_unknown | Mail.Land aún no pudo saber si el mensaje llegó a su cola de entrega; llega un evento final si Mail.Land conoce el resultado más tarde |
| message.retried | Usted reintentó un mensaje rebotado o fallido y vuelve a estar en cola |
| inbound.received | Llegó un correo a uno de sus dominios y coincidió con una ruta de webhook |
Otros tipos de evento, como message.sent, aperturas y clics, figuran en el catálogo para el futuro y aún no se envían. El endpoint del catálogo indica cuáles están disponibles ahora.
Firmado, y enviado solo a donde debe ir
Cada solicitud se puede verificar, y Mail.Land rechaza destinos que podrían usarse de forma abusiva.
HMAC-SHA256 con marca de tiempo
El encabezado X-MLND-Signature contiene una marca de tiempo y la firma de esa marca más el cuerpo original. Compruébela en tiempo constante y rechace las marcas antiguas para bloquear repeticiones.
Solo HTTPS en el puerto 443
Se rechazan las direcciones privadas y de loopback. Las redirecciones se siguen como máximo tres saltos, y cada salto se vuelve a comprobar antes de enviarle nada.
Un secreto por webhook
El secreto de firma se muestra una sola vez al crear el webhook. Si se filtra, genere uno nuevo: el anterior deja de funcionar de inmediato.
Cuando su endpoint no responde
Por defecto, una entrega fallida se reintenta con este calendario. Una respuesta 2xx en 15 segundos cuenta como éxito.
| Espera antes del intento | Tiempo desde el primer intento | |
|---|---|---|
| Intento 1 | Ninguna | 0 |
| Intento 2 | Inmediato | Aprox. 0 |
| Intento 3 | 1 minuto | Aprox. 1 minuto |
| Intento 4 | 5 minutos | Aprox. 6 minutos |
| Intento 5 | 15 minutos | Aprox. 21 minutos |
| Intento 6 | 1 hora | Aprox. 1 hora y 21 minutos |
Se reintentan los tiempos de espera agotados, los errores de red y las respuestas 408, 429, 500, 502, 503 y 504, y un encabezado Retry-After fija la siguiente espera. Las demás respuestas fuera de 2xx son definitivas. Puede reintentar cualquier entrega fallida desde el registro.
Pensado para eventos que llegan tarde o dos veces
La entrega es al menos una vez y no siempre en orden. Cada evento trae lo necesario para gestionarlo.
Versiones de estado
Cada evento de mensaje lleva una versión de estado que sube con cada cambio. Si se suscribe a todos los eventos de mensaje y aplica un evento solo cuando su versión es mayor que la guardada, su estado será correcto sea cual sea el orden de llegada. Con menos eventos, consulte el estado actual mediante la API.
ID de evento estables
El ID de evento es el mismo en cada reintento de un evento. Guarde los ID procesados y omita las repeticiones.
Cargas versionadas
Cada tipo de evento tiene una versión de esquema. Mail.Land solo añade campos y encabezados a una versión existente, de modo que un receptor que ignora los campos desconocidos sigue funcionando.
Control y visibilidad
Gestione los webhooks en el panel o mediante la API.
Filtre por producto y dominio
Elija eventos transaccionales, de marketing o de entrada, tipos de evento concretos y todos los dominios o solo algunos.
Pruebe antes de depender de él
Envíe un evento de prueba con la firma y el transporte reales. La respuesta también le indica si los eventos reales pueden llegar al endpoint con su suscripción actual.
Registro de entregas
Vea cada intento con su estado, filtre los fallidos y reintente una entrega manualmente.
Pausa automática
Por defecto, tras 10 intentos fallidos seguidos el webhook se pausa y usted recibe un aviso en el panel. Reactívelo cuando su endpoint vuelva a funcionar.
Preguntas sobre webhooks
¿Hay un evento cuando un mensaje se acepta o se envía?
Todavía no. message.sent figura en el catálogo pero hoy no se envía. La respuesta de la API a su solicitud de envío incluye los ID de mensaje, y el primer evento de webhook que recibe es el resultado de la entrega.
¿Puedo recibir eventos de apertura y clic?
Hoy no por webhook. Las aperturas y los clics, donde el seguimiento está activo, aparecen en sus registros y analíticas; los eventos de apertura y clic están en el catálogo para más adelante.
¿Y si un mensaje entregado rebota después?
Puede ocurrir: un servidor receptor puede rechazar un mensaje después de aceptarlo. Mail.Land envía entonces un evento de rebote con una versión de estado mayor, así que siga procesando eventos tras uno de entrega.
¿Qué pasa si mi endpoint cae durante un día?
Por defecto, cada evento se intenta hasta seis veces durante unos 80 minutos, y el webhook se pausa tras 10 intentos fallidos seguidos. Mientras está pausado, no se ponen en cola eventos nuevos para él. Cuando lo reactive, reintente las entregas fallidas desde el registro, consulte el estado de los mensajes mediante la API y reenvíe los mensajes entrantes que se perdió.
¿Cómo verifico que una solicitud viene de Mail.Land?
Calcule HMAC-SHA256 sobre la marca de tiempo, un punto y el cuerpo original con el secreto del webhook, compárelo en tiempo constante con el valor v1 y rechace las marcas de más de 5 minutos. La documentación incluye un ejemplo con valores exactos.
¿Puede un endpoint recibir eventos solo de algunos de mis dominios?
Sí. Configure el alcance del webhook en dominios seleccionados y enumérelos; entonces solo recibirá eventos de esos dominios.
Conecte su aplicación a cada resultado de entrega
Cree una cuenta gratuita, añada un endpoint y envíele un evento de prueba.