SMS delivery statuses

Every message has a status. It starts as QUEUED and ends in a status that says whether it reached the phone. A team webhook gets message.sent, message.delivered and message.failed. A sender webhook gets every change as message.status. UNKNOWN sends no event.

You're charged once the network accepts a message (SENT). A message the network never accepts ends as FAILED, and the charge is refunded.

What each status means

Status	Meaning	Charged?
Queued	Ponitor accepted it and is handing it to the network.	Held
Sent	The network accepted it. The delivery report hasn't arrived yet.	Yes
Delivered	The network confirmed it reached the phone.	Yes
Expired	The phone was off or out of coverage until the message expired.	Yes
Undelivered	The network couldn't deliver it, for example to an unknown or barred number.	Yes
Unknown	No delivery report arrived within 48 hours. Networks don't report every message, so it may have arrived.	Yes
Failed	The network never accepted it.	No, refunded

• DELIVERED, EXPIRED, UNDELIVERED and FAILED are final. UNKNOWN usually is too, but a late report moves it to DELIVERED, EXPIRED or UNDELIVERED.
• Ponitor holds the charge when you send. It keeps it when the network accepts the message, and refunds it if the message ends as FAILED. A request refused with a 4xx error is never charged.
• We may add statuses. Treat a status you don't recognise as not final.

WhatsApp messages use the same statuses, with a few differences. See WhatsApp statuses.

Why a message wasn't delivered

An EXPIRED, UNDELIVERED or FAILED message has a failureCode, and a failedReason in plain words that you can show your users. Branch on failureCode, not on the reason's text, which can change. Errors lists every code, what it means and what to do.

Status	failureCode
EXPIRED	E11001 the phone was off or out of coverage
UNDELIVERED	E11002 the number doesn't exist · E11004 can't receive SMS · E11017 barred · E11011 not deliverable · E11012 rejected · E11013 cancelled by the network
FAILED	E11003 invalid number · E11006 Sender ID refused · E11007 network busy · E11008 network unreachable · E11009 not confirmed · E11010 refused · E11015 not sent

E11009, "The network did not confirm the message", means the network never answered, so the message may or may not have gone out. This is rare, and it isn't charged.

Following a message

• In production, use a webhook. A team webhook gets message.sent, message.delivered and message.failed. A sender webhook gets message.status for each change.
• For a one-off check, call Get a message. It returns the current status, failureCode, failedReason and cost. Don't call it in a loop.

A message usually reaches SENT within seconds. If the phone is off, the network keeps trying until the message expires, then reports EXPIRED. A message still SENT after 48 hours becomes UNKNOWN.

Try it in the sandbox

Send to	What happens
+231880000100, the Simulator	QUEUED, then SENT, then DELIVERED, a few seconds apart.
+231770000001	It ends as UNDELIVERED, with a failedReason.
+231770000002	It stays SENT, with no delivery report, and becomes UNKNOWN after 48 hours.

See Magic numbers.