REST · JSON

API documentation

Queue outbound SMS with a simple JSON API. Authenticate with a per-client API key, debit one credit per message, and optionally schedule delivery. Create a free account for 10 test credits, then mint a key in the dashboard.

https://smsreactor.com/smsapi/

Authentication

Client endpoints require an API key in the request header (or, for quick tests, as a query parameter).

Header

X-API-Key: skr_your_key_here

Alternative (less preferred):

Query

?api_key=skr_your_key_here

Keys are created under Dashboard → API keys (clients) or Clients → Manage (admin). The raw key is shown once at creation.

Send SMS

POST /smsapi/create-task

Queues one SMS. Costs 1 credit on success. Delivery is handled by the local worker / Android gateway.

Request body

Field	Type	Required	Description
`recipient`	string	yes	Destination number, preferably E.164 (e.g. `+381611234567`).
`message`	string	yes	SMS body text.
`phone_id`	integer	no	Preferred gateway. Must be assigned to your client (VIP). Otherwise the API picks your VIP pool (LRU) or the shared pool.
`scheduled_at`	string	no	Local datetime `YYYY-MM-DD HH:MM:SS` (or `YYYY-MM-DDTHH:MM`). Omit for ASAP.

Request JSON

{
  "recipient": "+381611234567",
  "message": "Hello from SMSReactor!",
  "scheduled_at": "2026-07-26 18:30:00"
}

Success response

HTTP 201 Created

Response JSON

{
  "ok": true,
  "id": 42,
  "status": "pending",
  "phone_id": 1,
  "client_id": 3,
  "scheduled_at": "2026-07-26 18:30:00",
  "credits_remaining": 9
}

Credits

Each successful create-task debits 1 credit.
If the worker later reports the task as failed, that credit is refunded once.
Free self-serve accounts start with 10 credits for testing.
Insufficient balance returns HTTP 402.

Errors

Errors are JSON objects with an error string (and sometimes detail).

HTTP	When
`400`	Missing/invalid fields (e.g. bad `scheduled_at`).
`401`	Missing or invalid API key / worker token.
`402`	Not enough credits.
`405`	Wrong HTTP method.
`500`	Unexpected server error.
`503`	Worker path: no active gateway configured.

Example

{
  "error": "Insufficient credits"
}

Examples

cURL

bash / Windows curl

curl -X POST https://smsreactor.com/smsapi/create-task \
  -H "Content-Type: application/json" \
  -H "X-API-Key: skr_your_key_here" \
  -d '{
    "recipient": "+381611234567",
    "message": "Hello from SMSReactor!"
  }'

JavaScript (fetch)

javascript

const res = await fetch("https://smsreactor.com/smsapi/create-task", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "skr_your_key_here",
  },
  body: JSON.stringify({
    recipient: "+381611234567",
    message: "Hello from SMSReactor!",
  }),
});
const data = await res.json();
console.log(res.status, data);

PHP

php

$ch = curl_init("https://smsreactor.com/smsapi/create-task");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "X-API-Key: skr_your_key_here",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "recipient" => "+381611234567",
        "message" => "Hello from SMSReactor!",
    ]),
]);
$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $code, "\n", $body;

Worker endpoints

These are for the local SMS worker on your LAN (e.g. cron.php), not for application integrations. They require X-Worker-Token, not an API key.

Method	Path	Purpose
GET	`/smsapi/pending-tasks`	Claim one due pending task; returns gateway URL. Idle → `{}`.
POST	`/smsapi/task-status`	Report `sent` or `failed` for a claimed task.
POST	`/smsapi/inbound`	Inbound webhook / inbox sync target (Android gateway).