Python SDK

pip install sendafrica

pip install sendafrica[async]

import os
from sendafrica import SendAfrica
 
client = SendAfrica(api_key=os.environ["SENDAFRICA_API_KEY"])
 
result = client.sms.send(
    to="0712345678",
    message="Your verification code is 4921.",
)
print(result.message_id, result.status, result.credits_used)

from sendafrica import SendAfrica, AsyncSendAfrica
 
client = SendAfrica(
    api_key="SA-...",              # or omit to read SENDAFRICA_API_KEY
    base_url="https://api.sendafrica.online/v1",
    timeout=10,                    # request timeout in seconds
    max_retries=3,                 # retry on 429 / 5xx / network errors
    debug=True,                    # prints request/response summaries
    webhook_secret="whsec_...",    # used by client.webhooks for signature verification
)
 
# Async variant — same resource API, but every call is awaitable
async_client = AsyncSendAfrica(api_key="SA-...")
await async_client.sms.send(to="0712345678", message="Async send")
await async_client.aclose()  # close httpx transport when done

result = client.sms.send(
    to="0712345678",
    message="Welcome to SendAfrica!",
    sender="SENDAFRICA",  # optional registered sender ID
)
print(result.message_id, result.credits_used)

results = client.sms.send_many(
    messages=[
        {"to": "0712345678", "message": "Hi Ali"},
        {"to": "0765432109", "message": "Hi Zainab"},
    ],
    rate_limit_per_sec=10.0,  # default 10
    sender="MYBRAND",         # applied to all unless per-message overrides
)
print(results.sent_count, results.failed_count)
for r in results.results:
    print(r.message_id, r.to)
for f in results.failed:
    print(f["index"], f["to"], f["error"])

bulk = client.sms.bulk(
    to=["0712345678", "0765432109"],
    message="Black Friday starts now!",
    sender="MYBRAND",
)
print(bulk.total, bulk.sent, bulk.failed)
for r in bulk.results:
    print(r.to, r.status, r.message_id, r.error)

logs = client.sms.logs(
    page=1, per_page=25,
    status="delivered",     # pending | sent | delivered | failed
    search="0712345678",
    date_from="2026-09-01T00:00:00Z",
)
print(logs.total, logs.page, logs.total_pages)
for entry in logs.items:
    print(entry.to_phone, entry.status, entry.credits_used, entry.sent_at)

analysis = client.sms.analyze("Hello world from SendAfrica 🇹🇿")
print(analysis.encoding, analysis.parts, analysis.credits)
# UCS-2 1 1  (emoji forces Unicode encoding)

balance = client.credits.balance()
print(balance.balance, balance.account_id)
 
history = client.credits.history(page=1, per_page=25)
for txn in history:
    print(txn.type, txn.amount, txn.balance_after, txn.description)

rates = client.rates.list()
for r in rates:
    print(r.name, r.iso2, r.rate_tzs)
 
tz = client.rates.get("TZ")
print(tz.name, tz.rate_tzs)

reqs = client.sender_ids.requirements()
print(reqs.eligibility.can_request)
print([r.name for r in reqs.countries])
 
usable = client.sender_ids.usable()
for sid in usable:
    print(sid.name, sid.type, sid.is_default)
 
list = client.sender_ids.list()
 
new_id = client.sender_ids.create(
    name="MYBRAND",
    country="TZ",
    purpose="Marketing",
    sample_message="Welcome to MYBRAND",
    documents=[{"requirement_uid": "...", "filename": "doc.pdf", "content_base64": "..."}],
)
print(new_id.id, new_id.status)
 
one = client.sender_ids.get(new_id.id)
 
client.sender_ids.set_default(new_id.id)

rate = client.payments.rate()
print(rate.min_amount_tzs, [(t.max_amount_tzs, t.rate_tzs_per_credit) for t in rate.tiers])
 
payment = client.payments.create(
    amount=10000,       # TZS — converted to credits server-side
    provider="snippe",  # or "manual"
    phone="0712345678", # required for mobile-money providers
)
print(payment.id, payment.status, payment.credit_amount)

client.payments.send_declared_phone_otp("0765432109")
client.payments.verify_declared_phone_otp("0765432109", "4921")

from flask import request, jsonify
 
@app.route("/webhooks/sms", methods=["POST"])
def handle_webhook():
    payload = request.get_data(as_text=True)
    signature = request.headers.get("X-SendAfrica-Signature", "")
 
    try:
        event = client.webhooks.parse(payload, signature=signature)
    except Exception:
        return jsonify(error="invalid signature"), 401
 
    print(event.type, event.message_id, event.data)
    return jsonify(ok=True), 200

client.webhooks._verify_signature(raw_body, signature, secret)

export SENDAFRICA_API_KEY="SA-..."
 
sendafrica balance
sendafrica sms send --to 0712345678 --message "Hello from CLI" --sender MYBRAND
sendafrica sms logs --status delivered --per-page 50
sendafrica rates
sendafrica sender-ids list
sendafrica sender-ids requirements
sendafrica sender-ids usable

from fastapi import FastAPI
from sendafrica import AsyncSendAfrica
 
app = FastAPI()
client = AsyncSendAfrica(api_key="SA-...")
 
@app.on_event("shutdown")
async def shutdown():
    await client.aclose()
 
@app.post("/send")
async def send():
    result = await client.sms.send(to="0712345678", message="Async hello")
    return {"message_id": result.message_id}

from sendafrica import SendAfricaError
 
try:
    client.sms.send(to="invalid", message="test")
except SendAfricaError as e:
    print(e.status_code, e.request_id, e.message)