Skip to content

Messages

A message is one SMS to or from one number. Outbound messages move through queued, routed, sending, sent and end delivered, failed or blocked; inbound messages are received. See Track delivery.

Field Type Description
id string msg_…
direction string outbound or inbound.
to string Recipient, E.164. For inbound: your SIM’s number, or "" when unknown.
from string or null For inbound: the sender. null for outbound.
body string The text. Verification messages show [verification code hidden].
status string queued, routed, sending, sent, delivered, failed, blocked or received.
segments integer SMS parts the body is split into.
encoding string GSM7 or UCS2.
deviceId string or null The phone that sent or received it.
simId string or null The SIM used.
provider string or null device, or sandbox for sf_test_ keys. null until routed.
errorCode string or null Why it failed or was blocked. See failure codes.
createdAt string When it was accepted.
sentAt string or null When the carrier accepted it.
deliveredAt string or null When the handset confirmed it.
metadata object or null Your own JSON from the send request. Campaign messages carry campaignId; verification messages carry verificationId.
POST/v1/messagesmessages:send

Queues a message for each recipient. Returns 201 with one message per recipient, in request order. Supports Idempotency-Key. Recipients on the blacklist come back with status: "blocked" and errorCode: "blacklisted"; the rest are queued.

Body field Type Required Description Constraints
to string or string[] Yes Recipient numbers. E.164; 1 to 100 numbers.
body string Yes The text. 1 to 1,600 characters.
deviceId string No Send from this phone. Must belong to your organization.
simId string No Send from this SIM. Must belong to your organization.
poolId string No Round robin over the pool’s online phones, with failover. Must belong to your organization.
scheduledAt string No Send at this time. ISO 8601, at most one year ahead.
metadata object No Returned on the message and in webhooks. JSON object, at most 4 KB.
Terminal window
curl https://api.smsfabric.com/v1/messages \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-shipped" \
-d '{"to": ["+201001234567", "+201001234568"], "body": "Your order #1042 has shipped.", "metadata": {"orderId": "1042"}}'
{
"data": [
{
"id": "msg_q8v2k4n6p1r3t5w7y9z0b2c4",
"direction": "outbound",
"to": "+201001234567",
"from": null,
"body": "Your order #1042 has shipped.",
"status": "queued",
"segments": 1,
"encoding": "GSM7",
"deviceId": null,
"simId": null,
"provider": null,
"errorCode": null,
"createdAt": "2026-11-19T10:15:02.114Z",
"sentAt": null,
"deliveredAt": null,
"metadata": { "orderId": "1042" }
},
{
"id": "msg_j4l6n8p1r3t5v7x9z2b4d6f8",
"direction": "outbound",
"to": "+201001234568",
"from": null,
"body": "Your order #1042 has shipped.",
"status": "blocked",
"segments": 1,
"encoding": "GSM7",
"deviceId": null,
"simId": null,
"provider": null,
"errorCode": "blacklisted",
"createdAt": "2026-11-19T10:15:02.118Z",
"sentAt": null,
"deliveredAt": null,
"metadata": { "orderId": "1042" }
}
]
}
Error When
400 validation_failed An invalid number (errors[].field is to[<index>]), more than 100 recipients, an empty or too long body, metadata over 4 KB, or scheduledAt more than a year ahead. Nothing is sent.
404 not_found deviceId, simId or poolId is not in your organization.
409 idempotency_in_progress, 422 idempotency_key_reused See Idempotency.
GET/v1/messagesmessages:read

Returns messages newest first, paginated.

Query Type Description
direction string outbound or inbound.
status string One message status.
deviceId string Messages routed to or received by this phone.
campaignId string Messages sent by this campaign.
q string A phone number or part of it (3 to 15 digits, optional +), matched in to and from.
from string Created at or after this ISO 8601 time.
to string Created at or before this ISO 8601 time.
limit integer 1 to 200, default 50.
cursor string nextCursor from the previous page.
Terminal window
curl "https://api.smsfabric.com/v1/messages?status=failed&limit=2" \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
{
"data": [
{
"id": "msg_k5m7o9q2s4u6w8y1a3c5e7g9",
"direction": "outbound",
"to": "+966501234567",
"from": null,
"body": "Your appointment is confirmed for 20 November at 09:30.",
"status": "failed",
"segments": 1,
"encoding": "GSM7",
"deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9",
"simId": "sim_r2t4v6x8z1b3d5f7h9j2l4n6",
"provider": "device",
"errorCode": "no_service",
"createdAt": "2026-11-19T09:58:40.002Z",
"sentAt": null,
"deliveredAt": null,
"metadata": null
}
],
"nextCursor": null
}
GET/v1/messages/:idmessages:read

Returns the message with events[], its timeline, oldest first. Each event has id (evt_…), type, status (or null for routing steps), deviceId, detail and createdAt.

Path Type Description
id string The message id.
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.",
"status": "sent",
"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": null,
"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_a5c7e9g2i4k6m8o1q3s5u7w9", "type": "sent", "status": "sent", "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "detail": { "source": "device" }, "createdAt": "2026-11-19T10:15:05.870Z" }
]
}
Error When
404 not_found No such message in your organization.
GET/v1/messages/statsmessages:read

Daily counts for the last days UTC days, ending today, plus totals over the same period. Outbound sent counts messages that are sending, sent or delivered.

Query Type Description
days integer 1 to 31, default 7.
Terminal window
curl "https://api.smsfabric.com/v1/messages/stats?days=3" \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
{
"days": [
{ "date": "2026-11-17", "sent": 412, "delivered": 398, "failed": 6 },
{ "date": "2026-11-18", "sent": 530, "delivered": 511, "failed": 9 },
{ "date": "2026-11-19", "sent": 188, "delivered": 170, "failed": 2 }
],
"totals": { "sent": 1130, "delivered": 1079, "failed": 17, "queued": 14, "received": 63 }
}
GET/v1/messages/export.csvlogs:export

Streams every message that matches the filters as text/csv. Takes the same query filters as List messages, without limit and cursor. Cells that start with =, +, - or @ get a leading ' so spreadsheets don’t run them as formulas; that includes phone numbers.

Terminal window
curl "https://api.smsfabric.com/v1/messages/export.csv?from=2026-11-01T00:00:00Z&to=2026-11-30T23:59:59Z" \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-o messages-november.csv
id,direction,to,from,body,status,segments,encoding,deviceId,simId,provider,errorCode,createdAt,sentAt,deliveredAt
msg_q8v2k4n6p1r3t5w7y9z0b2c4,outbound,'+201001234567,,Your order #1042 has shipped.,delivered,1,GSM7,dev_m4p7s2v5y8b1e4h7k0n3q6t9,sim_r2t4v6x8z1b3d5f7h9j2l4n6,device,,2026-11-19T10:15:02.114Z,2026-11-19T10:15:05.870Z,2026-11-19T10:15:09.402Z