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.
Send one message
Section titled “Send one message”The key needs the messages:send scope. Always send an Idempotency-Key, so a retry after a timeout can’t send twice (see Idempotency).
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" } }'import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const [message] = await sf.messages.send( { to: '+201001234567', body: 'Your order #1042 has shipped. Track it at acme.example/t/1042', metadata: { orderId: '1042' }, }, { idempotencyKey: 'order-1042-shipped' },);console.log(message.id, message.status); // msg_… queuedimport osimport requests
res = requests.post( "https://api.smsfabric.com/v1/messages", headers={ "X-Api-Key": os.environ["SMSFABRIC_API_KEY"], "Idempotency-Key": "order-1042-shipped", }, json={ "to": "+201001234567", "body": "Your order #1042 has shipped. Track it at acme.example/t/1042", "metadata": {"orderId": "1042"}, }, timeout=30,)res.raise_for_status()message = res.json()["data"][0]print(message["id"], message["status"])<?php$payload = json_encode([ 'to' => '+201001234567', 'body' => 'Your order #1042 has shipped. Track it at acme.example/t/1042', 'metadata' => ['orderId' => '1042'],]);$ch = curl_init('https://api.smsfabric.com/v1/messages');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => $payload, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json', 'Idempotency-Key: order-1042-shipped', ], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,]);$message = json_decode(curl_exec($ch), true)['data'][0];echo $message['id'] . ' ' . $message['status'] . "\n";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.
Request fields
Section titled “Request fields”| 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.
Send to many numbers
Section titled “Send to many numbers”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.
Choose the phone
Section titled “Choose the phone”Without routing fields, SMSFabric picks the phone in this order:
simId, ordeviceId, when you give one.poolId: round robin over the pool’s online phones.- The organization’s default SIM (set in Devices, or with
POST /v1/devices/:id/sims/:simId/default). - 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.
Segments and encoding
Section titled “Segments and encoding”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.
Schedule a message
Section titled “Schedule a message”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"}Next steps
Section titled “Next steps”- Track delivery with
GET /v1/messages/:idand webhooks. - Receive replies.
- The full field list is in the messages reference.