How routing picks a sender

When you send a message without hardcoding a sender, Orbit resolves the from address through a fixed precedence chain. This page documents that chain, what each sender-pool strategy does, and how inbound (MO) rules route replies. Request and response schemas are owned by the Messaging API reference; this page covers routing behaviour only.

Precedence: what the platform checks first

On POST /api/v1/messages/sms, Orbit resolves the sender in this order. The first source that produces a sender wins:

#	Source	Wins over	Notes
1	`from_extension`	Everything below	UCaaS per-user business SMS — resolves to the DID on that extension. Mutually exclusive with `sender_pool_id` (sending both returns 422)
2	`sender_pool_id` in the request body	A bare `from`, messaging-service defaults, and the fallback chain	Resolved through the pool’s strategy (below). Sending both `from` and `sender_pool_id` is an ambiguous request — the pool wins and the explicit `from` is ignored; pass exactly one sender identity per request
3	`from` in the request body	Messaging-service defaults and the fallback chain	An explicit sender is the operator’s choice — honoured when no pool id is on the body
4	`messaging_service_id`	Conversation sticky sender and the fallback chain	The service’s own `sender_pool_id` (or per-country override pool) fills in only when you did not pass `sender_pool_id` yourself
5	Conversation sticky sender	Fallback chain	Two-way SMS replies to an existing conversation pin the sender to the DID the contact originally texted — only when no source above matched
6	Fallback chain	—	Org default sender → your first active number → the platform default number for `+1` destinations, or the `Devotel` alphanumeric sender ID for international destinations

Three rules worth knowing up front:

sender_pool_id and from_extension are mutually exclusive; sending both returns 422.
Sending both from and sender_pool_id is an ambiguous request — the pool wins and the explicit from is silently ignored. Pass exactly one sender identity per request (the full interaction matrix is on Sender resolution).
On a messaging service with a country_sender_pools map, the recipient-country’s override pool is preferred before the service-level default pool — but only when you did not set sender_pool_id explicitly.

Sender pool resolution

A sender pool groups sender identities (E.164 numbers, short codes, alphanumeric sender IDs) behind a selection strategy. At send time the pool picks exactly one of its members:

Strategy	How it picks	Where the state lives
`sticky` (default)	Deterministic per-recipient pick	The per-recipient assignment is persisted so the same recipient keeps the same sender across restarts
`round_robin`	Cycles through pool members in order	A per-pool counter spreads volume evenly
`random`	Uniform pick	No state
`geomatch`	Matches the recipient’s country to a same-country sender in the pool	Falls back to `sticky` over the whole pool when no sender matches the country, so the send never fails

Each pool member accumulates a health tier from delivery outcomes, and the rotation scheduler auto-swaps a degraded member for a warmed replacement. Creating pools, previewing which sender a recipient would get, and reading health are covered in the Sender pools guide.

Inbound routing (MO)

Outbound picks a sender; inbound rules decide where a received message goes. Tenant-level inbound rules are evaluated in priority order (lower value first) and match on:

number — the destination DID the message arrived on
sender — the originating address
keyword — case-insensitive substring of the message body
regex — a regular expression tested against the body

The first enabled rule that matches dispatches to one of: a webhook (signed HTTPS POST), a queue, an inbox, a team, or an ivr keyword menu tree. When no rule matches, the message falls through to the default inbox and the message.received event. Manage rules under /api/v1/messages/inbound-routes. This tenant-level rule set sits above the per-DID inbound hooks you may also have configured: pools own the “which sender” decision, these rules own the “where the reply lands” decision.

One curl example per branch

Explicit sender (branch 1):

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155550100", "from": "+14155559999", "body": "Hi" }'

Sender pool (branch 3):

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155550100", "sender_pool_id": "pool_abc123", "body": "Hi" }'

Messaging service fallback (branch 4 — the pool comes from the service):

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155550100", "messaging_service_id": "ms_abc123", "body": "Hi" }'

Inbound rule (MO):

curl -X POST https://api.orbit.devotel.io/api/v1/messages/inbound-routes \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP replies to the priority inbox",
    "matchType": "keyword",
    "matchValue": "vip",
    "targetType": "inbox",
    "targetConfig": { "inboxId": "inbox_vip" },
    "priority": 10
  }'

For the full request/response schema of the send endpoint, see the Messaging API reference.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

How routing picks a sender

How routing picks a sender

Precedence: what the platform checks first

Sender pool resolution

Inbound routing (MO)

One curl example per branch

See also

​How routing picks a sender

​Precedence: what the platform checks first

​Sender pool resolution

​Inbound routing (MO)

​One curl example per branch

​See also

How routing picks a sender

Precedence: what the platform checks first

Sender pool resolution

Inbound routing (MO)

One curl example per branch

See also