SMS API Reference

Base URL

https://tools.tornevall.net/api/sms

Authentication

Remote SMS integrations use the dedicated SMS core API credential. Ordinary Tools API-key scopes do not authorize SMS send/status or inbound gateway requests.

Send the dedicated credential in one of these headers:

Authorization: Bearer YOUR_API_TOKEN

or:

X-Api-Key: YOUR_API_TOKEN

The legacy apikey request parameter remains accepted where the endpoint contract already supported it, but header-based authentication is recommended for new integrations.

Authenticated Tools web sessions and explicitly trusted internal access paths are separate from the remote API credential contract.

POST /send

Queue an SMS for sending.

Request

POST /api/sms/send
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "destination": "+46701234567",
  "message": "Hello from API",
  "class": "-1",
  "central": "",
  "incident": false
}

Fields

Field	Required	Type	Notes
`destination`	Yes	string	Recipient phone number
`message`	Yes	string	Message text, maximum 512 characters
`class`	No	string	SMS message class
`central`	No	string	Optional SMS central name
`incident`	No	boolean	Mark the message as an incident. Incident messages are intended for urgent operational alerts and bypass application-level incident cooldowns where supported.

Before the text is written to the SMSTools queue, Tools normalizes characters that the current modem path does not handle reliably. Swedish letters are preserved. Unicode quotes, dash variants, and selected GSM extension-table characters are converted to readable basic characters instead of risking ? substitutions on the receiving handset.

Response

{
  "success": true,
  "pduid": 4106,
  "incident": false,
  "message": "SMS queued for sending"
}

A queued incident message is persisted with incident=1. This flag identifies urgent messages in the outgoing queue; it is not a carrier delivery receipt.

Errors

401 Unauthorized when the remote credential is missing or invalid
422 Unprocessable Entity when request validation fails
500 when the message cannot be queued

GET /{pduid}/status

Read the current status of an outgoing SMS.

Request

GET /api/sms/{pduid}/status
Authorization: Bearer YOUR_API_TOKEN

Response

{
  "pduid": 4106,
  "recipient": "+46701234567",
  "message": "Hello from API",
  "status": "queued",
  "incident": false,
  "tries": 0,
  "created_at": 0,
  "updated_at": 1709035200
}

Typical status values include queued, spooled, and unknown.

Tools also observes the SMSTools queue periodically and can record when an outbound row receives new attempts/timestamps or leaves pduout. This is queue/modem-side evidence and must not be treated as a carrier delivery receipt.

POST /inbound

The inbound gateway endpoint uses the same dedicated SMS core API credential. The request body is the SMS gateway webhook payload expected by Tools.

A normal Tools API token does not gain inbound gateway access by carrying an SMS-related scope value.

Admin: unknown-prefix AI fallback

Administrators can configure the optional unknown-prefix AI fallback from the SMS admin interface. This does not change the public inbound request authentication or payload contract.

Tornevall Networks