API integration reference

Live document — route values and availability below reflect the gateway's current configuration. AI agents and tooling should ingest /llms.txt, the machine-readable version of this page.

Authentication

Every request needs an X-API-Key header with your account's sg_… key (issued in admin → Accounts). Responses are JSON: {"status", "message", "data"}.

Live routes

Every SIM in the gateway is listed below — one row per SIM slot. Pass a route label as the sim field when sending to pick the outbound number, "any" for least-loaded, or omit it for your account default. Unlabeled SIMs can't be targeted directly but still carry "any"/default traffic. Online devices right now: 1 (offline after 10 min without a heartbeat).

Route (sim value)SIM slotCarrierHourly capStatus
unlabeled — via "any"/default only 0 T-Mobile Wi-Fi Calling 25/hr online
bg-primary 1 T-Mobile 25/hr online

Endpoints

EndpointDescription
POST /api/v1/messages Enqueue an outbound SMS. Returns 201 with the message row, or 200 replaying the original when client_ref matches a prior send (idempotent).
  • to — required — destination number, E.164 (bare 10-digit US numbers are auto-prefixed +1)
  • body — required — message text; long bodies are split into parts automatically
  • sim — optional — a route label from the routes table, a route phone number, or "any" for least-loaded; omit for the account default
  • client_ref — optional — idempotency key (max 64 chars); re-POSTing the same value returns the original message instead of sending twice
GET /api/v1/messages?id=N Fetch one message (status polling).
GET /api/v1/messages List messages, newest first, paged.
  • status — optional — filter: pending|pushed|sending|sent|delivered|failed|canceled
  • to — optional — filter by destination number
  • since — optional — created_at >= this datetime (server time, America/New_York)
  • page — optional — 1-based page number
  • per_page — optional — default 50, max 200
POST /api/v1/messages?id=N&action=cancel Cancel a message that is still queued (pending/pushed). Already-sending messages cannot be canceled.
GET /api/v1/status Preflight: 24h queue counts for your account, your default route with online state, and the number of online devices.
GET /api/v1/inbound Pull-style inbound SMS list for your account (push-style delivery happens via your webhook), newest first, paged.
  • since — optional — created_at >= this datetime
  • from — optional — filter by sender number
  • page — optional — 1-based page number
  • per_page — optional — default 50, max 200

Message lifecycle

Status walks pending → pushed → sending → sent → delivered (or exits to failed / canceled). Always send a client_ref on transactional messages — retrying the same reference can never double-send.

Webhooks

Set a webhook URL + signing secret on your account for push delivery of inbound and status events. Verify X-SG-Signature (HMAC-SHA256 of the raw body) before trusting a payload. Non-2xx deliveries retry with backoff (1m, 5m, 15m, 1h, 6h). Full verification snippet in /llms.txt.

HTTP status codes