SMS delivery reports for every text

Each outbound text goes through a set of statuses, and every change is written to its timeline with the time it happened. Open any message in history and you'll see the whole story: when it was queued, when it left, when the network confirmed delivery, or the reason it didn't get there.

A delivery report that turns up late, or turns up twice, can't move a text back to an earlier status, so what you see is the furthest point the text reached.

Delivered means the network reported that the text reached the phone. Sent on its own means we've handed it over and are waiting for the network's report.

Message history holds every text in and out of your account:

The texts that didn't arrive are the ones worth a look. Filter message history by undelivered once a campaign has finished and you have the numbers worth checking: a number that's no longer in use, a typo from the original sign-up form, that sort of thing. Fix them in your contacts or take them off the list, and the next send doesn't pay for texts that were never going to arrive.

For one-off texts, the timeline is the answer to 'did they get it?'. If a customer says a reminder never came, open the message and you'll see whether it was delivered and when, which is usually enough to settle it.

One credit covers one SMS part. Numbers refused before sending (landlines, other countries and opted-out numbers) are never charged. A text that fails before it leaves us is refunded automatically, and so is a scheduled text you cancel.

A text the network tried to deliver and couldn't is marked undelivered and isn't refunded, because it went out and the network did the work. Your billing ledger lists every charge and refund line by line, so any balance can be traced back to the texts behind it.

Subscribe a webhook to message.sent, message.delivered and message.failed. The message.failed event covers both kinds of failure, a text that never left (status failed, refunded) and one the network could not deliver (status undelivered, not refunded), and the payload carries the status and an error code so you can tell them apart.

Put your own client_ref on POST /api/v1/messages and it comes back on every event, so you can match reports to orders or bookings without storing our IDs. GET /api/v1/messages/{id} returns one message with its timeline. GET /api/v1/messages lists them and takes direction, status, q (a search), campaign_id, batch_id, client_ref, since and until as filters; the date filters, since and until, are only in the API. GET /api/v1/messages/export gives you the CSV, filtered by direction, status, q, campaign_id, batch_id, since and until.