Inbound Routes

Routes define how MailLand handles incoming emails for a domain. Each route matches on the recipient's local part (the part of the address before @) and runs one or more actions: store, deliver to a webhook, forward, reject at SMTP, or drop. Routes are evaluated in priority order (lowest number first) and the first match wins.

Match TypesCopy Anchor Link

Matching is case-insensitive and always runs against the local part, [email protected] and [email protected] both match a route with pattern support scoped to the same domain.

Route ActionsCopy Anchor Link

A route's actions field is a list of one or more of the following string values:

store and webhook can be combined with each other and with forward. reject, drop, and unsubscribe are terminal: each must be the only action on the route; the API rejects a request that combines one of them with any other action.

Forward DestinationsCopy Anchor Link

Before any mail is forwarded to an address, that address's owner must confirm they want it: unless the address is on one of your own domains that is fully verified for sending. There is no way around this for an outside address: it protects the destination's owner from receiving mail they never agreed to, and it protects your sending reputation from an address that bounces or complains.

When you create or update a route with forward in actions, MailLand automatically:

1. Creates (or reuses) a forward-destination record for forwardToEmail, scoped to your tenant: the same address is remembered across every route that forwards to it.
2. If the address needs confirmation and has never been asked, sends it a confirmation email containing a link.

The route save itself always succeeds; a failed confirmation email does not fail the route: the destination simply stays pending (nothing is forwarded to it) until you resend the confirmation.

Confirmation LinkCopy Anchor Link

The link in the confirmation email is valid for 7 days and is single-use: once the recipient confirms or declines, visiting the link again just shows the same decision, it cannot be reversed by revisiting it. An expired, never-decided link returns 410 Gone if opened again.

• Confirm: mail forwarded to this tenant will now be sent to the address.
• Decline: final. Nothing is ever forwarded to the address for this tenant again, and the tenant cannot request confirmation again for it.

Get a Forward DestinationCopy Anchor Link

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 is one of pending, confirmed or declined. confirmedVia is link when the owner confirmed through the email, verified_domain when the address is on one of your own sending-verified domains and needed no confirmation, or null otherwise. A route's own response also carries this same object under forwardDestination (see the route response below).

Resend a ConfirmationCopy Anchor Link

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

Only for a destination that is still pending and does need a link (an address on one of your own verified sending domains returns 409 FORWARD_DESTINATION_NO_CONFIRMATION_NEEDED, since there is nothing to resend). Rate-limited: at most once every 5 minutes and 5 times a day per destination, and 50 times a day across the whole tenant. Exceeding either limit returns 429 FORWARD_CONFIRMATION_RATE_LIMITED.

Create a RouteCopy Anchor Link

Routes belong to a domain and are created under that domain.

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
  }'

ResponseCopy Anchor Link

{
  "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"
}

Requests accept matchType in any case; responses always return the enum name capitalized: Exact, Prefix, Suffix, Contains, PlusAddressing, CatchAll, Regex. Do not compare a response's matchType against a lowercase string.

forwardDestination is only populated when actions includes forward; it carries the same object described in Get a Forward Destination:

{
  "...": "...",
  "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
  }
}

List Routes for a DomainCopy Anchor Link

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

Returns every route for the domain, sorted by priority (lowest first).

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
}

List All RoutesCopy Anchor Link

To list routes across every domain in the tenant, use the cursor-paginated endpoint instead:

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

Get Route DetailsCopy Anchor Link

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

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

Update a RouteCopy Anchor Link

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

The request body matches the create request, but every field is optional: only the fields you send are updated.

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
  }'

Toggle a RouteCopy Anchor Link

Flips isEnabled without touching any other field. No request body.

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..."

Reorder RoutesCopy Anchor Link

Update the priority of every route in a domain at once, by passing the route IDs in the desired order: the first ID becomes priority 1, the second priority 2, and so on.

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"]
  }'

Test a RouteCopy Anchor Link

Check which route would match a given recipient address without processing an email.

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"]
}

If no route matches, the response is 200 with matched: false and matchedRouteId/ matchedRouteName/actions all null. 404 means the domain was not found, or the tested address is invalid (no @).

Delete a RouteCopy Anchor Link

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..."

Route ExamplesCopy Anchor Link

Catch-all route: store every unmatched recipient:

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

Plus-addressing: route all support+*@yourdomain.com variants to one webhook:

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

Reject at SMTP: refuse mail to a retired mailbox before it is accepted:

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

What a Forwarded Copy Looks LikeCopy Anchor Link

A forwarded copy is a new, ordinary transactional email, not a raw relay of the original bytes, sent from your verified domain so it can pass DKIM and DMARC at the destination's mailbox provider:

• From: "<original sender name> via <matched address>@<your domain>", e.g. "Jane Doe via [email protected]". A display name that looks like an address (contains @, < or >) is replaced with the bare original address, so a copy can never impersonate a brand under your DKIM.
• Reply-To: the original message's Reply-To if it had one, otherwise the original sender's address, so replies reach the real author, not you.
• No tracking: open and click tracking are always off on a forwarded copy, whatever your workspace's tracking settings are.
• No branding footer: the Free-plan footer that other sends may carry is never added.
• Attachments: filtered through the same rules as an outbound API send (type, count, total size). Anything left out is noted at the top of the copy: "Forwarded without N attachment(s) that exceed the outbound attachment limits: ...", the copy still arrives, just without those parts.
• Tag: every forwarded copy carries the tag inbound-forward, so you can find them in your regular message log; its delivery status (queued, sent, delivered, bounced, etc.) is the same status any other transactional send gets, because it goes through the same delivery pipeline.
• Usage: each forwarded copy counts as one send against your plan's quota and billing, shown as its own "Inbound forward" line in usage, separate from API, SMTP, campaign and automation sends.

What Is Never ForwardedCopy Anchor Link

A message matching a forward route is not forwarded, and never billed, when:

• It was flagged as spam, or the sender is blocklisted as spam.
• It failed DMARC under the sender domain's effective policy of quarantine or reject, resolved by walking up from the author domain to find the nearest applicable record, so a subdomain's own sp= overrides its organizational domain's p=, and a t=y (testing) or pct=0 record is treated one policy level lower, forwarding it would re-sign a message the sender explicitly asked receivers to refuse.
• It, or its HTML/text body, is over the platform's outbound size limits.
• Forwarding it would create a loop: the destination is one of the message's own recipients, or it already carries too many hops or Received headers.

A copy that is eligible but temporarily can't be sent (a policy delay, a quota window, an outage) is retried with back-off for up to 24 hours, then expires without being sent. A route that is disabled, deleted, or has its destination changed after a message was received also stops any copy still waiting for it: the current route configuration is always authoritative.

Checking a Forward's OutcomeCopy Anchor Link

Every inbound email that matched a forward route carries a forwards array on its detail response (GET /v1/transactional/inbound/emails/{id}): one entry per destination the message was queued to forward to, so you can see what actually happened, not just where it was configured to go:

"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 is one of:

Pending, Processing and Deferred are the only non-final statuses, every other value is terminal.

Forward Error ResponsesCopy Anchor Link

Error ResponsesCopy Anchor Link

Next StepsCopy Anchor Link

• Inbound Overview: how inbound email processing works
• Inbound Webhooks: webhook payload format and delivery
• Domains: configure MX records for inbound