Why an SMS answer says queued: the sending queue, batches and what to tell your customer

The short answer: queued means the request was accepted and the message is in the queue, waiting its turn. It is not an error and you do not repeat the request. Without scheduling, the API tries to send at once and answers with the real status: sent if it went out, failed if it failed, or queued if it has to wait. Your system keeps the id and checks the status later.

When a message waits in the queue

Situation	What happens
A single send	It usually goes out straight away; if it has to wait its turn, you get queued.
A batch send (POST /v1/sms/messages/batch)	The messages join the queue, which is sent every minute; up to 20 go out straight away. The rest follow over the next minutes.
A message that fails on the way out	It is tried 2 more times, 10 minutes apart. If it still fails, it ends up failed and the credits go back to the balance.

What to tell the customer

On your website or app screen, do not say «we have sent you an SMS» just because the request was accepted. A more honest line works better: «You will receive the confirmation by SMS in a moment.» If the status later turns failed, your system can offer another route, such as e-mail.

Do not send again just because the answer said queued. The message is already on its way: a second request with a different Idempotency-Key gives the customer two texts and doubles the credits. If you retry after a dropped connection, always reuse the same key.

Following it through to the end

1	Store the id from the answer, with the event.

2	Check the status with GET /v1/sms/messages/{id} a few minutes later, or register a webhook to be told when each SMS is sent or fails.

3	For a batch, read results: each message has its index (its position in the request), its id and its status, or rejected with the reason in error.

4	If it ends up failed, read the reason, fix whatever is on your side and decide whether to resend or use another channel.

The statuses, one by one, are in tracking each transactional SMS.

Urgent notices one at a time; notices that can wait, in a batch. A single send at the moment of the event tries to go out at once; a batch is for many notices together, which then go through the queue over the following minutes.

Want notices that go out on their own, with a clear status for each? See Transactional SMS.

See Transactional SMS

Categories

Categories