Skip to main content
Inbound routing rules decide where an arriving message lands before it reaches your inbox. You define an ordered list of match condition → destination pairs; every inbound (MO) message is tested against them, and the first match claims it. Anything no rule claims falls through to the default delivery, so you can add rules incrementally without changing existing traffic. This is the messaging analogue of inbound email routing: the same rule-engine shape you use on a parsed inbound domain, applied to SMS and other message channels. Both surfaces sit behind the same permission tier — rules change where every inbound message in the tenant is delivered, so they are controlled by the owner and admin roles.

​
1. Match conditions

Each rule matches on exactly one of four condition types:
  • number — the receiving number (the DID the message arrived on), compared with normalized E.164 equality. Spaces and dashes collapse before the comparison.
  • sender — the originating number, the same normalized equality. Use this to route known contacts (a VIP customer’s handset, a driver pool’s numbers).
  • keyword — a case-insensitive token found anywhere in the message body. Good for vocabulary-driven triage (HELP, PRICE, a campaign code).
  • regex — a case-insensitive pattern on the message body, validated when you save the rule; an invalid pattern is rejected with a 422 instead of silently never matching. Anchored patterns (^SUPPORT) stay fast; the pattern source is capped at 512 characters.

​
2. Destinations

A matched message goes to one destination:
  • Webhook — an HTTPS, publicly reachable URL on your own infrastructure. Optionally add a shared secret; every delivery is then signed with X-Orbit-Signature: sha256=<hex> so your receiver can verify it. Pick a webhook when another system (a ticket bridge, a data warehouse, a custom processor) owns the follow-up.
  • Queue — a named inbound queue your team works from. Pick a queue when matched messages need triage discipline and handoff metrics rather than a general inbox.
  • Inbox — the shared inbox, the same place unrouted messages land. Pick an inbox when routing is about filing, not staffing.
  • Team — a specific team’s view. Pick a team when the match condition identifies ownership (French senders → the Paris team) rather than workload shape.
As a rule of thumb: webhook for machine consumers, queue for measurable human triage, team for ownership routing, inbox for simple filing.

​
3. Priority ordering

Rules evaluate in ascending priority — the lowest number first — and the first match wins. Ties go to the older rule. When you create rules, leave gaps in the priority numbers (10, 20, 30) so you can insert a rule between two neighbors later without renumbering the list. Unmatched messages keep their default delivery (the shared inbox and your subscribed webhook events), exactly as if no rules existed. A rule never blocks delivery — the worst a bad rule does is claim a message it should not have, and you reverse that by disabling the rule.

​
4. Worked examples

Opt-out traffic to the opt-outs queue. You reply to STOP and UNSUBSCRIBE yourself for audit before the general inbox sees the message. Create a rule with match type keyword, match value STOP, targeting your opt-outs queue at priority 10, and a sibling rule for UNSUBSCRIBE. Every opt-out request lands in the queue before it reaches the general inbox, and anything else keeps default delivery. Regex ticket bridge. Your legacy ticket system subscribes on a webhook. Create a rule with match type regex, match value ^SUPPORT, destination webhook with your bridge URL, at priority 20 below the opt-out rules. Messages starting with SUPPORT post to the bridge; the webhook failure count on the rule row tells you when the bridge stops answering.

​
5. Access control

Creating, listing, updating, and deleting inbound routing rules is restricted to the owner and admin roles — the same permission tier as inbound email routes and sender-pool management. Members and viewers see 403 on the API calls and no rule-management surface in the dashboard. Keep rule edits to that tier: a routing rule changes where every inbound message in the tenant is delivered.

​
6. API surface

The rules engine is exposed under GET/POST/PATCH/DELETE /api/v1/messages/inbound-routes. This guide intentionally does not re-document the endpoint payloads — the API reference is the source of truth for request and response shapes, and the dashboard’s rule form maps one-to-one onto those fields (matchType, matchValue, targetType, targetConfig, priority, enabled).

​
See also