API Documentation
Integrate SMS messaging into your application with our REST API. Send single messages or batch campaigns with just a few lines of code.
Authentication
The API uses HTTP Basic Authentication with your API key and secret.
Basic Authentication
Use your API key and secret for server-to-server integrations.
Send your API key and secret as a Base64-encoded apiKey:apiSecret pair in the Authorization header.
Example with a key my-api-key and secret my-api-secret:
Generate API keys
Create and manage API keys from Settings > API Keys in your dashboard. Each key can be scoped to a specific project and organization.
Base URL
Send SMS
Send a single SMS message to a phone number. Returns immediately with a message ID you can use to track delivery status.
Endpoint
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| channel | string | Yes | Set to "Sms" |
| to | string | Yes | Recipient phone number in E.164 format |
| body | string | Yes* | Message content (or use templateId) |
| from | string | No | Sender ID or phone number |
| templateId | number | No | Use a saved template instead of inline body |
| variables | object | No | Key-value pairs for template variable substitution |
| priority | string | No | Low Normal Medium High |
Example request
curl -X POST /api/messages \ -u "YOUR_API_KEY:YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "channel": "Sms", "to": "+1234567890", "body": "Hi Jane, your order #1042 has shipped!", "from": "+0987654321", "priority": "Normal" }'
Example response
{
"id": 984301,
"status": "Pending",
"channel": "Sms",
"to": "+1234567890"
}Send Batch SMS
Send SMS messages to multiple recipients in a single request. Supply recipients directly, reference contact lists or groups, or combine all three. Batches are processed asynchronously.
Endpoint
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| channel | string | Yes | Set to "Sms" |
| body | string | Yes* | Message content (or use templateId) |
| name | string | No | A name to identify this batch campaign |
| recipients | string[] | No* | Array of phone numbers in E.164 format |
| detailedRecipients | object[] | No* | Recipients with per-recipient variables: { destination, variables } |
| listIds | number[] | No* | Send to contacts in these saved lists |
| groupIds | number[] | No* | Send to contacts in these groups |
| scheduledAt | string | No | ISO 8601 datetime to schedule delivery |
| priority | string | No | Low Normal Medium High |
recipients, detailedRecipients, listIds, or groupIds.Example — simple batch
curl -X POST /api/messages/batch \ -u "YOUR_API_KEY:YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "channel": "Sms", "name": "Order updates", "body": "Hi! Your order is on its way.", "recipients": [ "+1234567890", "+0987654321", "+1122334455" ] }'
Example — personalized batch with variables
curl -X POST /api/messages/batch \ -u "YOUR_API_KEY:YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "channel": "Sms", "name": "Welcome campaign", "body": "Hi {{name}}, welcome to {{company}}!", "isParameterized": true, "detailedRecipients": [ { "destination": "+1234567890", "variables": { "name": "Jane", "company": "Acme" } }, { "destination": "+0987654321", "variables": { "name": "John", "company": "Globex" } } ] }'
Example response
{
"id": 501220,
"status": "Loading",
"totalRecipients": 3
}Message statuses
Track the lifecycle of each message through these statuses.
| Status | Description |
|---|---|
Pending | Message received, awaiting processing |
Queued | Queued for delivery to carrier |
Sent | Handed off to the carrier network |
Delivered | Confirmed delivered to the recipient |
Failed | Delivery failed (invalid number, carrier rejection, etc.) |
Rejected | Rejected by policy or compliance rules |
Ready to start sending?
Create a free account and send your first SMS in minutes. No credit card required.