Skip to content

Track delivery

Sending returns as soon as the message is queued. Everything after that, from a phone picking it up to the handset’s delivery report, happens asynchronously. You can follow it two ways: ask for the message, or let SMSFabric call you with a webhook.

  1. queued
  2. routed
  3. sending
  4. sent
  5. deliveredfailedblocked
Every outbound message ends in one terminal status: delivered, failed or blocked.
Status Meaning
queued Accepted and waiting: for a phone, for scheduledAt, or for the send window.
routed Assigned to a phone (and SIM), which has been told to send it.
sending The phone has handed it to the radio.
sent The carrier accepted it.
delivered The handset confirmed delivery. Final.
failed It could not be sent. errorCode says why. Final.
blocked Never sent because of your blacklist, an opt-out or a canceled campaign. errorCode says which. Final.
received An inbound message from someone else. Final. See Receive messages.

Statuses only move forward. A late report from a phone that would move a message backwards is ignored.

GET /v1/messages/:id returns the message with events[], its full timeline, oldest first. The key needs messages:read.

Terminal window
curl https://api.smsfabric.com/v1/messages/msg_q8v2k4n6p1r3t5w7y9z0b2c4 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
{
"id": "msg_q8v2k4n6p1r3t5w7y9z0b2c4",
"direction": "outbound",
"to": "+201001234567",
"from": null,
"body": "Your order #1042 has shipped. Track it at acme.example/t/1042",
"status": "delivered",
"segments": 1,
"encoding": "GSM7",
"deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9",
"simId": "sim_r2t4v6x8z1b3d5f7h9j2l4n6",
"provider": "device",
"errorCode": null,
"createdAt": "2026-11-19T10:15:02.114Z",
"sentAt": "2026-11-19T10:15:05.870Z",
"deliveredAt": "2026-11-19T10:15:09.402Z",
"metadata": { "orderId": "1042" },
"events": [
{ "id": "evt_w1y3a5c7e9g2i4k6m8o1q3s5", "type": "queued", "status": "queued", "deviceId": null, "detail": null, "createdAt": "2026-11-19T10:15:02.120Z" },
{ "id": "evt_x2z4b6d8f1h3j5l7n9p2r4t6", "type": "routed", "status": "routed", "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "detail": { "simId": "sim_r2t4v6x8z1b3d5f7h9j2l4n6" }, "createdAt": "2026-11-19T10:15:02.141Z" },
{ "id": "evt_y3a5c7e9g2i4k6m8o1q3s5u7", "type": "dispatched", "status": null, "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "detail": { "channel": "ws" }, "createdAt": "2026-11-19T10:15:02.380Z" },
{ "id": "evt_z4b6d8f1h3j5l7n9p2r4t6v8", "type": "sending", "status": "sending", "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "detail": { "source": "device" }, "createdAt": "2026-11-19T10:15:05.210Z" },
{ "id": "evt_a5c7e9g2i4k6m8o1q3s5u7w9", "type": "sent", "status": "sent", "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "detail": { "source": "device" }, "createdAt": "2026-11-19T10:15:05.870Z" },
{ "id": "evt_b6d8f1h3j5l7n9p2r4t6v8x1", "type": "delivered", "status": "delivered", "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "detail": { "source": "device" }, "createdAt": "2026-11-19T10:15:09.402Z" }
]
}

Besides status changes, the timeline records routing steps. These have status: null or status: "routed":

Event type Meaning
routed Assigned to a phone; detail.simId is the SIM.
wake_sent The phone was offline and was woken by push.
dispatched The phone took the message (detail.channel is ws or pull).
ack_timeout, device_rejected The phone did not accept the message in time, or refused it.
rerouted Moved to another phone in the pool (detail.from, detail.reason).
retry Sent again after the phone reported a failure (detail.reason).

Poll sparingly: every few seconds for a message a user is waiting on, and stop at a final status. For anything at volume, use webhooks. Polls count toward your rate limit.

Subscribe a webhook endpoint to these events and SMSFabric posts the message to you on each change:

Event Sent when the message becomes
message.queued queued
message.sent sent
message.delivered delivered
message.failed failed
message.received received (inbound)

The event’s data is the message, in the same shape as GET /v1/messages/:id without events, including your metadata. Use metadata to find the order, user or ticket the message belongs to.

{
"id": "evt_c7e9g2i4k6m8o1q3s5u7w9y2",
"type": "message.delivered",
"createdAt": "2026-11-19T10:15:09.455Z",
"orgId": "org_n5q8t1w4z7c0f3i6l9o2r5u8",
"data": {
"id": "msg_q8v2k4n6p1r3t5w7y9z0b2c4",
"status": "delivered",
"to": "+201001234567",
"deliveredAt": "2026-11-19T10:15:09.402Z",
"metadata": { "orderId": "1042" }
}
}

(data is shortened here.) routed, sending and blocked have no webhook. A blocked message is already final in the 201 response to your send.

Set up endpoints and verify their signatures in Webhooks.

GET /v1/messages lists messages newest first, with filters:

Query Example Matches
status failed One status.
direction inbound outbound or inbound.
deviceId dev_m4p7… Messages routed to this phone.
campaignId cmp_… Messages from one campaign.
q 4567 A phone number or part of it, in to or from.
from, to 2026-11-01T00:00:00Z Created in this date range.

It is paginated with limit and cursor (see Pagination). GET /v1/messages/stats?days=7 returns daily sent, delivered and failed counts, and GET /v1/messages/export.csv streams the same filters as CSV with the logs:export scope.

The portal’s Messages screen reads the same API, so what you see there is what your code gets:

In the API In the portal
GET /v1/messages with filters The Messages list with Status, Direction, Device, From date, To date and Search by number
status The Status column
deviceId and simId The Route column (Not routed yet while queued)
segments The Parts column
events[] The Timeline in the message drawer
errorCode Error in the message drawer
GET /v1/messages/export.csv Export CSV

The list updates live. See Messages in the portal for a walkthrough.

errorCode on a failed or blocked message:

errorCode Status Meaning
blacklisted blocked The number is on your blacklist.
opted_out blocked The recipient replied STOP (campaign messages).
campaign_canceled blocked The campaign was canceled before a phone took the message.
no_device_available failed No enabled phone could take the message.
device_unavailable failed The assigned phone was disabled or unpaired.
device_unpaired failed The phone was unpaired before it took the message, and no other online phone in its pool could. Resend it.
device_rejected failed The phone refused the message.
radio_off, no_service, generic_failure, limit_exceeded, null_pdu, short_code_not_allowed, short_code_never_allowed failed Reported by Android when the SIM could not send. Check signal, airplane mode and the SIM’s balance.
sim_not_found failed The chosen SIM is no longer in the phone.
tenant_suspended failed The organization was suspended.

See Troubleshooting for fixes.