Rutas de Entrada

Las rutas definen cómo MailLand gestiona los correos entrantes de un dominio. Cada ruta coincide con la parte local del destinatario (la parte de la dirección antes de @) y ejecuta una o más acciones: almacenar, entregar a un webhook, reenviar, rechazar en SMTP o descartar. Las rutas se evalúan en orden de prioridad (el número más bajo primero) y la primera coincidencia gana.

Tipos de coincidenciaCopiar enlace de la sección

La coincidencia no distingue mayúsculas de minúsculas y siempre se evalúa contra la parte local, [email protected] y [email protected] coinciden ambos con una ruta con patrón support limitada al mismo dominio.

Acciones de rutaCopiar enlace de la sección

El campo actions de una ruta es una lista de uno o más de los siguientes valores de cadena:

store y webhook pueden combinarse entre sí y con forward. reject, drop y unsubscribe son terminales: cada una debe ser la única acción de la ruta; la API rechaza una solicitud que combine una de ellas con cualquier otra acción.

Destinos de reenvíoCopiar enlace de la sección

Antes de reenviar cualquier correo a una dirección, el propietario de esa dirección debe confirmarlo: excepto si la dirección está en uno de sus propios dominios totalmente verificados para envío. Para una dirección externa no hay forma de evitarlo: protege al propietario del destino de recibir correo que nunca aceptó, y protege su reputación de envío de una dirección que rebota o se queja.

Al crear o actualizar una ruta con forward en actions, MailLand automáticamente:

1. Crea (o reutiliza) un registro de destino de reenvío para forwardToEmail, con alcance a su tenant: la misma dirección se recuerda en todas las rutas que reenvían a ella.
2. Si la dirección necesita confirmación y nunca se le ha preguntado, envía un correo de confirmación con un enlace.

El guardado de la ruta en sí siempre tiene éxito; un correo de confirmación fallido no hace fallar la ruta: el destino simplemente queda pending (no se reenvía nada) hasta que reenvíe la confirmación.

Enlace de confirmaciónCopiar enlace de la sección

El enlace del correo de confirmación es válido durante 7 días y es de un solo uso: una vez que el destinatario confirma o rechaza, visitar el enlace de nuevo solo muestra la misma decisión, no se puede revertir volviendo a visitarlo. Un enlace expirado que nunca se decidió devuelve 410 Gone si se abre de nuevo.

• Confirmar: el correo reenviado a este tenant ahora se enviará a la dirección.
• Rechazar: definitivo. Nunca se vuelve a reenviar nada a la dirección para este tenant, y el tenant no puede volver a solicitar confirmación para ella.

Obtener un destino de reenvíoCopiar enlace de la sección

GET https://api.mail.land/v1/transactional/inbound/forward-destinations/{destinationId}

{
  "id": "f2k9m3q7p4w8x1",
  "email": "[email protected]",
  "status": "pending",
  "confirmedVia": null,
  "lastSentAt": "2026-09-26T10:00:00Z",
  "confirmedAt": null,
  "declinedAt": null
}

status es uno de pending, confirmed o declined. confirmedVia es link cuando el propietario confirmó por correo, verified_domain cuando la dirección está en uno de sus propios dominios verificados para envío y no necesitó confirmación, o null en otro caso. La respuesta de una ruta también incluye este mismo objeto bajo forwardDestination (ver la respuesta de ruta más abajo).

Reenviar una confirmaciónCopiar enlace de la sección

POST https://api.mail.land/v1/transactional/inbound/forward-destinations/{destinationId}/resend

Solo para un destino que sigue pending y realmente necesita un enlace (una dirección en uno de sus propios dominios de envío verificados devuelve 409 FORWARD_DESTINATION_NO_CONFIRMATION_NEEDED, ya que no hay nada que reenviar). Con límite de frecuencia: como máximo una vez cada 5 minutos y 5 veces al día por destino, y 50 veces al día para todo el tenant. Superar cualquiera de los límites devuelve 429 FORWARD_CONFIRMATION_RATE_LIMITED.

Crear una rutaCopiar enlace de la sección

Las rutas pertenecen a un dominio y se crean bajo ese dominio.

POST https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes

{
  "name": "Support Inbox",
  "matchType": "exact",
  "matchPattern": "support",
  "actions": ["store", "webhook"],
  "webhookId": "w4k8m2q7p9x3z1",
  "priority": 10
}

curl -X POST https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Inbox",
    "matchType": "exact",
    "matchPattern": "support",
    "actions": ["store", "webhook"],
    "webhookId": "w4k8m2q7p9x3z1",
    "priority": 10
  }'

RespuestaCopiar enlace de la sección

