SMS API Documentation - REST API Reference

Learn how to send SMS via API and set up SMS webhook integration for receiving messages

Getting Started SMS Webhook Setup - Receive SMS via API How to Send SMS via API Rate Limits & Best Practices

Getting Started

Welcome to the SMS Forwarder REST API documentation. This comprehensive guide will help you integrate programmable SMS sending and receiving capabilities into your applications using our webhook-based architecture.

API Authentication

All API requests require authentication using an API key. Generate your API key from the API Keys page.

Include your API key in the Authorization header as a Bearer token.

Base URL

https://sms.smsforwarding.com/api

SMS Webhook Setup - Receive SMS via API

Configure webhooks to receive real-time SMS notifications when messages arrive at your devices. Our SMS webhook API delivers incoming messages instantly to your configured endpoints. Visit the Webhooks page to set up your endpoints.

How SMS Webhooks Work

Create a webhook endpoint in your application
Register the endpoint URL in the Webhooks page
When an SMS arrives, we'll send a POST request to your endpoint
Your application receives and processes the SMS data in real-time

Webhook Payload Example

When an SMS is received, your webhook will receive this JSON payload:

{
  "event": "incoming_sms",
  "timestamp": "2024-02-08T10:30:45.123Z",
  "device": {
    "id": 123,
    "sim_number": "+1234567890",
    "device_name": "My Android Device"
  },
  "sms": {
    "id": 456,
    "sender": "+9876543210",
    "message": "Your verification code is 123456",
    "received_at": "2024-02-08T10:30:45.123Z"
  }
}

Webhook Security

Always validate webhook requests by checking the source IP and implementing signature verification. Respond with a 200 status code within 5 seconds to avoid timeouts.

How to Send SMS via API

Send SMS messages programmatically through your registered Android devices using our REST API. Simple HTTP POST requests allow you to send SMS to any phone number worldwide.

Endpoint

POST /sms/send

Request Parameters

Parameter	Type	Required	Description
simNumber	string	Yes	Your device's SIM number (sender)
recipients	string or array	Yes	Single recipient (string) or multiple recipients (array of strings)
messageContent	string	Yes	Message content (max 160 chars per segment)
priority	number	Yes	Message priority level (0-5). We recommend priority 3 for most use cases.

Priority Levels (0-5)

0 - Low priority (non-urgent notifications)
1 - Below normal priority
2 - Normal priority (general messages)
3 - Above normal priority (recommended for most use cases)
4 - High priority (important alerts)
5 - Urgent/Critical (time-sensitive messages)

Single vs. Bulk SMS

Single Recipient: Pass recipients as a string. Response has batchId: null
Multiple Recipients: Pass recipients as an array. Response includes a unique batchId for tracking the bulk operation
Both modes support the same priority levels and return an array of SMS IDs for tracking delivery status.

Code Examples

curl -X POST https://sms.smsforwarding.com/api/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "simNumber": "+917002352056",
    "recipients": "+916000089047",
    "messageContent": "Hello from SMS Forwarder API!",
    "priority": 3
  }'

Success Response - Single Recipient

When sending to a single recipient, the response includes batchId: null:

{
  "success": true,
  "message": "SMS queued successfully",
  "data": {
    "smsIds": [109],
    "recipientsCount": 1,
    "batchId": null,
    "status": "PENDING",
    "estimatedProcessingTime": "1-2 minutes",
    "createdAt": "2026-02-10T10:32:08.189Z"
  }
}

Success Response - Multiple Recipients (Bulk)

When sending to multiple recipients, the response includes a unique batchId for tracking:

{
  "success": true,
  "message": "Bulk SMS queued successfully",
  "data": {
    "smsIds": [113, 114],
    "recipientsCount": 2,
    "batchId": "90366e98-4bb1-4a0e-94f7-d3eea881a679",
    "status": "PENDING",
    "estimatedProcessingTime": "1-2 minutes",
    "createdAt": "2026-02-10T14:45:20.469Z"
  }
}

Response Fields

Field	Type	Description
success	boolean	Whether the request was successful
message	string	Human-readable message ("SMS queued successfully" or "Bulk SMS queued successfully")
data.smsIds	array	Array of SMS IDs created for tracking delivery status
data.recipientsCount	number	Number of recipients
data.batchId	string or null	Batch ID for bulk SMS (null for single recipient)
data.status	string	Current status (PENDING, QUEUED, etc.)
data.estimatedProcessingTime	string	Estimated time for processing
data.createdAt	string	ISO 8601 timestamp of creation

Error Response

{
  "success": false,
  "error": "Invalid recipient number",
  "code": "INVALID_RECIPIENT"
}

Rate Limits & Best Practices

API Rate Limits

Free Plan: 5 requests per minute, 100 requests per day
Pro Plan: 1,000 requests per minute, 50,000 requests per day
Enterprise: Custom rate limits available

Best Practices

Implement exponential backoff
If you receive a 429 (Too Many Requests) response, wait before retrying with exponentially increasing delays.
Keep your API keys secure
Never expose API keys in client-side code, public repositories, or logs. Use environment variables.
Monitor webhook reliability
Check webhook delivery logs in the Webhooks page to ensure your endpoints are responding correctly.
Handle message segmentation
SMS messages over 160 characters are split into multiple segments. Plan your billing and UX accordingly.

Need Help?

Our support team is here to help you integrate our SMS API into your applications.

Contact Support Configure Webhooks