Tracking
Message status and delivery reports
| status | Meaning | Final | Charged |
|---|---|---|---|
| scheduled | Waiting for send_at. | No | Yes, refunded if canceled |
| queued | Accepted and waiting for the next queue pass (every two seconds). | No | Yes |
| sent | Handed to the network; waiting for the delivery report. | No | Yes |
| delivered | The handset confirmed delivery. | Yes | Yes |
| failed | Could not be delivered; error says why. | Yes | No, refunded |
| canceled | Its scheduled batch was canceled. | Yes | No, refunded |
Error codes on messages
| error.code | Meaning |
|---|---|
| network_error | The message could not be handed to the network. Its price is back in the balance. |
| undeliverable | The network reported that the handset could not be reached. |
| canceled | The scheduled batch was canceled before it started. |
Refunds
When a message fails, its full price goes back to the balance in the same pass, as a refund line in the ledger that names the batch. The batch field refunded shows the running total.
Webhooks or polling
Webhooks are the fast path: each final status calls your endpoint once it is set. For small volumes, or to double-check, poll GET /v1/messages/{id} or GET /v1/batches/{id}; the rate limit leaves room for both.