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.
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.
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.
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.
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.
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