Sending SMS

Endpoints

The two endpoints accept the same body and behave the same way; only the type field of the response differs. Reading status, batches and cancelling are covered in messages and batches.

Request

curl -X POST https://api.sendozi.com/v1/sms/bulk \
  -H "Authorization: Bearer $SENDOZI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: term-two-reminder-2026-09-24" \
  -d '{
    "sender": "Greenfield",
    "recipients": ["08012345678", "+2349012345678", "2347012345678"],
    "message": "Term two resumes on Monday 5 October. Fees are due by Friday.",
    "route": "promotional"
  }'

Response

A send that is accepted returns 202 with the batch it created. Nothing has been delivered yet: the batch is queued, and its recipients are handed to the network within moments (live promotional sends wait for the delivery window).

{
  "success": true,
  "data": {
    "batch_id": "bat_9b1f2a4c6d8e0f13",
    "channel": "sms",
    "mode": "production",
    "status": "queued",
    "requested_count": 3,
    "accepted_count": 3,
    "duplicates_removed": 0,
    "invalid_count": 0,
    "suppressed_count": 0,
    "dnd_skipped_count": 0,
    "consent_rejected_count": 0,
    "estimated_cost_kobo": 2100,
    "reserved_cost_kobo": 2100,
    "progress": { "queued": 3, "processing": 0, "sent": 0, "delivered": 0, "failed": 0, "skipped": 0 },
    "type": "bulk"
  },
  "request_id": "req_6fddf1f66c77787f"
}

How recipients are handled

Nigerian mobile numbers only. Each number is normalised to +234 form, then invalid numbers, repeats and opted-out numbers are removed and counted. The send goes ahead for everyone left; it is refused only if nobody is left.

• Accepted spellings: 08012345678, 8012345678, 2348012345678, +2348012345678, 002348012345678, and +234 0803... with the zero kept after the country code. Spaces, dashes and brackets are ignored. 0700 and 0800 numbers are not mobiles and are counted as invalid.
• A valid number is a Nigerian mobile number on a 070, 071, 080, 081, 090 or 091 prefix. Anything else, including international numbers, is counted in invalid_count.
• A number that appears twice, in any spelling, is sent once and counted in duplicates_removed.
• A number that has opted out of SMS from your workspace is removed and counted in suppressed_count.
• On a live promotional send, a number that returned a Do Not Disturb block to your workspace in the last 90 days is skipped and counted in dnd_skipped_count. The message that met the block was charged; the repeats are not sent.
• If no valid number is left, the send returns 400 invalid_recipient; if every valid number has opted out, 400 recipient_suppressed.

Routes and Sender IDs

• promotional is for campaigns, offers and announcements to your own audience. The Console sends promotional SMS only.
• transactional is for one person's own event: an OTP, a payment alert, a receipt. Through the API it takes exactly one recipient and an Idempotency-Key; the text is your own. See transactional SMS.
• A Sender ID is approved for one route. A transactional approval also sends promotional, except to Airtel until Airtel whitelists it: those numbers are left out and counted in sender_network_skipped_count. A promotional-only Sender ID used for transactional returns 403 sender_id_route_mismatch; one that is not approved at all returns 403 sender_id_not_approved.
• A Sender ID created before the routes were separated reports sms_route "unclassified" and returns 403 sender_id_unclassified until Sendozi records its route.
• Both routes cost the same.

Message length and pages

SMS is billed at ₦7.00 per page per recipient. A page is one message on the network: 160 characters in GSM-7, or 70 if the text contains any character outside GSM-7 - an emoji, a curly quote, a tone-marked letter. GSM-7 extension characters (^ { } \ [ ~ ] | €) count as two, and an emoji counts as two in Unicode.

A longer message is refused with 400 invalid_request, never truncated. Messages are also checked against a short list of high-risk phrases; a match returns 400 message_policy_violation.

How a send is charged

1. 1

   Reserved on acceptance

   A live send reserves estimated_cost_kobo from the wallet when it is accepted. If the balance does not cover it, the send returns 403 insufficient_balance and nothing is queued.

2. 2

   Charged per recipient

   Each recipient is charged its price when it is handed to the network, and charged even if the network later reports it undelivered.

3. 3

   Not charged

   A recipient refused before it reached the network, skipped because the number opted out after the send was accepted, or cancelled is not charged.

4. 4

   Released

   When the batch finishes or is cancelled, whatever part of the reservation was not charged goes back to the wallet. actual_cost_kobo on the batch is the final charge.

Large sends

• One request carries up to 1,000,000 recipients and at most 32 MB. A larger audience is several requests, each with its own Idempotency-Key.
• A large request takes longer to accept, because every recipient is checked and written before the batch starts. Allow a client timeout of a few minutes, and retry with the same Idempotency-Key if it times out.
• Recipients are handed to the network at a steady platform-wide rate, and every workspace's batches share it fairly, so a large campaign does not hold up another customer's send and your transactional SMS is always sent first.