Skip to content

Quickstart

In this guide you link a phone to your account, create an API key, send a message from your code and follow it in the portal until it is delivered.

  • An SMSFabric account. Sign up at https://app.smsfabric.com/register (account guide).
  • An Android phone with a SIM card and the SMSFabric app installed (install the app).
  • A terminal with curl, or Node.js 20 or later.
  1. In the portal, open Devices and click Pair a phone.

  2. A one-time QR code appears. It lasts 10 minutes.

  3. On the phone, open SMSFabric, tap Scan QR code, then point the camera at the code. No camera? Tap Enter the code instead and type the code shown under the QR.

    Tap Scan QR code.
    Tap Continue and allow the camera.
  4. The portal confirms the phone is paired and lists its SIM cards. The phone shows the gateway online.

    The gateway is online.

Allow the app to ignore battery optimisation when it asks, so Android doesn’t pause it overnight (why).

  1. Open API keys under Developers in the sidebar, then click Create API key.

  2. Name the key after what uses it, and choose Test · sandbox or Live · real SMS.

  3. Tick messages:send and messages:read, then click Create key.

  4. Copy the secret and store it in your secret manager or .env file. It is shown only once. Then click I’ve stored it.

Save it as an environment variable for the next step:

Terminal window
export SMSFABRIC_API_KEY="sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Send to your own mobile number in international format (E.164), for example +201001234567.

Terminal window
curl -X POST https://api.smsfabric.com/v1/messages \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quickstart-001" \
-d '{"to": "+201001234567", "body": "Hello from SMSFabric"}'

SMSFabric answers 201 Created with one message per recipient, in status queued:

{
"data": [
{
"id": "msg_8k2m9xdp4lw1",
"direction": "outbound",
"to": "+201001234567",
"body": "Hello from SMSFabric",
"status": "queued",
"segments": 1,
"encoding": "GSM7",
"createdAt": "2026-11-19T09:41:00.000Z"
}
]
}

The Idempotency-Key header makes retries safe: sending the same request again within 24 hours returns the first result instead of a second SMS (idempotency).

Import a ready-made collection, set the apiKey variable and run Messages › Send a message. See Postman and Insomnia for the steps.

22 ready requests in the order you'd try them, from the first send to campaigns, webhooks and your plan.

  1. Open Messages. Your message is at the top, and its status updates live.

  2. Click the message to open it.

  3. The timeline shows each step: queued, routed, sent and delivered, with the phone and SIM that sent it.

Your code can read the same timeline with GET /v1/messages/:id, or get each change pushed to it by a webhook. See Tracking delivery.

Add an HTTPS endpoint under Webhooks, subscribe it to message.delivered and message.failed, and check the SMSFabric-Signature header on every call. The webhooks guide has the full setup and verification code.

No public URL yet? Run smsfabric listen to get the same events on your machine and forward them to a local server:

Terminal window
smsfabric listen --forward-to http://localhost:3000/hooks/sms --events message.delivered,message.failed