Sandbox Magic Numbers

Orbit’s sandbox simulator routes every send through a deterministic table keyed by the trailing digit of the recipient number. The trailing digit selects one of ten Sinch-equivalent delivery scenarios — happy-path delivered, undelivered, failed, expired, rejected, blocked, carrier-rewrite, and three long-tail variants. Use these to exercise your retry, dead-letter, and DLR-timeout logic against realistic delivery shapes without touching a real carrier. 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.

The 10 magic-number cases

The canonical example numbers live in the NANP +1 (500) 555-000X fictional sub-range. Any E.164 number with the same trailing digit triggers the same behaviour — +15005550002, +15555550002, and +908505550002 all resolve to the delivered happy-path.

Trailing digit	Canonical example	Status	DLR latency	Description
`1`	`+15005550001`	`submitted`	(no DLR)	Carrier acknowledges submission but never reports a final state. Tests your DLR-timeout / dead-letter fallback.
`2`	`+15005550002`	`delivered`	0–100 ms	The default happy-path. The recipient handset reports delivered within ~50 ms.
`3`	`+15005550003`	`undelivered`	800–1500 ms	The carrier accepts the SUBMIT but the handset reports back undelivered. Mimics off-network roaming or device-side opt-out lists.
`4`	`+15005550004`	`failed`	50–150 ms	Network error before the message reached the SMSC. Standard `failed` DLR.
`5`	`+15005550005`	`expired`	3 s	Message TTL elapsed before the carrier could deliver.
`6`	`+15005550006`	`unknown`	5 s	Carrier never reported a final state. Exercises the long-tail reconciler path.
`7`	`+15005550007`	`rejected`	100–200 ms	Carrier-side rejection (spam filter, content policy).
`8`	`+15005550008`	`blocked`	25–75 ms	Recipient is on a suppression list or has opted out.
`9`	`+15005550009`	`delayed`	60 s	Eventually delivered after a 60-second lag. Use this to verify your client doesn’t time-out long-tail delivery DLRs.
`0`	`+15005550010`	`carrier_rewrite`	0–100 ms	Carrier delivers but appends a regulatory footer. The simulated DLR carries `metadata.body_rewritten_by_carrier = true`.

Example: send to the failed-path number

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": "This send will fail with status=failed within ~100ms"
  }'

Your webhook endpoint will receive a message.status_updated event with status: "failed" after the documented latency band — no real carrier is touched, no balance is deducted.

Example: test long-tail 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": "+15005550009",
    "from": "+15005550101",
    "body": "Eventually delivered after 60 seconds"
  }'

Your webhook will not receive a DLR for ~60 seconds. If your client expects DLRs within a tight window, switch to +15005550002 (delivered happy-path) or +15005550004 (failed).

Programmatic table access

The magic-number table is also exposed via the API for clients that want to render their own developer surface (e.g. an embedded “Test your integration” widget):

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

Response:

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

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 table; the suffix-driven status maps to the canonical generic status set.

Documentation Index

​Sandbox Magic Numbers

​The 10 magic-number cases

​Example: send to the failed-path number

​Example: test long-tail delivery

​Programmatic table access

​Hard rules