Your message says delivered and your customer says it never arrived

When you submit a message, the network path returns a status for it. On our platform that status is one of nine documented states, and a receipt carries a final state with the gateway error code where one exists. All of it is published on the message state reference, which is the page to read alongside this one.

A receipt tells you what the network did with the message. It does not tell you that the recipient read it, that the message was displayed, or that the right person was holding the phone. It is a transport report, and the transport ends at the handset. Everything after that point, including whether the message landed in the inbox, a spam folder or a thread the recipient never opened, is invisible to us and to every other provider.

That distinction matters most in the one case people actually complain about: a receipt that says delivered, and a customer who says nothing arrived. Both can be true at once.

Nine states are documented on the platform, numbered 0 to 8. Only one of them is a report that the message reached the destination device.

Pending deserves one line of its own. A message in state 0 is not necessarily undelivered. It can also mean the operator has simply not returned a final status yet, which is the normal state for a message sitting in a queue at the network.

State 6 is the one that misleads people most often. Accepted is a terminal state, and it is a deliberate fallback: the record closes because no receipt will ever arrive. It is not a stage on the way to a receipt, so a sender who reads it as progress will keep polling for something that is never coming.

The practical consequence is that a high accepted count on a route means the networks are not returning receipts on that traffic. It does not mean the messages landed, and it does not mean they failed. It means the answer is unknown, and the honest way to report it is as unknown rather than folded into a delivery rate.

Our side of the boundary is narrow and completely observable: what was submitted, when, to which number, from which sender ID, the state the network returned, and any gateway error code. The other side is the device, and a message can be received by a handset that is not in the recipient's hand, not switched on, out of coverage, or holding a full message store. In each case the network can still report delivery, because the message was accepted by the device.

On top of that, modern phones filter. A message from an unfamiliar alphanumeric sender can be sorted into a separate folder by the handset or by a messaging app the customer uses by default. Nothing in the delivery path sees that decision.

UK numbers add one more wrinkle: because numbers are portable, the prefix no longer tells you which network issued the number, or where it sits now. Routing based on number ranges is approximate by nature, which is one reason we do not publish per-network delivery percentages.

When a customer reports that a message never arrived, these five fields turn a conversation into an investigation. Send them and the sequence can be reconstructed without guesswork.

The message ID from the submission response. The destination number in international format, without a leading zero or plus sign where your interface strips it. The submit time with the timezone. The final state from the receipt, not just the word delivered. The sender ID that was used, because a substituted or rejected sender ID is visible in the receipt and nowhere else.

With those, the first question has a factual answer: did the network report state 2, or did it report accepted, rejected or expired? If it reported 2, the message reached the handset and the next questions are about the device. If it reported accepted, no receipt came back and the message may or may not have landed.