SMS GatewayAPI Docs
Quick StartAPI ReferenceSwagger Admin Panel
GETTING STARTED

Quick Start

Get your first SMS sent in under 5 minutes. This guide walks you through getting your API key and making your first request.

1

Get your API key

Contact your administrator to get your API credentials. You will receive:

  • client_idYour unique client identifier (e.g., client_abc123def456)
  • client_secretYour secret key — keep this safe and never expose it in client-side code
2

Authenticate

Exchange your credentials for a Bearer token using the OAuth2 client credentials flow:

Request an access token
curl -X POST "https://api.yourdomain.com/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "client_credentials"
  }'

Response:

Response — 200 OK
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}
Note: Tokens expire after 1 hour. Implement automatic token refresh in your application.
3

Send your first SMS

Use your token to send an SMS. All API requests require the Authorization header.

Send an SMS
curl -X POST "https://api.yourdomain.com/api/v1/sms/send" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+265888123456",
    "message": "Hello! This is my first SMS from SMS Gateway."
  }'

Response:

Response — 200 OK
{
  "success": true,
  "message_id": "msg_abc123xyz789",
  "status": "sent",
  "cost": 0.05,
  "currency": "MWK"
}
4

Check delivery status

Use the message ID from the response to check the delivery status:

Check SMS status
curl -X GET "https://api.yourdomain.com/api/v1/sms/status/msg_abc123xyz789" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
5

Integrate into your app

Use one of our SDK examples to integrate into your application:

Python

send_sms.py
import requests

# Authenticate
auth = requests.post(
    "https://api.yourdomain.com/api/v1/auth/token",
    json={
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "grant_type": "client_credentials"
    }
).json()

token = auth["access_token"]

# Send SMS
response = requests.post(
    "https://api.yourdomain.com/api/v1/sms/send",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "to": "+265888123456",
        "message": "Hello from Python!"
    }
)

print(response.json())

Node.js

send-sms.js
const BASE_URL = "https://api.yourdomain.com";

async function sendSMS(to, message) {
  // Get access token
  const authRes = await fetch(`${BASE_URL}/api/v1/auth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: "YOUR_CLIENT_ID",
      client_secret: "YOUR_CLIENT_SECRET",
      grant_type: "client_credentials"
    })
  });
  const { access_token } = await authRes.json();

  // Send SMS
  const smsRes = await fetch(`${BASE_URL}/api/v1/sms/send`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${access_token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ to, message })
  });

  return smsRes.json();
}

sendSMS("+265888123456", "Hello from Node.js!");

cURL

curl
# 1. Get token
TOKEN=$(curl -s -X POST "https://api.yourdomain.com/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"YOUR_ID","client_secret":"YOUR_SECRET","grant_type":"client_credentials"}' \
  | jq -r '.access_token')

# 2. Send SMS
curl -X POST "https://api.yourdomain.com/api/v1/sms/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"+265888123456","message":"Hello from cURL!"}'

Next Steps