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.
Message statuses
Section titled “Message statuses”queuedroutedsendingsentdeliveredfailedblocked
| 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.
Poll a message
Section titled “Poll a message”GET /v1/messages/:id returns the message with events[], its full timeline, oldest first. The key needs messages:read.
curl https://api.smsfabric.com/v1/messages/msg_q8v2k4n6p1r3t5w7y9z0b2c4 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const message = await sf.messages.get('msg_q8v2k4n6p1r3t5w7y9z0b2c4');console.log(message.status, message.errorCode);for (const event of message.events) { console.log(event.createdAt, event.type, event.deviceId ?? '');}import osimport requests
res = requests.get( "https://api.smsfabric.com/v1/messages/msg_q8v2k4n6p1r3t5w7y9z0b2c4", headers={"X-Api-Key": os.environ["SMSFABRIC_API_KEY"]}, timeout=30,)res.raise_for_status()message = res.json()print(message["status"], message["errorCode"])for event in message["events"]: print(event["createdAt"], event["type"], event["deviceId"] or "")<?php$ch = curl_init('https://api.smsfabric.com/v1/messages/msg_q8v2k4n6p1r3t5w7y9z0b2c4');curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('SMSFABRIC_API_KEY')], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,]);$message = json_decode(curl_exec($ch), true);echo $message['status'] . "\n";foreach ($message['events'] as $event) { echo $event['createdAt'] . ' ' . $event['type'] . "\n";}{ "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.
Get notified with webhooks
Section titled “Get notified with webhooks”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.
Find messages
Section titled “Find messages”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 same data in the portal
Section titled “The same data in the portal”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.
Failure codes
Section titled “Failure codes”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.