API and integrations
SMS API operations: status, errors and retries
An operational plan for integrations: OAuth tokens, idempotency, uncertain responses and the difference between created and delivered SMS.
Keep the business event and send connected
Persist an internal event reference, intended recipient and content version before sending. Associate the returned Intellipush message ID with that reference after successful creation. This is a recommended application model, rather than an additional API guarantee.
Obtain a token with POST /restv2/token, HTTP Basic and grant_type=client_credentials as form data. Tokens are opaque, last 3,600 seconds and have no refresh token. Cache them server-side until shortly before expiry instead of obtaining a new token per SMS.
Retry the same logical send
The public contract documents Idempotency-Key for SMS creation. Generate a unique, unpredictable key per logical request and persist it before the first attempt. Reuse the same key and identical accepted fields in the same order for retries within 24 hours. Keys are scoped to account, OAuth client and operation.
Without the header, creation is not idempotent. A timeout can mean that a response was lost after creation succeeded. Do not replace this with a new key and a blind send. Check documented account capabilities and route uncertain cases for investigation.
- 409 idempotency_in_progress: follow Retry-After and retain the same key and data.
- 409 idempotency_conflict: investigate key or payload handling; do not automatically change the key to force a send through.
- 503 idempotency_temporarily_unavailable: the contract states that no SMS was created; retry later with the same key.
Separate request errors from delivery outcomes
HTTP status is authoritative for the request. Explicitly handle 400 (invalid input/business rule), 401 (missing or invalid authentication), 403 (not permitted), 405 (wrong method), 409 and 5xx. Use documented errorcode values where available; status_message is human-readable text.
HTTP 200 from creation does not confirm delivery. Use the returned ID with POST /restv2/sms/status and id_array. The sent_to_operator and confirmed_delivered fields distinguish forwarding from confirmed delivery. A delivered status is not a read receipt.
Choose status handling deliberately
The current API source describes status queries, /events and signed /webhooks. Check /capabilities and the reference before choosing a mechanism. For webhooks, verify signatures against the exact request body and deduplicate event_id before returning a successful response. Do not assume identical availability across accounts.
Record internal references, message IDs, timestamps, HTTP status and X-Request-ID for diagnosis. X-Request-ID is a support reference, not an idempotency key. Avoid logging tokens, secrets or message bodies without a documented need.
A small pre-launch test matrix
Test a controlled number and low volume after your own approval. Cover token expiry, invalid data, replay with the same key, a conflicting key and a lost response. Document how sending is stopped, who owns failures and when an uncertain message is escalated. Website examples are not a sandbox.
Reviewed 30 October 2026. The API reference and current portal pricing govern implementation and purchasing.