Get Started

Prerequisites

• Notify Africa account with available SMS credits.
• Sender ID approved for sending.
• API key with SMS access.
• Server environment that can protect the API key.
• Tanzanian recipient while Tanzania-only delivery is enabled for your environment.

Complete Portal Setup

Before calling the Developer API:

1. Fund the account in the Notify Africa Portal.
2. Request a sender ID and wait for approval.
3. Create an API key with SMS access.
4. Copy the key when shown and store it in a secret manager.

Do not call Portal account-management operations from your integration.

Configure Environment

export NOTIFY_API_BASE_URL="https://api.notify.africa"
export NOTIFY_SMS_API_KEY="ntfy_your_api_key"
export NOTIFY_SMS_SENDER_ID="your_approved_sender"

Use the base URL assigned to your environment when it differs from the production example.

Required Headers

Authorization: Bearer ntfy_your_api_key
Content-Type: application/json

Content-Type is required for requests with a JSON body.

Send Your First SMS

curl --request POST \
  "$NOTIFY_API_BASE_URL/api/v1/api/messages/send" \
  --header "Authorization: Bearer $NOTIFY_SMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{
    \"phone_number\": \"255712345678\",
    \"message\": \"Hello from Notify Africa\",
    \"sender_id\": \"$NOTIFY_SMS_SENDER_ID\"
  }"

Example response:

{
  "status": 202,
  "message": "SMS sent successfully",
  "timestamp": "2026-09-09T12:00:00.000Z",
  "path": "/api/v1/api/messages/send",
  "data": {
    "messageId": "d9b54c80-8a63-4f8b-83c8-71f2439f5429",
    "status": "SENT"
  }
}

The initial status depends on scheduling and provider submission. Store data.messageId; it is the UUID used for status requests.

Check Delivery Status

curl --request GET \
  "$NOTIFY_API_BASE_URL/api/v1/api/messages/status/d9b54c80-8a63-4f8b-83c8-71f2439f5429" \
  --header "Authorization: Bearer $NOTIFY_SMS_API_KEY"

The API does not expose an SMS callback endpoint. Poll status at a controlled interval until the message reaches a terminal state.

Checklist

• Account has enough credits for every calculated segment.
• Sender ID is approved and usable by the account that owns the API key.
• API key starts with ntfy_ and has SMS access.
• Request uses Bearer authentication.
• Message contains 1-918 characters.
• Returned message UUID is stored before polling.