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.
Get a test key
Section titled “Get a test key”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.
What happens to a test message
Section titled “What happens to a test message”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"}'import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_TEST_KEY });
const [message] = await sf.messages.send({ to: '+201001234567', body: 'Sandbox test' });await new Promise((resolve) => setTimeout(resolve, 3000));const after = await sf.messages.get(message.id);console.log(after.provider, after.status); // sandbox deliveredimport osimport timeimport requests
headers = {"X-Api-Key": os.environ["SMSFABRIC_TEST_KEY"]}sent = requests.post( "https://api.smsfabric.com/v1/messages", headers=headers, json={"to": "+201001234567", "body": "Sandbox test"}, timeout=30,).json()["data"][0]time.sleep(3)after = requests.get(f"https://api.smsfabric.com/v1/messages/{sent['id']}", headers=headers, timeout=30).json()print(after["provider"], after["status"]) # sandbox delivered<?php$headers = ['X-Api-Key: ' . getenv('SMSFABRIC_TEST_KEY'), 'Content-Type: application/json'];$ch = curl_init('https://api.smsfabric.com/v1/messages');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode(['to' => '+201001234567', 'body' => 'Sandbox test']), CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true,]);$sent = json_decode(curl_exec($ch), true)['data'][0];sleep(3);$ch = curl_init('https://api.smsfabric.com/v1/messages/' . $sent['id']);curl_setopt_array($ch, [CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true]);$after = json_decode(curl_exec($ch), true);echo $after['provider'] . ' ' . $after['status'] . "\n"; // sandbox deliveredThe 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 |
Live and sandbox side by side
Section titled “Live and sandbox side by side”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.
What you can test
Section titled “What you can test”- Request validation, error handling and idempotency.
- Your webhook endpoint, signature checks and deduplication.
- Status handling from
queuedtodelivered. - 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.