Message statuses

Every message moves from queued to sent to delivered or failed. Here is what each status means and when it fires.

Applies to

message.failed event

1{
2  "type": "message.failed",
3  "data": {
4    "id": "msg_01J9ZK4T7Q",
5    "status": "failed",
6    "failure_code": "carrier_rejected",
7    "channel": "sms",
8    "updated_at": "2026-10-20T14:02:19Z"
9  }
10}

Lifecycle

queued: accepted and waiting to send.
sent: handed to the carrier or mail provider.
delivered: the provider confirmed delivery.
failed: delivery stopped. Check failure_code.
canceled: a scheduled send was canceled before it left.

Failure codes

failure_code is stable and safe to branch on. Common values are carrier_rejected, invalid_recipient, unsubscribed and expired. Messages are never retried after failed.

Timing

Most SMS reach delivered within seconds, but some carriers report late or not at all. Treat sent as final if no update arrives within 24 hours.

Placeholder API

Fernway is a fictional product used to show how this template works. Replace these docs with your own in the CMS.

← Versioning policy

Webhooks →