Sandbox Magic Numbers

Orbit’s sandbox simulator routes every send through a deterministic rule keyed by the trailing digit of the recipient number, so you can exercise your delivery-receipt (DLR), retry, and dead-letter handling without touching a real carrier. Every send is keyed by the trailing digit of the recipient number. Send to +15005550005 and you receive an expired delivery receipt; send to +15005550003 and you receive undelivered; send to +15005550001 and the carrier only ACKs the submit and never reports a final state — so you can exercise your DLR-timeout handling. Each scenario walks the same intermediate→terminal sequence a real carrier produces. The simulator only activates when:

The API key is a sandbox key (prefix dv_test_sk_*), or
The organisation has is_sandbox = true in the Orbit data plane, or
The request carries the X-Test-Mode: true header from the dashboard.

Magic numbers in live mode are sent to the real carrier — there is no production-side magic behaviour. The trailing-digit convention is sandbox-only.

Message sends — the delivery-state table

The trailing digit of the recipient selects one of ten delivery scenarios. Each scenario emits its full delivery-receipt sequence as message.status webhooks — an intermediate sent acknowledgement (when the message reaches the carrier) followed by the terminal outcome:

Trailing digit	Scenario	Webhook `data.status` sequence	Terminal DLR latency
`1`	Submitted only	`sent`	never (ACK only)
`2`	Delivered	`sent` → `delivered`	~50 ms
`3`	Undelivered	`sent` → `undelivered`	~1150 ms
`4`	Failed (pre-submit)	`failed`	~100 ms
`5`	Expired (TTL)	`sent` → `expired`	~3 s
`6`	Unknown (no report)	`sent` → `unknown`	~5 s
`7`	Rejected (spam filter)	`rejected`	~150 ms
`8`	Blocked (suppression)	`blocked`	~50 ms
`9`	Delayed	`sent` → `delivered`	~60 s
`0`	Carrier rewrite	`sent` → `delivered`	~50 ms

Each webhook carries a state_class (intermediate or terminal) and an is_terminal flag so your handler can tell an in-flight update from a final outcome — the same tags the production delivery-receipt path stamps. The trailing-0 (carrier rewrite) terminal receipt also carries body_rewritten_by_carrier: true, mimicking regulatory sender-ID rewrites. Delivery receipts do not change your stored message — a sandbox send never reaches a carrier, so the message keeps its honest test_sent status rather than being promoted to delivered/failed. The receipts appear only in the webhook payloads sent to your sandbox webhook URL, never on the message you retrieve through the API. Any E.164 number with the same trailing digit triggers the same scenario — +15005550009, +15555550009, and +908505550009 all resolve to the delayed-then-delivered sequence.

Example: simulate a failed delivery

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15005550004",
    "from": "+15005550101",
    "body": "Trailing 4 → pre-submit failure, status=failed within ~100ms"
  }'

Your sandbox webhook endpoint receives a single message.status event with data.status: "failed", state_class: "terminal" — no real carrier is touched, no balance is deducted.

Example: simulate a delivered message

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15005550002",
    "from": "+15005550101",
    "body": "Trailing 2 → sent then delivered within ~100ms"
  }'

Your webhook receives two message.status events in order: an intermediate data.status: "sent" (state_class: "intermediate"), then data.status: "delivered" (state_class: "terminal").

Voice calls

Sandbox voice calls always resolve completed today. The trailing-digit table below is a reference catalog of the outcomes simulateCall can compute — it is not yet wired into the live call path. The sandbox short-circuit pins the call record and the async lifecycle event to completed, and returns { "status": "completed" } synchronously, regardless of the recipient’s trailing digit. If you place a sandbox call to a number ending in 9 expecting no-answer, you will still receive completed. Treat the table below as the planned mapping, not behaviour you can trigger today.

simulateCall keys on the trailing digit too, but with three outcomes:

Trailing digit	Outcome
`9`	`no-answer`
`8`	`busy`
any other	`completed`

The simulated lifecycle (call.initiated → call.answered → call.ended) fires through the same sandbox-events worker.

Reference catalog: `GET /sandbox/numbers`

Orbit also publishes a 10-state magic-number catalog for clients that want to render their own developer surface (e.g. an embedded “Test your integration” widget). This is a descriptive reference table returned by the read-only GET /sandbox/numbers endpoint and serialised from SANDBOX_MAGIC_NUMBERS in @devotel/messaging/sandbox/magic-numbers.

These ten states are the same scenarios the live send/DLR path fires (see the delivery-state table above). The catalog is a machine-readable copy of that mapping so you can render your own developer surface — e.g. an embedded “Test your integration” widget — without hard-coding the digits and latency bands yourself.

curl https://api.orbit.devotel.io/api/v1/sandbox/numbers \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY"

Response (one entry per trailing digit):

{
  "data": {
    "numbers": [
      {
        "trailing_digit": "1",
        "example_e164": "+15005550001",
        "status": "submitted",
        "label": "Submitted only",
        "description": "Carrier accepts the message and returns an ACK, but never reports a final delivery state...",
        "fires_dlr": false,
        "dlr_latency_ms_min": 0,
        "dlr_latency_ms_max": 0,
        "rewrite_footer": null
      }
    ],
    "docs_url": "https://docs.orbit.devotel.io/sandbox/magic-numbers"
  }
}

The full catalog covers the statuses submitted, delivered, undelivered, failed, expired, unknown, rejected, blocked, delayed, and carrier_rewrite, each keyed by trailing digit (1–0). See SANDBOX_MAGIC_NUMBERS for the canonical example numbers, latency bands, and descriptions.

Hard rules

No real carrier is ever reached. Every magic-number send short-circuits before the provider router resolves a backend.
No balance is deducted. Sandbox sends always have cost_usd_cents: 0 and never reach Stripe or your wallet.
DLRs fire to your sandbox webhook URL only. Configure this separately from your live URL under Settings → API Keys → Sandbox so production handlers never see test traffic.
Channels covered: SMS, MMS, WhatsApp, RCS, Viber, Telegram, Messenger, AMB, Email. Channel-specific status codes (e.g. WhatsApp 131047) are out of scope for the magic-number convention; the trailing-digit rule maps to the canonical generic status set.

API Reference

All Endpoints

Sandbox Magic Numbers

Sandbox Magic Numbers

Message sends — the delivery-state table

Example: simulate a failed delivery

Example: simulate a delivered message

Voice calls

Reference catalog: `GET /sandbox/numbers`

Hard rules

​Sandbox Magic Numbers

​Message sends — the delivery-state table

​Example: simulate a failed delivery

​Example: simulate a delivered message

​Voice calls

​Reference catalog: GET /sandbox/numbers

​Hard rules

Sandbox Magic Numbers

Message sends — the delivery-state table

Example: simulate a failed delivery

Example: simulate a delivered message

Voice calls

Reference catalog: `GET /sandbox/numbers`

Hard rules