Public REST API for the inst8 SMS gateway — send and receive SMS/MMS through your own Android device fleet from any CRM or application.
\nAll endpoints require a Bearer token:
\nAuthorization: Bearer i8_...
Request a token from your account manager. Tokens are scoped (send, read, webhooks) and rate-limited (default 120 requests/min; 429 + Retry-After when exceeded; X-RateLimit-* headers on every response).
Sends are asynchronous: POST /messages.php validates, queues, and returns 202 with a message id per recipient. Messages are paced per SIM by the gateway (roughly one send per 30 seconds per SIM) to protect number health — this pacing cannot be bypassed. Track progress by polling GET /messages.php?id=... or via webhooks.
Message lifecycle: queued → Pending/Scheduled → Sent → Delivered (or Failed). Note: Delivered depends on carrier delivery reports, which many carriers under-report; absence of Delivered does not mean the message failed.
Send an Idempotency-Key header (max 64 chars) with POST /messages.php to make retries safe — a replayed key returns the original result instead of re-sending.
All responses: {\"success\": bool, \"data\": {...}, \"error\": {\"code\", \"message\"} | null}.
Register an HTTPS URL to receive message.received (inbound SMS) and message.status (outbound status changes) events, dispatched about once per minute, signed with X-Api-Signature: sha256=HMAC_SHA256(rawBody, secret). Delivery is at-least-once — de-duplicate on the message id. A webhook failing 20 consecutive dispatch runs is disabled automatically.
Validates the token and returns the account (credits, expiry) plus token metadata (scopes, rate limit). Requires scope: read.
Lists the account's devices with their enabled SIMs (device id + sim slot identify a sending line; use them to pin a send to a specific SIM). last_seen is the device's last check-in and is informational only. Requires scope: read.
Optional but recommended — makes retries safe
\n"}],"body":{"mode":"raw","raw":"{\n \"to\": \"+15551234567\",\n \"message\": \"Hello from the API!\"\n}"},"url":"https://inst8-sms.com/api/v1/messages.php","description":"Queues one SMS. Returns 202 with data.messages[0].id — poll that id or use webhooks for status. With no device_id the gateway rotates across your healthy SIMs automatically. Requires scope: send.
Up to 100 recipients per request; each recipient becomes its own message with its own id, spread across your healthy SIMs. 207 is returned if only some could be queued (retry the failed ones). Requires scope: send.
device_id (+ optional sim_slot) pins the send to one of your SIMs from GET /devices.php. schedule is a future unix timestamp. Requires scope: send.
type: mms with attachments (array of public media URLs). Requires scope: send.
One outbound message by its id (from the send response). status: queued/failed while in the API pipeline, then the gateway status (Pending, Scheduled, Sent, Delivered, Failed). Requires scope: read.
Cursor-paginated list of messages sent through the API. Requires scope: read.
1-200
\n","type":"text/plain"},"key":"limit","value":"50"},{"disabled":true,"description":{"content":"resume from data.next_cursor
\n","type":"text/plain"},"key":"cursor","value":"0"},{"disabled":true,"description":{"content":"optional status filter
\n","type":"text/plain"},"key":"status","value":"Delivered"}],"variable":[]}},"response":[],"_postman_id":"10e96c65-bba7-4aea-9481-b0e3be40fc37"},{"name":"List inbound (received) messages","id":"8d1d5d76-edfc-4eb1-970d-31f759b921e2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://inst8-sms.com/api/v1/messages.php?direction=inbound&since_id=0&limit=50","description":"Polling alternative to the message.received webhook: SMS received on your SIMs, ascending by id. Persist next_since_id between polls. Requires scope: read.
resume from data.next_since_id
\n","type":"text/plain"},"key":"since_id","value":"0"},{"description":{"content":"1-200
\n","type":"text/plain"},"key":"limit","value":"50"}],"variable":[]}},"response":[],"_postman_id":"8d1d5d76-edfc-4eb1-970d-31f759b921e2"}],"id":"ff3361aa-92e9-46da-b585-482c41f2baa1","_postman_id":"ff3361aa-92e9-46da-b585-482c41f2baa1","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"i8_YOUR_TOKEN_HERE"}]},"isInherited":true,"source":{"_postman_id":"36cff270-2839-413b-83f0-1d61e56668a1","id":"36cff270-2839-413b-83f0-1d61e56668a1","name":"inst8 SMS Public API v1","type":"collection"}}},{"name":"Webhooks","item":[{"name":"List webhooks","id":"e62ed8eb-fdbb-4b1f-b485-b69f314dddc0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://inst8-sms.com/api/v1/webhooks.php","description":"Lists registered webhooks (secrets are only shown at creation). Requires scope: read.
Registers an HTTPS endpoint. The response contains the signing secret ONCE — store it and verify X-Api-Signature: sha256=HMAC_SHA256(rawBody, secret) on every delivery. Events arrive batched about once per minute; delivery is at-least-once. Max 5 active webhooks. Requires scope: webhooks.
Removes a webhook by id. Requires scope: webhooks.
Numbers that will be silently skipped on sends (your STOP list — inbound STOP replies land here automatically). Requires scope: read.
1-500
\n","type":"text/plain"},"key":"limit","value":"100"},{"disabled":true,"description":{"content":"resume from data.next_cursor
\n","type":"text/plain"},"key":"cursor","value":"0"}],"variable":[]}},"response":[],"_postman_id":"a0732bd7-ba4b-4d6c-90ab-f89908cfd17d"},{"name":"Add number to blacklist","id":"740aa55c-a5f1-49e7-8593-10fb32187656","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"number\": \"+15551234567\"\n}"},"url":"https://inst8-sms.com/api/v1/blacklist.php","description":"Opt a number out — future sends to it are skipped. Requires scope: send.
Re-enables sending to a previously opted-out number. Requires scope: send.