Send SMS

Send a single SMS message to one recipient. This is the most common SMS operation: ideal for OTPs, transactional alerts, and notifications. For sending to many recipients in one request, use Bulk SMS.

📡 Endpoint

POST /v1/sms/send

Base URL: https://api.afriroute.ai

🔑 Authentication

Authorization: Bearer $AFRIROUTE_API_KEY
Content-Type: application/json

📥 Request Parameters

Field	Type	Required	Description
to	string	Yes	Recipient phone number in E.164 format (e.g. +251911234567)
from	string	Yes	Registered sender ID or phone number (alphanumeric, 3-11 chars)
text	string	Yes	Message content (up to 1600 characters / multiple parts)
callback_url	string	No	Webhook URL to receive delivery reports
metadata	object	No	Custom key-value data echoed back in callbacks

📤 Example Request

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": "Your OTP is 123456. Valid for 5 minutes.",
    "callback_url": "https://yourapp.com/webhooks/sms",
    "metadata": { "order_id": "ord_9981" }
  }'

const response = await fetch('https://api.afriroute.ai/api/v1/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $AFRIROUTE_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+251911234567',
    from: 'AFRIROUTE',
    text: 'Your OTP is 123456. Valid for 5 minutes.',
    callback_url: 'https://yourapp.com/webhooks/sms'
  })
});

const data = await response.json();
console.log(data.message_id); // msg_abc123xyz

import requests

response = requests.post(
    'https://api.afriroute.ai/api/v1/sms/send',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={
        'to': '+251911234567',
        'from': 'AFRIROUTE',
        'text': 'Your OTP is 123456. Valid for 5 minutes.',
        'callback_url': 'https://yourapp.com/webhooks/sms',
    },
)
print(response.json()['message_id'])

✅ Response

200 OK

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

Field	Description
message_id	Unique identifier; use it to fetch status
status	One of queued, sent, delivered, failed
parts	Number of message segments billed
cost	Total cost for this message
currency	ISO 4217 currency code (e.g. ETB)

🔢 Message Segments

Standard GSM-7 messages fit 160 characters per part. Including any non-GSM (Unicode) character switches the message to UCS-2 encoding, reducing capacity to 70 characters per part. Longer text is split into concatenated parts, and you are billed per part (parts in the response).

💡 Best Practices

• Validate numbers in E.164 format before sending.
• Use a registered sender ID for the best deliverability — see Sender IDs.
• Keep transactional messages under 160 characters to bill a single part.
• Always set callback_url so you receive delivery confirmations.
• Attach metadata (e.g. order or user IDs) to reconcile callbacks with your records.

⚠️ Error Handling

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "The 'to' field is not a valid E.164 number",
    "timestamp": "2026-05-28T10:30:00Z"
  }
}

HTTP	Code	Resolution
400	INVALID_PHONE	Use E.164 format including country code
400	INVALID_SENDER_ID	Register or correct your sender ID
401	UNAUTHORIZED	Check your API key
402	INSUFFICIENT_BALANCE	Top up your account
429	RATE_LIMITED	Retry with exponential backoff

See the full list in Error Codes.

📚 Related Resources

• SMS API Overview
• Bulk SMS
• Delivery Reports
• Sender IDs

---

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