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.
Before you start
Section titled “Before you start”- 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. Pair a phone
Section titled “1. Pair a phone”-
In the portal, open Devices and click Pair a phone.
-
A one-time QR code appears. It lasts 10 minutes.
-
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. -
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).
2. Create an API key
Section titled “2. Create an API key”-
Open API keys under Developers in the sidebar, then click Create API key.
-
Name the key after what uses it, and choose Test · sandbox or Live · real SMS.
-
Tick
messages:sendandmessages:read, then click Create key. -
Copy the secret and store it in your secret manager or
.envfile. It is shown only once. Then click I’ve stored it.
Save it as an environment variable for the next step:
export SMSFABRIC_API_KEY="sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"3. Send your first SMS
Section titled “3. Send your first SMS”Send to your own mobile number in international format (E.164), for example +201001234567.
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"}'npm install @smsfabric/sdkimport { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const [message] = await sf.messages.send( { to: '+201001234567', body: 'Hello from SMSFabric' }, { idempotencyKey: 'quickstart-001' },);console.log(message?.id, message?.status);import osimport requests
response = requests.post( "https://api.smsfabric.com/v1/messages", headers={ "X-Api-Key": os.environ["SMSFABRIC_API_KEY"], "Idempotency-Key": "quickstart-001", }, json={"to": "+201001234567", "body": "Hello from SMSFabric"}, timeout=30,)response.raise_for_status()message = response.json()["data"][0]print(message["id"], message["status"])<?php$ch = curl_init('https://api.smsfabric.com/v1/messages');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json', 'Idempotency-Key: quickstart-001', ], CURLOPT_POSTFIELDS => json_encode(['to' => '+201001234567', 'body' => 'Hello from SMSFabric']),]);$message = json_decode(curl_exec($ch), true)['data'][0];echo $message['id'] . ' ' . $message['status'] . PHP_EOL;package main
import ( "bytes" "crypto/rand" "encoding/json" "fmt" "io" "log" "net/http" "os")
func main() { payload, _ := json.Marshal(map[string]string{"to": "+201001234567", "body": "Hello from SMSFabric"}) req, err := http.NewRequest("POST", "https://api.smsfabric.com/v1/messages", bytes.NewReader(payload)) if err != nil { log.Fatal(err) } req.Header.Set("X-Api-Key", os.Getenv("SMSFABRIC_API_KEY")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", newUUID())
res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() raw, _ := io.ReadAll(res.Body) if res.StatusCode/100 != 2 { log.Fatalf("send failed: %s %s", res.Status, raw) } var out struct{ Data []struct{ ID, Status string } } if err := json.Unmarshal(raw, &out); err != nil || len(out.Data) == 0 { log.Fatalf("unexpected response: %s", raw) } fmt.Println(out.Data[0].ID, out.Data[0].Status)}
func newUUID() string { b := make([]byte, 16) rand.Read(b) b[6], b[8] = b[6]&0x0f|0x40, b[8]&0x3f|0x80 return fmt.Sprintf("%x-%x-%x-%x-%x", b[:4], b[4:6], b[6:8], b[8:10], b[10:])}import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.util.UUID;import java.util.regex.Matcher;import java.util.regex.Pattern;
public class Send { public static void main(String[] args) throws Exception { String json = """ {"to":"+201001234567","body":"Hello from SMSFabric"}"""; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.smsfabric.com/v1/messages")) .header("X-Api-Key", System.getenv("SMSFABRIC_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", UUID.randomUUID().toString()) .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() / 100 != 2) { throw new IllegalStateException("Send failed: " + response.statusCode() + " " + response.body()); } Matcher message = Pattern.compile("\"id\":\"([^\"]+)\".*?\"status\":\"([^\"]+)\"").matcher(response.body()); if (!message.find()) { throw new IllegalStateException("Unexpected response: " + response.body()); } System.out.println(message.group(1) + " " + message.group(2)); }}using System;using System.Net.Http;using System.Text;using System.Text.Json;
using var client = new HttpClient();using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.smsfabric.com/v1/messages");request.Headers.Add("X-Api-Key", Environment.GetEnvironmentVariable("SMSFABRIC_API_KEY"));request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());request.Content = new StringContent( JsonSerializer.Serialize(new { to = "+201001234567", body = "Hello from SMSFabric" }), Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);var text = await response.Content.ReadAsStringAsync();if (!response.IsSuccessStatusCode){ throw new HttpRequestException($"Send failed: {(int)response.StatusCode} {text}");}
using var json = JsonDocument.Parse(text);var message = json.RootElement.GetProperty("data")[0];var id = message.GetProperty("id").GetString();var status = message.GetProperty("status").GetString();Console.WriteLine($"{id} {status}");require "json"require "net/http"require "securerandom"
uri = URI("https://api.smsfabric.com/v1/messages")request = Net::HTTP::Post.new(uri, { "X-Api-Key" => ENV.fetch("SMSFABRIC_API_KEY"), "Content-Type" => "application/json", "Idempotency-Key" => SecureRandom.uuid,})request.body = JSON.generate({ to: "+201001234567", body: "Hello from SMSFabric" })
response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }abort "Send failed: #{response.code} #{response.body}" unless response.is_a?(Net::HTTPSuccess)
message = JSON.parse(response.body)["data"][0]puts "#{message["id"]} #{message["status"]}"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).
Prefer Postman or Insomnia?
Section titled “Prefer Postman or Insomnia?”Import a ready-made collection, set the apiKey variable and run Messages › Send a message. See Postman and Insomnia for the steps.
- Download the Postman collection (
smsfabric.postman_collection.json, Collection v2.1) - Download the Insomnia collection (
smsfabric.insomnia.json, v4 export)
22 ready requests in the order you'd try them, from the first send to campaigns, webhooks and your plan.
4. Watch it in the portal
Section titled “4. Watch it in the portal”-
Open Messages. Your message is at the top, and its status updates live.
-
Click the message to open it.
-
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.
5. Get delivery updates by webhook
Section titled “5. Get delivery updates by webhook”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:
smsfabric listen --forward-to http://localhost:3000/hooks/sms --events message.delivered,message.failed