Skip to main content

SMS API Overview

The AfriRoute SMS API lets you send text messages to 54+ African countries with enterprise-grade reliability, local sender IDs, Unicode support, and real-time delivery tracking. This page is your starting point: it covers authentication, the available endpoints, message lifecycle, and how the SMS docs are organised.

🚀 Quick Start​

curl -X POST https://api.afriroute.ai/api/v1/sms/send \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+251911234567",
    "from": "AFRIROUTE",
    "text": "Hello from AfriRoute!"
  }'

🔑 Authentication​

Every request must include your secret API key as a Bearer token:

Authorization: Bearer $AFRIROUTE_API_KEY

Keys are managed from the dashboard. Use separate keys for test and production, scope them to the minimum permissions required, and rotate them periodically. Never embed keys in client-side code.

🌐 Base URL​

All endpoints are served over HTTPS from a single base URL:

https://api.afriroute.ai

📡 Endpoints​

MethodPathPurposeReference
POST/v1/sms/sendSend a single messageSend SMS
POST/v1/sms/bulkSend to many recipients in one callBulk SMS
GET/v1/sms/{message_id}Retrieve delivery statusDelivery Reports
GET/v1/sms/sender-idsList / manage sender IDsSender IDs

🔄 Message Lifecycle​

Each message moves through a predictable set of states. Every state change can be pushed to your callback_url.

StatusMeaning
queuedAccepted by AfriRoute and waiting to be dispatched
sentHanded off to the mobile operator
deliveredConfirmed delivered to the handset
failedCould not be delivered (see Error Codes)

📊 Standard Response​

A successful send returns the message resource:

{
  "message_id": "msg_abc123xyz",
  "status": "queued",
  "to": "+251911234567",
  "from": "AFRIROUTE",
  "parts": 1,
  "cost": 0.05,
  "currency": "ETB",
  "created_at": "2026-05-28T10:30:00Z"
}

🧩 SDK Example​

const afriroute = require('@afriroute/sdk');
const client = new afriroute.Client('$AFRIROUTE_API_KEY');

const msg = await client.sms.send({
  to: '+251911234567',
  from: 'AFRIROUTE',
  text: 'Hello from AfriRoute!'
});

console.log(msg.message_id, msg.status);
from afriroute import Client

client = Client("$AFRIROUTE_API_KEY")
msg = client.sms.send(
    to="+251911234567",
    from_="AFRIROUTE",
    text="Hello from AfriRoute!",
)
print(msg.message_id, msg.status)

🌍 Coverage​

54+ African countries with tier-1 carrier connections, including Ethiopia, Kenya, Nigeria, South Africa, Tanzania, Uganda, Ghana, and Rwanda. View full coverage →

💡 Best Practices​

  • Use E.164 phone numbers (e.g. +251911234567) for every recipient.
  • Register a sender ID for higher deliverability (90%+ vs ~60%).
  • Keep messages under 160 GSM-7 characters to stay within a single part.
  • Handle delivery callbacks rather than polling for accurate status.
  • Validate numbers before sending to avoid wasted spend.

🔒 Security & Limits​

  • All traffic is encrypted in transit over TLS.
  • Default rate limit: 100 requests/second per key.
  • API keys can be scoped, restricted by IP, and rotated at any time.

📚 Related Resources​

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