Developer Resources
API Documentation
Integrate SMS messaging into your applications with our simple HTTP API or full-featured REST v3 endpoints.
Getting Started
Send your first SMS in minutes. Follow these three simple steps to get up and running with the SDASMS API.
01
Get Your API Key
Sign up or log in to your SDASMS dashboard. Navigate to Settings > API Keys and generate a new key. Keep it secure — it's your authentication credential.
02
Configure Your Endpoint
Choose your preferred API: the simple HTTP API or the full-featured REST v3 API. Both support JSON and form-encoded requests.
03
Send Your First Request
Make a POST request to the SMS send endpoint with your API key, recipient number, and message. You'll receive a message ID for tracking delivery.
Authentication
All API requests require authentication. You can authenticate using either a Bearer token in the Authorization header or by passing your API key as a query parameter.
Bearer Token
Recommended — REST API v3
Include your API key in the Authorization header using the Bearer scheme. This is the recommended method for the v3 REST API.
HTTP Header
Authorization: Bearer YOUR_API_KEYAPI Token Parameter
Simple — HTTP API
Pass your API key as the api_token parameter in the request body or query string. This is the simplest method for the HTTP API.
Form Data
POST /api/http/sms/send
api_token=YOUR_API_KEY
to=+254712345678
from=SDASMS
message=Hello WorldHTTP API Endpoints
A simple, easy-to-use HTTP API for sending SMS and managing your messaging. Perfect for quick integrations and simple use cases.
Base URL:
https://my.sdasms.comPOST
/api/http/sms/sendSend an SMS message to one or more recipients.
| Parameter | Type | Required | Description |
|---|---|---|---|
api_token | string | Required | Your API authentication token |
to | string | Required | Recipient phone number(s), comma-separated |
from | string | Required | Sender ID or phone number |
message | string | Required | SMS text content (up to 160 chars per segment) |
schedule | datetime | Optional | Schedule delivery (ISO 8601 format) |
GET
/api/http/sms/statusCheck the delivery status of a sent message.
| Parameter | Type | Required | Description |
|---|---|---|---|
api_token | string | Required | Your API authentication token |
message_id | string | Required | ID returned from the send endpoint |
POST
/api/http/contactsCreate or update contacts in your address book.
| Parameter | Type | Required | Description |
|---|---|---|---|
api_token | string | Required | Your API authentication token |
phone | string | Required | Contact phone number |
name | string | Optional | Contact display name |
group | string | Optional | Group to assign the contact to |
GET
/api/http/reportsRetrieve delivery reports for your messages.
| Parameter | Type | Required | Description |
|---|---|---|---|
api_token | string | Required | Your API authentication token |
date_from | date | Optional | Start date (YYYY-MM-DD) |
date_to | date | Optional | End date (YYYY-MM-DD) |
status | string | Optional | Filter by status: delivered, failed, pending |
REST API v3 Endpoints
A modern, RESTful API with full JSON support, structured responses, and OAuth2 authentication. Ideal for production applications.
Base URL:
https://my.sdasms.comPOST
/api/v3/sms/sendSend SMS via the RESTful v3 API with full JSON body support.
| Parameter | Type | Required | Description |
|---|---|---|---|
to | array | Required | Array of recipient phone numbers |
from | string | Required | Sender ID or phone number |
message | string | Required | SMS text content |
schedule | datetime | Optional | ISO 8601 scheduled time |
callback_url | string | Optional | Webhook URL for delivery updates |
GET
/api/v3/sms/{id}Retrieve details and delivery status of a specific message.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Required | Message ID (path parameter) |
POST
/api/v3/contactsCreate or update contacts with structured JSON payload.
| Parameter | Type | Required | Description |
|---|---|---|---|
phone | string | Required | Contact phone number |
name | string | Required | Contact display name |
groups | array | Optional | Array of group names to assign |
metadata | object | Optional | Custom key-value pairs |
GET
/api/v3/reportsRetrieve aggregated delivery reports with filtering and pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
date_from | date | Optional | Start date (YYYY-MM-DD) |
date_to | date | Optional | End date (YYYY-MM-DD) |
page | integer | Optional | Page number (default: 1) |
per_page | integer | Optional | Results per page (default: 50) |
POST
/api/v3/groupsCreate contact groups for organized messaging campaigns.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Required | Group name |
description | string | Optional | Group description |
Code Examples
Get started quickly with code samples in popular languages. All examples show how to send an SMS message.
cURL
curl -X POST https://my.sdasms.com/api/http/sms/send \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "api_token=YOUR_API_KEY" \
-d "to=+254712345678" \
-d "from=SDASMS" \
-d "message=Hello from SDASMS API!"Webhooks
Receive real-time delivery updates via HTTP callbacks to your server. Configure your webhook URL in the dashboard or via the API.
Webhook Payload
When a delivery status changes, SDASMS sends a POST request to your configured URL with the following JSON payload:
JSON
{
"event": "sms.delivery",
"message_id": "msg_abc123def456",
"status": "delivered",
"to": "+254712345678",
"timestamp": "2025-01-15T10:30:00Z",
"error_code": null,
"metadata": {
"campaign_id": "camp_789"
}
}Delivery Status Values
Webhook callbacks will include one of the following status values:
queuedMessage is queued and waiting to be sent
sentMessage has been sent to the carrier
deliveredMessage was successfully delivered
failedMessage delivery failed
undeliveredMessage could not be delivered
Your endpoint must respond with a 200 status code within 5 seconds. Failed deliveries are retried up to 3 times with exponential backoff.
Rate Limits
To ensure fair usage and platform stability, API requests are rate-limited. Limits vary by plan and endpoint.
SMS Send
100 req/min
Per API key on standard plans
Status Checks
200 req/min
Delivery status queries
Contact Ops
60 req/min
Create, update, list contacts
Reports
30 req/min
Delivery and analytics reports
Rate Limit Headers
Every API response includes headers to help you track your rate limit usage:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum number of requests allowed in the current window |
X-RateLimit-Remaining | Number of requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the rate limit window resets |
Error Codes
The API uses standard HTTP status codes. Here are the most common errors and how to resolve them.
| Code | Error | Description |
|---|---|---|
| 400 | Bad Request | The request was malformed or missing required parameters. Check your request body and try again. |
| 401 | Unauthorized | Invalid or missing API key. Verify your api_token or Authorization header is correct. |
| 403 | Forbidden | Your API key does not have permission to access this resource. Check your account plan and permissions. |
| 404 | Not Found | The requested resource or endpoint does not exist. Verify the URL path and resource ID. |
| 429 | Too Many Requests | You have exceeded the rate limit. Wait and retry, or contact support to increase your limits. |
| 500 | Server Error | An unexpected error occurred on our servers. Please retry after a moment or contact support. |
Example Error Response
JSON
{
"success": false,
"error": {
"code": 401,
"message": "Invalid API key provided",
"type": "authentication_error"
}
}Developer Ready
Ready to integrate?
Start building today
Get your API key and start sending SMS in minutes. Our comprehensive documentation and code samples make integration a breeze.