{
  "id": "r7k3m9q2p4w8x1",
  "name": "Support Inbox",
  "domainId": "k3v9x2m8q1w7z4",
  "domainName": "yourdomain.com",
  "priority": 10,
  "isEnabled": true,
  "matchType": "Exact",
  "matchPattern": "support",
  "actions": ["store", "webhook"],
  "webhookId": "w4k8m2q7p9x3z1",
  "webhookName": "Support Webhook",
  "webhookUrl": "https://yourapp.com/webhooks/support",
  "forwardToEmail": null,
  "forwardDestination": null,
  "rejectStatus": null,
  "rejectMessage": null,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

Las solicitudes aceptan matchType en cualquier combinación de mayúsculas/minúsculas; las respuestas siempre devuelven el nombre del enum capitalizado: Exact, Prefix, Suffix, Contains, PlusAddressing, CatchAll, Regex. No compare el matchType de una respuesta con una cadena en minúsculas.

forwardDestination solo se completa cuando actions incluye forward; incluye el mismo objeto descrito en Obtener un destino de reenvío:

{
  "...": "...",
  "actions": ["store", "forward"],
  "forwardToEmail": "[email protected]",
  "forwardDestination": {
    "id": "f2k9m3q7p4w8x1",
    "email": "[email protected]",
    "status": "pending",
    "confirmedVia": null,
    "lastSentAt": "2026-09-26T10:00:00Z",
    "confirmedAt": null,
    "declinedAt": null
  }
}

Listar rutas de un dominioCopiar enlace de la sección

GET https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes

Devuelve todas las rutas del dominio, ordenadas por prioridad (la más baja primero).

curl https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "items": [
    { "id": "r7k3m9q2p4w8x1", "name": "Support Inbox", "priority": 10, "isEnabled": true, "..." : "..." }
  ],
  "totalCount": 1
}

Listar todas las rutasCopiar enlace de la sección

Para listar rutas de todos los dominios del tenant, use en su lugar el endpoint paginado por cursor:

GET https://api.mail.land/v1/transactional/inbound/routes

Obtener detalles de una rutaCopiar enlace de la sección

GET https://api.mail.land/v1/transactional/inbound/routes/{routeId}

curl https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Actualizar una rutaCopiar enlace de la sección

PUT https://api.mail.land/v1/transactional/inbound/routes/{routeId}

El cuerpo de la solicitud coincide con el de creación, pero todos los campos son opcionales: solo se actualizan los campos que envíe.

curl -X PUT https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "matchPattern": "help",
    "priority": 5
  }'

Activar o desactivar una rutaCopiar enlace de la sección

Cambia isEnabled sin tocar ningún otro campo. Sin cuerpo de solicitud.

POST https://api.mail.land/v1/transactional/inbound/routes/{routeId}/toggle

curl -X POST https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1/toggle \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Reordenar rutasCopiar enlace de la sección

Actualiza la prioridad de todas las rutas de un dominio a la vez, pasando los IDs de ruta en el orden deseado: el primer ID pasa a prioridad 1, el segundo a prioridad 2, y así sucesivamente.

POST https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes/reorder

{
  "routeIds": ["r7k3m9q2p4w8x1", "m2p8w4x1k7q3z9", "x4k1p7m3q9w2z8"]
}

curl -X POST https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes/reorder \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "routeIds": ["r7k3m9q2p4w8x1", "m2p8w4x1k7q3z9", "x4k1p7m3q9w2z8"]
  }'

Probar una rutaCopiar enlace de la sección

Compruebe qué ruta coincidiría con una dirección de destinatario dada sin procesar un correo.

POST https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes/test

{
  "emailAddress": "[email protected]"
}

curl -X POST https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "[email protected]"
  }'

{
  "matched": true,
  "matchedRouteId": "r7k3m9q2p4w8x1",
  "matchedRouteName": "Support Inbox",
  "actions": ["store", "webhook"]
}

Si ninguna ruta coincide, la respuesta es 200 con matched: false, y matchedRouteId/matchedRouteName/actions son todos null. 404 significa que el dominio no se encontró, o que la dirección probada no es válida (sin @).

Eliminar una rutaCopiar enlace de la sección

DELETE https://api.mail.land/v1/transactional/inbound/routes/{routeId}

curl -X DELETE https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Ejemplos de rutasCopiar enlace de la sección

Ruta catch-all: almacenar todo destinatario no reconocido:

{
  "name": "Catch All",
  "matchType": "catchall",
  "matchPattern": "*",
  "actions": ["store"],
  "priority": 999
}

Direccionamiento plus: enrutar todas las variantes de support+*@yourdomain.com a un webhook:

{
  "name": "Support Tickets",
  "matchType": "plusaddressing",
  "matchPattern": "support",
  "actions": ["store", "webhook"],
  "webhookId": "w4k8m2q7p9x3z1",
  "priority": 5
}

