Skip to content

Sandbox

The sandbox is the real API with a virtual phone behind it. Requests made with an sf_test_ key are validated, stored, rate limited and reported exactly like live ones, and you get the same webhooks, but no SMS leaves any SIM. Use it for development, CI and demos.

In the portal, open Developers → API keys, click Create API key and choose Test · sandbox as the Mode (walkthrough). Or, signed in, call POST /v1/api-keys with "mode": "test". The key starts with sf_test_.

You don’t need a paired phone to use the sandbox.

Terminal window
curl https://api.smsfabric.com/v1/messages \
-H "X-Api-Key: sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to": "+201001234567", "body": "Sandbox test"}'

The message moves through these statuses within about 2 seconds:

Time Status Webhook
0 s queued message.queued
immediately routed, with provider: "sandbox" and deviceId: null none
about 0.5 s sent message.sent
about 2 s delivered message.delivered
sf_live_ sf_test_
SMS reaches the recipient Yes No
Needs a paired phone Yes No
provider device sandbox
deviceId, simId The phone and SIM used null
deviceId, simId, poolId in the request Must exist in your organization Ignored
Send window and scheduledAt Both apply Only scheduledAt applies
Blacklist Applies (blocked) Applies (blocked)
Validation, idempotency, rate limits Apply Apply
Webhooks Sent Sent
Campaigns Run through your phones Run with sandbox: true, all delivered
Verify Code sent by SMS Created and limited as usual; the code is never delivered

Sandbox and live data live in the same organization. Test messages appear in GET /v1/messages and the portal’s Messages screen with provider: "sandbox", so you can see them next to your real traffic.

  • Request validation, error handling and idempotency.
  • Your webhook endpoint, signature checks and deduplication.
  • Status handling from queued to delivered.
  • Campaign creation, estimates, pacing, pause, resume and reports.
  • Blacklist and STOP handling (add a number to the blacklist and send to it).

What you can’t test in the sandbox: real delivery, a phone going offline or failing, inbound messages, and approving a Verify code. Use a live key, a paired phone and your own number for those.

When your integration works in the sandbox, follow Go live.