Troubleshooting: inbound email never routes

Inbound email to your parse domain runs three surfaces in parallel — a webhook forward to your endpoint, an inbox conversation, and (optionally) an email Flow. When you see none of them, work this page top to bottom. It isolates DNS, route matching, normalization, and trigger issues one at a time, so the escalation you open carries exactly the inputs Support needs. The full setup walkthrough lives in inbound email and SMS routing. This page assumes that setup exists and something is misbehaving.

1. The inbound parse pipeline, in order

Every inbound email passes through these stages, and each stage is a place the pipeline can stop:

DNS → MX records. The receiving domain’s MX records point at Orbit’s ingress hostname (shown in Email → Inbound routes → Add route). Until MX resolves, no mail arrives at all.
Route match. The SMTP envelope recipient is matched against your registered inbound routes — exact address, catch-all (*@domain), or local-part — then the To and Cc headers. No match, no parse.
Normalization. The message is parsed into the normalized payload (from, toAddress, matchedRecipient, subject, text, html, attachments metadata, headers including message-id).
Fan-out. The normalized message is forwarded to your destinationUrl as a signed POST and simultaneously opens (or threads onto) an inbox conversation. Signature verification and a 2xx response are required for the forward to count as delivered.
(Optional) Flow trigger. An email-channel Flow can react to the inbound event — compose a reply through email, or fan out to another channel. Inbound email routes themselves have no built-in reply path.

2. Symptom → where to look

Symptom	First check	Second check
No conversation, no webhook, no trace	MX records on the parse domain resolve to Orbit’s ingress host	A route exists whose `recipientPattern` covers the actual recipient (exact, catch-all, or local-part syntax)
Route exists and DNS is fine, still nothing	The address being written to actually matches the pattern — BCC/aliased mail matches envelope first, but a sender addressing a different domain gets no match	Route `active` flag — a disabled route matches nothing
Webhook forward fails, conversation opens	Your endpoint returned a non-2xx, or rejected the signature	`failureCount` / `lastFailureAt` on the route via `GET /email/inbound-routes`
Conversation opens but no Flow trigger	The Flow listens on the inbound email event and its trigger is published/enabled	`text`/`html` are both `null` — an empty-body message can slip past trigger conditions that expect body content
Flow auto-reply looped	Your Flow’s “send email” step targets an address back at the parse domain — the loop closes on itself	Add a reply-to / subject guard in the Flow, or use the inbox reply surface instead of a no-guard outbound send
Bounces and unsubscribes swallowed the parse	A compliance-suppressed recipient on the outbound side — suppressions apply at send, and inbound parse never unsubscribes anyone	Non-2xx webhook responses recorded as forward failures, not parse failures

3. Diagnostic checklist

Work each item in order — collect the output as you go; it becomes your escalation payload.

DNS. dig MX inbound.your-domain.com (or your DNS provider’s record viewer) — confirm the MX record points at the ingress hostname the dashboard displayed when you created the route.
Route shape. GET /email/inbound-routes — confirm a route exists and its recipientPattern covers the exact address being written to, in whichever syntax (exact, catch-all, local-part) you registered. Check active: true and failureCount: 0.
Normalized payload. From an earlier working message (or the guide’s example): does the payload carry text or html, and a headers.message-id? A body-less message is valid but can break downstream matchers. Attachment bytes never appear here — only metadata — unless you set includeRawMime: true on the route.
Signature. Your endpoint must verify the X-Orbit-Signature header (sha256=<hex>, HMAC over the raw body, keyed by the route’s signingSecret) and return 2xx. Only 2xx counts; redirects are not followed.
Flow trigger. If you expected a Flow: open it, confirm it triggers on the inbound email event, and confirm the trigger is enabled and published. The flow executions page covers trigger-side failure in more depth.

Inspect inbound routes over the API

The route state checks below (recipientPattern coverage, active, failureCount / lastFailureAt) all read the same listing endpoint. List every registered inbound email route:

curl https://api.orbit.devotel.io/api/v1/email/inbound-routes \
  -H "X-API-Key: dv_live_sk_YOUR_KEY"

The response is the standard { data, meta } envelope, with the routes under data.routes:

{
  "data": {
    "routes": [
      {
        "id": "einr_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
        "recipientPattern": "support@inbound.your-domain.com",
        "destinationUrl": "https://api.your-app.com/hooks/orbit-inbound",
        "includeRawMime": false,
        "active": true,
        "description": "Support mailbox → helpdesk",
        "failureCount": 0,
        "lastForwardedAt": "2026-08-30T14:22:10.000Z",
        "lastFailureAt": null,
        "createdAt": "2026-08-01T09:15:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_…",
    "timestamp": "2026-08-30T14:40:02.000Z"
  }
}

Compare the row against what you expect: active: true, recipientPattern covering the failing address, and failureCount: 0. A rising failureCount with a recent lastFailureAt means the webhook endpoint is rejecting the forwards — check its response codes and signature verification, not the route. Signing secrets never appear in this listing; the plaintext secret is returned only once, at route creation. Every route the list call returns carries recipientPattern, destinationUrl, active, failureCount, and lastFailureAt, so one call is enough for the full check — there is no separate single-route read you need here. To re-check between fix attempts, poll the same list call before sending the next test message:

async function getRouteStatus(id) {
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/email/inbound-routes",
    { headers: { "X-API-Key": process.env.ORBIT_API_KEY } },
  );
  const { data } = await res.json();
  const route = data.routes.find((r) => r.id === id);
  return {
    active: route?.active,
    failureCount: route?.failureCount,
    lastFailureAt: route?.lastFailureAt,
  };
}

Escalate with these

Open a ticket when every item above is clean and inbound mail still never lands. Include all four:

The parse domain (for example inbound.your-domain.com).
The route id from GET /email/inbound-routes (the einr_… id).
One sample headers.message-id from a message that should have routed (the RFC 5322 Message-ID header).
Your tenant ID — in the dashboard under Settings → Organization, and returned by the GET /api/v1/me response as organizationId.

With the domain, route id, and a concrete Message-ID, Support can tell within one lookup whether the message reached ingress at all, and which stage turned it away.

Reference

Troubleshooting: inbound email never routes

Troubleshooting: inbound email never routes

1. The inbound parse pipeline, in order

2. Symptom → where to look

3. Diagnostic checklist

Inspect inbound routes over the API

Escalate with these

See also

​Troubleshooting: inbound email never routes

​1. The inbound parse pipeline, in order

​2. Symptom → where to look

​3. Diagnostic checklist

​Inspect inbound routes over the API

​Escalate with these

​See also

Troubleshooting: inbound email never routes

1. The inbound parse pipeline, in order

2. Symptom → where to look

3. Diagnostic checklist

Inspect inbound routes over the API

Escalate with these

See also