Skip to main content
A sandbox key lets you build and test the full send path — validation, eligibility, webhooks, signature verification — without delivering a message or incurring a charge. Sends run every gate a live send runs, then short-circuit to a simulated result.

​
Getting a sandbox key

Create a sandbox key from the dashboard under Settings → API Keys with Sandbox mode enabled. A key is treated as a sandbox key when it carries the sandbox flag or its value starts with trk_test_.
The partner key-mint endpoint issues live keys — there is no sandbox option on it yet. Provision sandbox keys from the dashboard.
Use a sandbox key exactly like a live key — the same endpoints, the same headers. The response tells you it’s simulated:
No MessageSent row is written, nothing is queued to the carrier, and no usage is billed.
Sandbox keys are read-only for the account hierarchy — creating children, minting keys, and suspending all require a live parent key (403 sandbox_read_only).

​
Deterministic outcomes

Send to a reserved recipient number to force a specific outcome. Any other recipient simulates delivered. A failed outcome also returns error_code: "SANDBOX_CARRIER_REJECT" and an error_description, mirroring a real carrier rejection.

​
Simulated signed webhooks

A single sandbox send fires the matching signed webhook to your account’s configured endpoints — a real HTTP POST with a real X-Trackly-Signature, with data.sandbox: true on the envelope. This is the end-to-end way to prove your signature verification works before going live: send to +15005550101, receive a message.failed event, and confirm your verifier accepts it.
Bulk sends do not fire webhooks. A bulk simulation would fan out one POST per message; to test webhook handling, use single sends to the reserved numbers.
Webhook dispatch is best-effort — if your endpoint is down, the simulated send still returns 201.

​
Every live gate still runs

A sandbox pass means a live send would pass too, because the simulation runs the same checks first and returns the same error codes on failure:
  • Payload shape and E.164 validation (missing_to, invalid_phone, …)
  • Sending-list ownership (list_not_found)
  • BYOC webhook verification (webhook_not_configured)
  • Double opt-in (pending_confirmation, doi_expired)
  • Suppression / opt-out (contact_suppressed)
  • Free-tier BYOC requirement (free_tier_non_byoc)
Two side-effecting behaviors are not simulated: warm-up (its eligibility check would claim a ramp slot) and wrap_links URL shortening (it persists short links). A live wrap_links=true send may therefore report a different segment count than its sandbox preview.

Preflight

Check eligibility, segments, and cost without sending — works with live keys too.

Webhook signing

Verify the signature on the webhooks your sandbox sends fire.