Rechazo en SMTP: rechazar correo a un buzón retirado antes de que sea aceptado:

{
  "name": "Retired Mailbox",
  "matchType": "exact",
  "matchPattern": "old-team",
  "actions": ["reject"],
  "rejectStatus": "550 5.1.1",
  "rejectMessage": "Mailbox does not exist",
  "priority": 1
}

Cómo es una copia reenviadaCopiar enlace de la sección

Una copia reenviada es un correo transaccional nuevo y normal, no una retransmisión en bruto de los bytes originales, enviado desde su dominio verificado para que pueda pasar DKIM y DMARC en el buzón del destino:

• From: "<nombre del remitente original> via <dirección coincidente>@<su dominio>", p. ej. "Jane Doe via [email protected]". Un nombre de visualización que parece una dirección (contiene @, < o >) se reemplaza por la dirección original simple, para que una copia nunca pueda suplantar una marca bajo su DKIM.
• Reply-To: el Reply-To del mensaje original si lo tenía, si no la dirección del remitente original, para que las respuestas lleguen al autor real, no a usted.
• Sin seguimiento: el seguimiento de apertura y clics siempre está desactivado en una copia reenviada, sean cuales sean los ajustes de seguimiento de su workspace.
• Sin pie de marca: el pie de página del plan gratuito que pueden llevar otros envíos nunca se añade.
• Adjuntos: filtrados con las mismas reglas que un envío saliente por API (tipo, cantidad, tamaño total). Lo que se omite se indica con una nota al principio de la copia: "Forwarded without N attachment(s) that exceed the outbound attachment limits: ...", la copia igual llega, solo sin esas partes.
• Etiqueta: cada copia reenviada lleva la etiqueta inbound-forward, para que pueda encontrarlas en su registro de mensajes habitual; su estado de entrega (queued, sent, delivered, bounced, etc.) es el mismo estado que recibe cualquier otro envío transaccional, porque pasa por la misma canalización de entrega.
• Uso: cada copia reenviada cuenta como un envío contra la cuota y facturación de su plan, y se muestra como su propia línea "Inbound forward" en el uso, separada de los envíos por API, SMTP, campañas y automatizaciones.

Lo que nunca se reenvíaCopiar enlace de la sección

Un mensaje que coincide con una ruta forward no se reenvía, y nunca se factura, cuando:

• Se marcó como spam, o el remitente está bloqueado como spam.
• Falló DMARC según la política efectiva del dominio remitente, que es quarantine o reject, resuelta subiendo desde el dominio del remitente hasta encontrar el registro aplicable más cercano, de modo que el sp= propio de un subdominio prevalece sobre el p= de su dominio organizacional, y un registro t=y (de prueba) o pct=0 se trata un nivel de política por debajo, reenviarlo volvería a firmar un mensaje que el remitente pidió explícitamente a los receptores rechazar.
• Él, o su cuerpo HTML/texto, supera los límites de tamaño de salida de la plataforma.
• Reenviarlo crearía un bucle: el destino es uno de los propios destinatarios del mensaje, o ya lleva demasiados saltos o cabeceras Received.

Una copia que es elegible pero no se puede enviar temporalmente (una pausa de política, una ventana de cuota, una interrupción) se reintenta con espera creciente hasta 24 horas, y luego expira sin enviarse. Una ruta que se deshabilita, se elimina o cambia su destino después de recibir un mensaje también detiene cualquier copia que aún esperaba: la configuración actual de la ruta siempre es la autoridad.

Comprobar el resultado de un reenvíoCopiar enlace de la sección

Todo correo entrante que coincidió con una ruta forward lleva un array forwards en su respuesta de detalle (GET /v1/transactional/inbound/emails/{id}): una entrada por cada destino al que el mensaje se puso en cola para reenviar, para que veas lo que realmente ocurrió, no solo a dónde se configuró.

"forwards": [
  {
    "destination": "[email protected]",
    "status": "Admitted",
    "reason": null,
    "omittedAttachmentCount": 0,
    "messageId": "m_01hz3k...",
    "createdAt": "2026-09-26T10:00:00Z",
    "updatedAt": "2026-09-26T10:00:02Z"
  }
]

status es uno de:

Pending, Processing y Deferred son los únicos estados no finales, cualquier otro valor es terminal.

Respuestas de error de reenvíoCopiar enlace de la sección

Respuestas de errorCopiar enlace de la sección

Próximos pasosCopiar enlace de la sección

• Inbound Overview: cómo funciona el procesamiento de correo entrante
• Inbound Webhooks: formato de payload y entrega de webhooks
• Domains: configurar registros MX para correo entrante