Send Messages

Choose A Send Mode

Shared Prerequisites

• API key has SMS access.
• Account has enough credits for all calculated segments.
• Sender ID resolves to an approved sender available to the authenticated customer.
• Every message contains 1-918 characters.
• Recipients comply with the countries enabled for the deployment.

The service defaults to Tanzania-only recipients. Confirm enabled destinations with Notify Africa before integrating another country.

Send One SMS

Use the compatibility request when integrating directly, or use an official SMS SDK:

{
  "phone_number": "255712345678",
  "message": "Your verification code is 482901",
  "sender_id": "MYBRAND"
}

The endpoint also accepts canonical fields:

{
  "recipient": "+255712345678",
  "content": "Your verification code is 482901",
  "senderId": "MYBRAND",
  "scheduledAt": "2026-09-10T08:00:00.000Z"
}

Compatibility phone fields may omit +. Canonical recipient values require E.164 format with +.

Send Identical Content To Many Recipients

{
  "phone_numbers": [
    "255712345678",
    "255713456789"
  ],
  "message": "Your order is ready for collection",
  "sender_id": "MYBRAND"
}

The response summarizes accepted messages and the resulting debit:

{
  "status": 200,
  "message": "Batch messages sent successfully",
  "timestamp": "2026-09-09T12:10:00.000Z",
  "path": "/api/v1/api/messages/batch",
  "data": {
    "messageCount": 2,
    "creditsDeducted": 2,
    "remainingBalance": 498
  }
}

This response does not return the message UUIDs. Use personalized bulk sending when the integration must retain one UUID per recipient.

Send Personalized Messages

{
  "senderId": "MYBRAND",
  "messages": [
    {
      "recipient": "+255712345678",
      "content": "Hello Asha, order ORD-1001 is ready"
    },
    {
      "recipient": "+255713456789",
      "content": "Hello Baraka, order ORD-1002 is ready"
    }
  ]
}

Example response data:

{
  "acceptedCount": 2,
  "rejectedCount": 0,
  "results": [
    {
      "messageId": "d9b54c80-8a63-4f8b-83c8-71f2439f5429",
      "status": "sent",
      "estimatedSegments": 1,
      "debitApplied": true
    },
    {
      "messageId": "91f22458-a942-4ac2-9fdf-df260da5a2de",
      "status": "sent",
      "estimatedSegments": 1,
      "debitApplied": true
    }
  ],
  "creditsDeducted": 2,
  "remainingBalance": 498
}

The shared HTTP envelope wraps this object in data.

Schedule A Bulk Send

Add one ISO date-time for the entire canonical request:

{
  "senderId": "MYBRAND",
  "messages": [
    {
      "recipient": "+255712345678",
      "content": "Your appointment starts tomorrow at 09:00"
    }
  ],
  "scheduledAt": "2026-09-10T06:00:00.000Z"
}

Scheduled results start with status: "scheduled". Send an explicit UTC offset or Z; the API validates ISO syntax but does not reject past timestamps.

Recipient Filtering

• A single unsupported recipient rejects the request.
• Bulk processing rejects the request when no recipient is eligible.
• A mixed bulk request can continue with eligible recipients and count unsupported recipients as rejected.
• The same-content batch response does not expose the rejected-recipient count.

Validate destinations before sending and use /send-bulk when per-recipient results matter.