Message Lifecycle
Every message — sent or received — has exactly one status at any moment. Outbound and inbound use the same field, but reach it from opposite directions.
Outbound
| Status | Meaning |
|---|---|
| queued | Written to the queue. Waiting for the owning SIM's next poll. |
| sending | A SIM has claimed it and is transmitting it. |
| sent | The phone's radio confirmed transmission to the carrier. |
| delivered | A delivery receipt came back from the recipient's carrier network. |
| failed | Every retry was used. See below for what leads here. |
Delivered isn't universalNot every carrier network sends a delivery receipt back. A message stuck at sent with no further update usually did arrive — the absence of delivered is not itself evidence of failure.
How a message reaches failed
Two distinct paths lead here:
- The SIM tried and couldn't. A transmission error (no signal, malformed number, carrier rejection) was reported back directly.
- The phone went silent. A SIM that claims a message and then never reports back — killed process, dead battery, SIM pulled — leaves that message in
sending. Connecfy notices this lazily (the next time any of that account's SIMs polls for work) once 3 minutes pass with no report, and puts the message back in the queue for another SIM to try. This happens up to 3 times total before the message is markedfailedwith reason "Delivery timeout."
Inbound
Simpler — there's only one state. A received text is written directly as:
received — the terminal, and only, status for inbound messages. There's no queued/sending phase because nothing was ever dispatched; the SIM is just reporting something that already happened. See Receiving SMS.
Checking status
Poll GET /api/v1/sms/<message_id>/ with your API key. There's no webhook for status changes today — see Building Reliable Integrations for a sane polling interval.