SMS API

SMS API Reference

Send and manage SMS messages via REST API. All endpoints require authentication and return JSON responses.

Endpoints

POST

/api/v1/sms

Send a single SMS to one recipient

POST

/api/v1/bulk-sms

Send SMS to multiple recipients

POST

/api/v1/otp

Generate and send an OTP code

POST

/api/v1/sms/verify-otp

Verify an OTP code

GET

/api/v1/health

Check API health status

GET

/api/v1/validate

Validate an API key

Send Single SMS

Send an SMS message to a single phone number.

POST /api/v1/sms

Request Body

Parameter	Type	Required	Description
to	string	Required	Recipient phone number in E.164 format (e.g., +265888123456)
message	string	Required	Message content (max 160 characters per SMS segment)
from	string	Optional	Sender ID (alphanumeric, max 11 characters)
reference	string	Optional	Your reference ID for tracking this message
webhook_url	string	Optional	URL to receive delivery status callback
priority	string	Optional	Priority: "low", "normal", "high" (default: normal)
scheduled_at	string	Optional	Schedule delivery in ISO 8601 format

Send an SMS

curl -X POST "https://api.yourdomain.com/api/v1/sms" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+265888123456",
    "message": "Your verification code is 123456",
    "from": "YourBrand",
    "reference": "txn_12345",
    "priority": "high"
  }'

Response

200 OK

{
  "success": true,
  "message_id": "msg_abc123xyz789",
  "status": "sent",
  "cost": 0.05,
  "currency": "MWK",
  "rate_limit": {
    "remaining": 99,
    "reset": 60
  }
}

Error Response

400 Bad Request

{
  "success": false,
  "error": "Invalid phone number format",
  "code": "INVALID_PHONE_NUMBER"
}

Send Bulk SMS

Send SMS to multiple recipients in one request.

POST /api/v1/bulk-sms

Parameter	Type	Required	Description
recipients	array[string]	Required	Array of phone numbers in E.164 format (max 10,000)
message	string	Required	Message content
from	string	Optional	Sender ID
reference	string	Optional	Your reference ID for tracking
webhook_url	string	Optional	URL for delivery report callbacks
batch_size	integer	Optional	Batch size for processing (default: 100)

Send bulk SMS

curl -X POST "https://api.yourdomain.com/api/v1/bulk-sms" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      "+265888123456",
      "+265999654321",
      "+265777888999"
    ],
    "message": "Bulk notification message",
    "from": "YourBrand",
    "reference": "campaign_001"
  }'

200 OK

{
  "success": true,
  "message_ids": ["msg_001", "msg_002", "msg_003"],
  "total_sent": 3,
  "total_failed": 0,
  "total_cost": 0.15
}

Health Check

Check the API health status.

GET /api/v1/health

Check health

curl -X GET "https://api.yourdomain.com/api/v1/health"   -H "Authorization: Bearer sk-your-api-key"

200 OK

{
  "success": true,
  "data": {
    "message_id": "msg_abc123",
    "status": "delivered",
    "recipient": "+265888123456",
    "sent_at": "2026-01-13T10:30:00Z",
    "delivered_at": "2026-01-13T10:30:15Z",
    "cost": 0.05
  }
}

Status Values

Status	Description
`pending`	Queued for delivery
`sent`	Sent to carrier
`delivered`	Successfully delivered to recipient
`failed`	Delivery failed
`expired`	Delivery timeout exceeded
`rejected`	Rejected by carrier

Get Account Balance

Check your current credit balance.

GET /api/v1/account/balance

200 OK

{
  "success": true,
  "data": {
    "balance": 1000.00,
    "currency": "MWK",
    "credit_limit": 5000.00,
    "last_updated": "2026-01-13T10:00:00Z"
  }
}