Docs

Everything you need to send SMS

Concise guides for each stage of integration. Language-specific code lives in each SDK's page.

Getting started

Sign up and grab a sandbox API key from the dashboard.
Install your SDK — see /sdks.
Send a test SMS to any registered sandbox phone number.
Go live: swap sa_test_ for sa_live_.

Authentication

SendAfrica uses two credential types. Don't mix them up.

JWT

For a logged-in human. Access token lasts 15 minutes, refresh token lasts 30 days and rotates on use.

Used for: profile, sender IDs, billing, team management.

API key

For calling the messaging gateway. Format sa_live_ or sa_test_. Single scope: sms:send.

This is what every SDK uses by default.

Sending SMS

curl

curl https://api.sendafrica.online/v1/sms/send \
  -H "Authorization: Bearer $SENDAFRICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+255712345678",
    "message": "Habari!",
    "sender_id": "SENDAFRICA"
  }'

Delivery Status

A message moves through: queued → sent → delivered / failed / undelivered. Poll GET /v1/sms/{id}/status, or configure a webhook for push updates.

Webhooks

Register a callback URL via POST /v1/webhooks. Every event is signed with an X-SendAfrica-Signature HMAC header — verify before acting.

delivery.event.json

{
  "event": "sms.delivered",
  "message_id": "msg_7f2c1a",
  "status": "delivered",
  "occurred_at": "2026-07-18T09:12:47Z"
}

Payments

Top up your balance with mobile money (M-Pesa, Tigo Pesa, Airtel Money, MTN MoMo). Call POST /v1/payments/topup, then poll GET /v1/payments/{id}.

Errors

See the full errors table on the API reference page.

Rate limits

The gateway returns 429 rate_limited without a Retry-After. Use client-side exponential backoff (each SDK ships a helper).