Skip to main content

Python SDK

The official afriroute package provides a clean, Pythonic client for SMS, Voice, WhatsApp, and Email — with automatic retries and Bearer-token authentication handled for you.

Installation​

pip install afriroute

Requires Python 3.8 or newer. We recommend a virtual environment:

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install afriroute

Authentication​

Initialize the client with your API key. It is sent as Authorization: Bearer $AFRIROUTE_API_KEY against https://api.afriroute.ai.

from afriroute import Afriroute

client = Afriroute("$AFRIROUTE_API_KEY")

Target the sandbox or tune behavior with keyword arguments:

client = Afriroute(
    "$AFRIROUTE_API_KEY",
    base_url="https://api.afriroute.ai",
    timeout=60,
    max_retries=5,
)
tip

Load your key from the environment: Afriroute(os.environ["AFRIROUTE_API_KEY"]).

Send an SMS​

response = client.sms.send(
    to="+251900000000",
    message="Hello from AfriRoute",
    sender_id="AfriRoute",
)

print(response["message_id"])

Send a WhatsApp Message​

wa = client.whatsapp.send(
    to="+251900000000",
    message="Hello via WhatsApp",
)

print(wa["message_id"])

Make a Voice Call​

call = client.voice.call(
    to="+251900000000",
    from_number="+1234567890",
    tts_message="Welcome to AfriRoute",
)

print(call["call_id"])

Send an Email​

email = client.email.send(
    to="[email protected]",
    subject="Welcome",
    body="<h1>Hello</h1>",
)

print(email["message_id"])

Error Handling​

Failed requests raise AfriRouteError, which exposes code, message, and status:

from afriroute import Afriroute, AfriRouteError

client = Afriroute("$AFRIROUTE_API_KEY")

try:
    client.sms.send(
        to="+251900000000",
        message="Hello",
        sender_id="AfriRoute",
    )
except AfriRouteError as e:
    if e.code == "INVALID_PHONE_NUMBER":
        print("Use E.164 format, e.g. +251911234567")
    elif e.code == "INSUFFICIENT_BALANCE":
        print("Top up your account")
    elif e.code == "RATE_LIMIT_EXCEEDED":
        print("Slow down — retried automatically")
    else:
        print(f"{e.code}: {e.message}")

Transient failures (429, 5xx) are retried automatically up to max_retries with exponential back-off.

Features​

  • Pythonic, keyword-argument API
  • Automatic retries with exponential back-off
  • Built-in rate-limit (429) handling
  • Configurable base URL, timeout, and retries
  • Works in scripts, Django, Flask, and FastAPI

Last Updated: May 2026 · Need help? Contact Support →