Scheduling SMS notices through the API: send_at, time zones and when credits are charged

The short answer: add the send_at field to the send, with the date, time and time zone in ISO 8601, such as 2026-11-20T09:30:00+02:00. The date must be in the future and no more than 365 days ahead. The message becomes scheduled, and credits are only taken when it goes out.

A scheduled request

curl https://api.mozout.com/v1/sms/messages \
-H "Authorization: Bearer sandbox_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: consulta-5812-vespera" \
-d '{"number": "841234567", "text": "Reminder: your appointment is tomorrow at 10:00.", "send_at": "2026-11-20T09:30:00+02:00"}'

The answer carries the message id, the status scheduled and the planned time in scheduled_for. Store the id in your system next to the booking or invoice: you need it to look the notice up or cancel it.

The time zone

The end of the timestamp says which zone the time is in. Mozambique is on +02:00 and Angola on +01:00: the same "09:30" with the wrong offset goes out an hour early or late. If your system stores dates in UTC, you can send UTC with a trailing Z, as long as the conversion is right.

What happens until the time comes

Moment	What happens
When you schedule	The API only checks that the balance is enough. Nothing is taken: charged stays false.
Meanwhile	The balance shows, in scheduled_credits, what is scheduled and not yet taken.
At the time	The message goes out and the credits are taken.
At the time, balance short	The message is not sent and ends up failed, with the error insufficient_credits.

Scheduling errors

Reason (details.reason)	What it means
invalid_send_at	The date is not in a valid format. Check the ISO 8601 and the offset.
send_at_in_past	The date has passed. If you want it out now, send without send_at.
send_at_too_far	The date is more than 365 days away.

These come back with status 422. The other SMS errors are listed in SMS API errors and message statuses.

Keep enough balance for notices already scheduled. A reminder booked weeks ago fails at send time if the balance ran out in the meantime. See how to watch the balance in what automatic notices cost.

Test with a sandbox_ key. The API checks everything and answers, but sends and charges nothing.

Want your notices to go out on their own at the right time? See the API page.

See the API page

Categories

Categories