Sandbox & test numbers

Test keys (ghost_sk_test_) run against a fully simulated environment: no carrier traffic, no charges, and nothing real ever sent. Every endpoint works, so you can build your whole integration — including webhooks — before going live.

Your sandbox number

Signup provisions a sandbox number in the reserved +1 500-555-XXXX range. It's the from for outbound tests and the to for simulated inbound. You can "purchase" more from GET /v1/numbers/available + POST /v1/numbers — the whole numbers API works in the sandbox.

Magic destination numbers

Send to these numbers to trigger fixed behaviors:

Number	Behavior
`+15005550006`	Delivered: status `sent`, then a `message.delivered` event ~2s later. Any other number behaves the same.
`+15005550001`	Stuck: status stays `queued` forever, no delivery event.
`+15005550002`	Failed: status `failed` and a `message.failed` event with code `undeliverable`.

Simulated inbound

POST /v1/test/inbound delivers a fake inbound SMS to one of your sandbox numbers through the real pipeline: it appears in GET /v1/messages and emits a message.received event. (Test keys only — live keys get a 403 test_mode_only.)

Sandbox limits

A ceiling of 1,000 messages/day per account keeps the sandbox healthy. It's not a product quota — if you legitimately hit it, tell us.