Quickstart

Send your first SMS with the SendAfrica API in under five minutes — get a key, send a message, check your balance.

This guide takes you from zero to a delivered SMS. All you need is a SendAfrica account and a terminal.

#1. Get your API key

Create an account at https://app.sendafrica.online and verify your email (a 6-digit OTP is sent automatically).
Log in to the dashboard and go to Settings → API Keys.
Click Create API Key, give it a name, and copy the key.

Shown only once

The full key is displayed only once at creation. Store it immediately in your .env file or secrets manager. If you lose it, delete the key and create a new one. Keys look like SA-<64 hex chars>.

#2. Send your first SMS

One POST with your key in the X-API-Key header is all it takes. Tanzanian numbers are accepted as 0712345678 or +255712345678 — both are normalized automatically.

send.sh

bash

curl -X POST https://api.sendafrica.online/v1/sms/ \
  -H "X-API-Key: $SENDAFRICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0712345678",
    "message": "Hello from SendAfrica! Your order is ready.",
    "from": "MyBrand"
  }'

About the sender ID

Omit from entirely and your message sends from SendAfrika, the platform default. To brand your messages, pass your own sender ID — but it must be registered and authorized first. Unregistered sender IDs are rejected by the carrier, and the message is re-sent under the platform's fallback sender instead of yours.

#3. Read the response

200 OK

json

{
  "success": true,
  "data": {
    "message_id": "SA-f3b1c2d49e8a4f2bb1c2d3e4f5a6b7c8",
    "status": "sent",
    "cost": "TZS 35.00",
    "credits_used": 1
  },
  "request_id": "dfffa252-4781-43ff-8e1a-bf01a754d66a",
  "timestamp": "2026-06-11T16:24:05Z"
}

Field	Description
`message_id`	Unique ID for this message — use it to correlate delivery webhooks
`status`	`"sent"` on success; final delivery confirmation arrives via webhook
`cost`	Carrier cost string from the gateway
`credits_used`	Credits deducted (1 per SMS part by default)

#4. Check your balance

Always check your balance before large batches — you will get an insufficient_credits error mid-batch if you run out:

balance.sh

bash

curl -s https://api.sendafrica.online/v1/credits/balance \
  -H "X-API-Key: $SENDAFRICA_API_KEY"

# { "success": true, "data": { "account_id": "486f...", "balance": 5000 } }

#5. Track delivery with webhooks

A successful send responds with status: "sent" (already submitted to the gateway); delivery updates then arrive via webhook as delivered or failed. Point a webhook URL at your server to receive push-based delivery reports, and verify the signature before trusting the payload:

webhook.py

python

from fastapi import Request

@app.post("/webhooks/sendafrica")
async def webhook(request: Request):
    event = client.webhooks.parse(
        await request.body(),
        signature=request.headers.get("X-SendAfrica-Signature"),
    )

    if event.type == "sms.delivered":
        print(f"Message {event.message_id} delivered")

Next steps

Add an Idempotency-Key header so network retries never double-send, read the error codes table, or jump into bulk sending and campaigns.

Introduction

Integrate with AI Assistants