Message statuses
pending → claimed → sent → delivered
↘ failed ↘ (expired before it was sent)
| Status | Meaning | Final? |
|---|---|---|
pending | Waiting in the queue for a phone. | no |
claimed | A phone has taken it and is sending it. | no |
sent | The phone sent it and the mobile network accepted it. | usually; becomes delivered if a delivery report arrives |
delivered | The network reported delivery to the handset. | yes |
failed | It could not be sent; error says why. | yes, except for a late sent (below) |
expired | ttlSec passed before any phone sent it. | yes, except for a late sent (below) |
Not every network sends delivery reports. A message can stay sent for good even though it arrived: treat sent as success and delivered as confirmation.
Failover: SIMs and phones#
A failure doesn't immediately mean failed:
- Another SIM. A phone with two SIMs tries the message on its other SIM before it reports a failure.
- Another phone. If another phone of your workspace is online and hasn't tried this message yet, the failure is recorded as
attempt_failedand the message goes back to the queue for that phone. Only when every online phone has tried it does it becomefailed. - A silent phone. If the phone holding a message stops pulling for more than 2 minutes, the message goes back to the queue (
requeued) for the others.
Some errors would fail the same way on every phone, so they are final at once: invalid_phone, missing_text, text_too_long, unknown_template, missing_var.
A message sent with deviceId is never handed to another phone.
Expiry#
A message that isn't sent within ttlSec (default 24 hours; 5 minutes for OTP codes unless you choose otherwise) becomes expired with error: "expired". Expiry is checked every 30 seconds, whether or not a phone is online.
Late "sent"#
A phone can report success after the message already counted as failed or expired, for example when it was offline while sending. A late sent is always accepted: the message becomes sent, because the SMS really went out. delivered is never downgraded.
Each change to sent, delivered, failed or expired is also sent as a webhook.