Developer documentation

Build with the InboxIQ API

SMS

Send bulk SMS

Send many messages in one request. InboxIQ groups them into a batch, sends them in the background and keeps count of what was delivered.

POST/api/v1/send-sms/bulk

Request

Send a JSON array of messages. Each message has its own number and text.

[ ]arrayRequired

The request body is a JSON array. Each item is one message.

[ ].destinationstringRequired

The phone number for this message, for example 263771234567.

[ ].messageTextstringRequired

The text for this message. Each item can have different text, so you can personalise every message.

curl -X POST https://api.inboxiq.co.zw/api/v1/send-sms/bulk \
-H "Authorization: Basic $(echo -n 'username:password' | base64)" \
-H "key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{
"destination": "263771234567",
"messageText": "Hi Tariro, your order #5120 is ready for collection."
},
{
"destination": "263712345678",
"messageText": "Hi Tendai, your order #5121 is ready for collection."
},
{
"destination": "263731234567",
"messageText": "Hi Rudo, your order #5122 is ready for collection."
}
]'

Response

The response comes back straight away with the new batch. The messages are then queued and sent in the background, so the counts start at zero.

Response · 200 OK
{
"batchReference": "B00042",
"batchStatus": "PENDING",
"numberOfSms": 3,
"delivered": 0,
"failed": 0,
"unknownDelivery": 0
}
batchReferencestring

The reference for this batch. Use it to check progress with GET /api/v1/batches.

batchStatusstring

The overall status of the batch, for example PENDING, SENDING, SENT or COMPLETED.

numberOfSmsnumber

How many messages are in the batch.

deliverednumber

How many have been delivered so far.

failednumber

How many could not be sent or delivered.

unknownDeliverynumber

How many were sent but the network did not confirm delivery.

Tracking the batch

Save the batchReference and check it with Check a batch, or open Bulk Batches in the dashboard to see every message and download the batch report.

Good practice

  • Validate and de-duplicate numbers before sending. Every item in the array is one SMS and uses one credit.
  • Only send marketing messages to people who agreed to receive them, and honour requests to stop.
  • Large lists are fine in one request. InboxIQ splits them into chunks and sends them for you.
  • Make sure your account has enough credit for the whole list before you send.