Delivery and status

Every message ends in one of four states. This page says what each one means and what, if anything, you should do about it.

The four states

Message statuses, in the order a message moves through them.
Field	Type	Description
`pending`	not final	Submitted and on its way. Most messages leave this state within seconds; a busy network can take minutes.
`sent`	not final	Accepted by the network for delivery. It has left us and has not yet been confirmed on a handset.
`delivered`	final	Confirmed on the recipient's handset. This is the only status that is proof of arrival.
`failed`	final	Did not arrive. The detail field says why. Under charged-on-delivery billing this is refunded automatically.

Sent is not delivered

A message can sit at sent and never arrive: the handset may be off, out of coverage, or the number may be on DND for a promotional message. Treat sent as "handed over", not as success.

Why a message fails

The detail on a failed message is the network's own words, which are terse. The common causes:

Field	Type	Description
`Number on DND`	promotional only	The recipient has registered on the Do Not Disturb list. Promotional messages are blocked; service and transactional messages are not affected.
`Handset unreachable`	temporary	Switched off, out of coverage, or storage full, for the whole retry window. Nothing is wrong with the number and a later send may work.
`Invalid number`	permanent	Not a working mobile number. Worth removing from your list rather than retrying.
`Content mismatch`	fixable	The delivered text did not match the approved template. Usually a variable that is too long or contains characters the template does not allow.
`Chain or registration`	fixable	The entity, chain, sender ID or template did not check out at the operator. See Chain declaration; this one fails for every message at once, not for a few.

Messages that stay pending

A delivery report can be lost. The network may drop it, or it may simply never be issued for a given message.

A message with no report is settled automatically after 48 hours. The wait is longer than the network's own retry window on purpose, so that a slow but genuine delivery lands first and keeps its charge rather than being written off early and then arriving.

Under charged-on-delivery billing, a message settled that way is refunded. Under charged-on-send it is not, because that mode charges for acceptance rather than arrival. See Billing and wallet.

A stuck pending message is not lost

It has been submitted. Sending it again produces a second message, and if the first one does arrive the recipient gets two. Wait for it to settle rather than resending.

Reading it in bulk

The Messages page lists a day at a time, newest first, with the status and detail on each. Looking at one day rather than everything is deliberate: it keeps the page fast no matter how long you have been a customer.

Two patterns are worth knowing when scanning a bad day:

Everything failed points at registration: the chain, the sender ID or the template. One fix repairs all of it.
Some failed points at the recipients: DND, unreachable handsets, invalid numbers. There is no single fix, and the mix is normal.

If you send from your own systems, the same information is available per message and per day through the API. See Message status.

Delivery and status

The four states#

Why a message fails#

Messages that stay pending#

Reading it in bulk#

The four states

Why a message fails

Messages that stay pending

Reading it in bulk