Sending many SMS notices in one API request: the batch endpoint and its results

The short answer: POST /v1/sms/messages/batch takes many messages in a single request, each with its own number and, if you like, its own text. There is no limit on the number of messages, only on the request size (1 MB). The answer tells you, in results, what happened to each one.

What the request looks like

curl https://api.mozout.com/v1/sms/messages/batch \
-H "Authorization: Bearer sandbox_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: avisos-vencimento-2026-11-17" \
-d '{"text": "Your invoice is due tomorrow.",
"send_at": "2026-11-20T08:00:00+02:00",
"messages": [{"number": "841234567"},
{"number": "ANOTHER_NUMBER", "text": "Hi Ana, your invoice is due tomorrow."}]}'

Field	What it does
text	The text for every message that does not bring its own.
sender	Optional: an approved sender for all of them. Without it, the free NETMSG sender is used.
send_at	Optional: schedules them all for the same time, as in a single send.
messages	The list. Each entry has a number and, optionally, its own text.

What happens next

1	Each message is checked against the same rules as a single send: valid number, text, sender, words that are not allowed, numbers that opted out.

2	Up to 20 go out straight away; the rest join the queue, which sends every minute.

3	If the balance runs out or the daily limit is reached halfway down the list, the remaining messages are rejected.

4	In results you see what happened to each one, with the same error reasons as a single send.

Always read results. A batch can succeed for most messages and fail for a few. Store each number's outcome in your system, so you neither resend the ones that went out nor forget the ones that failed.

Batch or one request per message?

Situation	What to use
One notice at a time, when something happens	POST /v1/sms/messages
The day's reminders, the list of expiries, an alert to the whole team	POST /v1/sms/messages/batch
A campaign prepared by hand	The SMS page in My MozOut, with a contact group

A batch also saves requests: the account has a per-minute request limit, and a list sent in one request counts as one. The single send is covered in sending SMS through the API.

Personalise in your own system. Since each entry can carry its own text, build each customer's message (name, amount, date) before sending the batch. With a sandbox_ key, nothing is sent or charged.

Have lots of notices to send at once? See the API page.

See the API page

Categories

Categories