Setup guide · Developer API
Get started with the inst8 Developer API
Send your first API message in about ten minutes: create a token, call the send endpoint, register a webhook for replies. The full endpoint reference lives in our Postman documentation.
Step-by-step
- 1
Create an API token
In the inst8 dashboard, open Integrations → Developer API and click ‘Create Token’. Pick the permissions it needs (send, read, webhooks) and copy the token — it's shown only once.
- 2
Authenticate
Send the token as a bearer header on every request — Authorization: Bearer i8_… — against the base URL https://inst8-sms.com/api/v1/.
- 3
Send your first message
POST JSON to /messages.php: {"to": "+15551234567", "message": "Hello from inst8"}. The API answers 202 with a message ID, and the gateway queues and paces delivery through your SIMs automatically — same carrier-safe pacing as our CRM integrations.
- 4
Check delivery status
GET /messages.php?id=<message id> follows the message from queued to sent to delivered or failed, with an error reason when something goes wrong.
- 5
Receive replies
POST your endpoint URL to /webhooks.php and inbound messages arrive as HMAC-signed message.received events, with message.status events for delivery updates. Prefer not to host an endpoint? GET /messages.php?direction=inbound polls the same data.
- 6
Explore the full reference
Batch sends (up to 100 recipients), idempotency keys, device and SIM listing, opt-out management — every endpoint with runnable examples is in the Postman documentation linked at the top of this guide.
Troubleshooting
- 401 unauthorized
- Check the Authorization header is exactly ‘Bearer’ plus a space plus your token. If the token was revoked, create a fresh one from Integrations → Developer API.
- 429 rate limited
- You've exceeded the token's per-minute request limit. Respect the Retry-After header, and batch up to 100 recipients per request instead of one call per recipient.
- 202 accepted but nothing arrives
- Check the message's status via the API. Stuck in queued: confirm your Android device is online and its service is running. Failed: the error field says why — usually no credits, a blacklisted recipient, or no active device.
- Webhook not firing
- Events dispatch about once a minute — allow 60–90 seconds. Your endpoint must be public HTTPS and answer 2xx within 10 seconds. After 20 consecutive failed runs a webhook is auto-disabled — check it with GET /webhooks.php.
Still stuck?
Message us on WhatsApp — usually answered in under an hour.