SMS GatewayDocumentation

Sandbox Mode

Test your integration thoroughly without affecting production data or incurring any costs. Sandbox mode simulates the full API behavior in an isolated environment.

Overview

Sandbox mode provides a fully functional testing environment where you can develop and validate your integration before going live. All API endpoints are available, but messages are simulated rather than delivered to real carriers.

Sandbox accounts are free and unlimited. Use them for development, CI/CD testing, demos, and QA — without spending a single cent.

Getting a Sandbox Account

New accounts are automatically created in sandbox mode. You can also switch an existing account to sandbox mode from the Developer Portal, or register with a sandbox flag:

bash
1curl -X POST https://api.smsgateway.com/api/v1/auth/register \
2  -H "Content-Type: application/json" \
3  -d '{
4    "email": "developer@example.com",
5    "password": "securePassword123",
6    "organizationName": "My Test Org",
7    "sandbox": true
8  }'

Sandbox Features

SMS with [Sandbox Test] Prefix

All outgoing SMS messages are automatically prefixed with [Sandbox Test] to clearly identify them as simulated messages.

OTP Testing

Full OTP send and verify flow works in sandbox. You can use any OTP code for testing, or configure specific test codes.

Delivery Simulation

Configure simulated delivery delays and fail rates to test your error handling and retry logic.

Full Analytics

Access analytics and reporting as in production to verify your dashboard integrations.

Sending SMS in Sandbox

Use your sandbox API key (prefixed with sg_test_) to make requests:

sandbox-sms.sh
1curl -X POST https://api.smsgateway.com/api/v1/sms/send \
2  -H "Authorization: Bearer sg_test_your_sandbox_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "to": "+251911234567",
6    "body": "Your verification code is 4829"
7  }'
response.json
1{
2  "messageId": "msg_sandbox_9x8y7z6w5v",
3  "status": "sent",
4  "to": "+251911234567",
5  "body": "[Sandbox Test] Your verification code is 4829",
6  "sandbox": true,
7  "createdAt": "2025-01-15T10:30:00.000Z"
8}

Sandbox Endpoints

GET
/api/v1/sandbox/statusCheck sandbox status and limits
GET
/api/v1/sandbox/statsView sandbox analytics
POST
/api/v1/sandbox/simulateConfigure delivery simulation
POST
/api/v1/sandbox/migrateMigrate to production

Check Sandbox Status

sandbox-status.sh
1curl -X GET https://api.smsgateway.com/api/v1/sandbox/status \
2  -H "Authorization: Bearer <sandbox_api_key>“
status-response.json
1{
2  "isSandbox": true,
3  "environment": "sandbox",
4  "organizationId": "org_sandbox_abc123",
5  "limits": {
6    "smsPerDay": 100,
7    "otpPerDay": 20
8  },
9  "createdAt": "2025-01-10T08:00:00.000Z"
10}

Configure Delivery Simulation

Customize how the sandbox simulates message delivery:

Request Body

deliveryDelay
optional
integer — Seconds to delay before simulated delivery (default: 0).
failRate
optional
integer — Percentage of messages that should simulate failure (0-100).
carrierStatus
optional
string — Forced carrier status: "delivered", "pending", or "failed".
simulate-config.sh
1curl -X POST https://api.smsgateway.com/api/v1/sandbox/simulate \
2  -H "Authorization: Bearer <sandbox_api_key>“ \
3  -H "Content-Type: application/json" \
4  -d '{
5    "deliveryDelay": 5,
6    "failRate": 10,
7    "carrierStatus": "delivered"
8  }'
simulate-response.json
1{
2  "deliveryDelay": 5,
3  "failRate": 10,
4  "carrierStatus": "delivered",
5  "updatedAt": "2025-01-15T10:30:00.000Z"
6}

Sandbox vs Production

FeatureSandboxProduction
SMS Sending
OTP Sending & Verification
Delivery Simulation
Configurable Delays
Fail Rate Simulation
Analytics Dashboard
Webhook Events
API Key Management
Real Carrier Delivery
Billing / Charges
Production Contacts
Production Campaigns

Migrate to Production

When you're ready to go live, use the migrate endpoint to upgrade your sandbox account to production. This will:

  • Convert your sandbox API keys to production keys
  • Preserve your webhook configurations
  • Enable real carrier delivery
  • Begin billing for SMS usage
migrate.sh
1curl -X POST https://api.smsgateway.com/api/v1/sandbox/migrate \
2  -H "Authorization: Bearer <sandbox_api_key>“ \
3  -H "Content-Type: application/json" \
4  -d '{
5    "confirmProduction": true
6  }'

Testing Tips

Use Real Phone Formats

Even in sandbox, use valid E.164 phone numbers to catch formatting issues before production.

Test Error Handling

Configure a 100% fail rate to verify your application handles delivery failures gracefully.

Test Webhooks

Use tools like ngrok to expose a local endpoint and test webhook delivery in sandbox.

Automate in CI/CD

Run integration tests against sandbox in your CI pipeline to catch regressions early.

Related Pages

SDK Examples

Code examples that work in both sandbox and production.

API Keys

Understand sandbox vs production key formats.