Skip to content

Send messages

POST /v1/messages queues a text for one recipient or up to 100. The API answers right away with 201 Created and one message per recipient. A phone then picks the message up and sends it, and you follow it through tracking and webhooks.

The key needs the messages:send scope. Always send an Idempotency-Key, so a retry after a timeout can’t send twice (see Idempotency).

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",
"body": "Your order #1042 has shipped. Track it at acme.example/t/1042",
"metadata": { "orderId": "1042" }
}'

The response:

{
"data": [
{
"id": "msg_q8v2k4n6p1r3t5w7y9z0b2c4",
"direction": "outbound",
"to": "+201001234567",
"from": null,
"body": "Your order #1042 has shipped. Track it at acme.example/t/1042",
"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" }
}
]
}

deviceId, simId and provider fill in once the message is routed to a phone.

Field Type Required Description
to string or string[] Yes One number, or an array of 1 to 100. E.164 format (+201001234567); every number is checked with libphonenumber.
body string Yes 1 to 1,600 characters. Split into SMS segments automatically.
deviceId string No Send from this phone (dev_…).
simId string No Send from this SIM (sim_…). Implies its phone.
poolId string No Send through this pool, round robin over its online phones, with failover.
scheduledAt ISO 8601 date No Hold the message until this time. At most one year ahead.
metadata object No Your own JSON, up to 4 KB. Returned on the message and in every webhook about it.

An unknown deviceId, simId or poolId returns 404 not_found, also when it belongs to another organization. An invalid number returns 400 validation_failed with errors[].field set to to[<index>], and nothing is sent.

Pass an array. You get one message per recipient, in the same order, each with its own id and status.

{
"to": ["+201001234567", "+201001234568", "+966501234567"],
"body": "The Nasr City branch opens at 10:00 tomorrow."
}

A number on your blacklist does not fail the request. Its message comes back with status: "blocked" and errorCode: "blacklisted" and never leaves the server; the others are queued.

For more than 100 recipients, or for personalised text, use a campaign.

Without routing fields, SMSFabric picks the phone in this order:

  1. simId, or deviceId, when you give one.
  2. poolId: round robin over the pool’s online phones.
  3. The organization’s default SIM (set in Devices, or with POST /v1/devices/:id/sims/:simId/default).
  4. Round robin over all online phones.

If no phone is online, the most recently seen one is woken by push and the message waits for it. If no phone can take the message at all, it fails with errorCode: "no_device_available".

Sending with poolId adds failover: if a phone does not accept the message within 10 seconds, rejects it, or goes offline, the message moves to another online phone in the pool. When a phone reports a send failure, the message is retried up to maxRetries times (default 2, in preferences), on another pool phone when there is one, otherwise on the same phone.

Each phone keeps a cooldown between messages (default 3 s plus up to 2 s of jitter) to protect your SIMs. Plan throughput around it: one phone sends about 14 messages a minute with the defaults. Add phones to a pool to send faster.

The API reports how the carrier will bill the text:

Encoding Used when One segment Each segment of a longer text
GSM7 Every character is in the GSM 03.38 alphabet 160 characters 153 characters
UCS2 Any other character, including Arabic and emoji 70 characters 67 characters

^ { } \ [ ] ~ | € count as two GSM characters. One Arabic letter switches the whole text to UCS2, so a 71-character Arabic message is 2 segments.

Set scheduledAt to send later. The message stays queued until then. If your organization has a send window in preferences, messages outside it wait for the window to open.

{
"to": "+201001234567",
"body": "Reminder: your appointment is tomorrow at 09:30.",
"scheduledAt": "2026-11-20T07:00:00Z"
}