Send a Single Transactional SMS with OAuth 2.0

The Transactional SMS API enables you to send targeted single or batch transactional SMS messages to your users through an OAuth 2.0-authenticated HTTP interface. Messages are accepted asynchronously and queued for delivery. Final delivery status is sent to your webhook callback.

You can use this endpoint to send one transactional SMS message to a user.

Use Cases

You can send transactional SMS messages for:

System notifications, password reset messages, and login codes
Order confirmations, shipping updates, and delivery alerts
Appointment confirmations and ticket booking confirmations
Welcome messages and recurring billing notifications

Endpoint and Headers

POST https://gw.useinsider.com/api/sms/v1/send

Visit our Postman collection to test this request.

Headers

Header	Sample Value	Description
Authorization	Bearer	Bearer access token obtained from the /auth/token endpoint. This key is required to authorize your request. Refer to Generate an OAuth 2.0 Token for SMS to generate your OAuth 2.0 token.
Content-Type	application/json	Specifies the media type of the request body.

Body Parameters

Parameter	Description	Data Type	Required
to	Recipient phone number in E.164 format, for example, +905551234567.	String	Yes
content	SMS body. The content must be between 1 and 670 characters.	String	Yes
sender	Sender name or ID configured for your account. If omitted, the default sender is used.	String	No
callback	Webhook URL that receives delivery events. Must return HTTP 200 on a verification probe.	URL	No
sendAt	Schedule timestamp in ISO 8601 format, for example, 2026-06-01T15:04:05Z. This parameter is supported only by Twilio and Sinch providers.	String	No
uniqueArgs	Arbitrary key-value map for partner-side correlation. These values are returned in webhook events.	Object	No
settings	Per-message send-time options. See the Settings Object section below.	Object	No

SMS body must be between 1 and 670 characters.

Settings Object

Parameter	Description	Data Type	Required
urlShorteningStatus	Enables URL shortening for links in the SMS content.	Boolean	No
urlShorteningDomain	Branded short URL domain, for example, insdr.io. URL shortening must be enabled for your account.	String	No
urlTrackingStatus	Enables click tracking on shortened URLs. If this parameter is not enabled and Insider Tag is not installed on the destination page, click metrics are shown as zero.	Boolean	No
smartEncoding	Converts UCS-2 special characters to GSM-7, where possible, to reduce the SMS segment count.	Boolean	No
urlExcludeProtocol	Removes the URL protocol, such as http:// or https://, from rendered links.	Boolean	No

All phone numbers must be in E.164 format:
Correct: +905551234567
Incorrect:05551234567, 5551234567, 0090 555 123 45 67

Sample Request

curl --location 'https://gw.useinsider.com/api/sms/v1/send' \
  --header 'Authorization: Bearer eyJhbGc...' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "+905551234567",
    "content": "Your order #12345 has shipped.",
    "sender": "BRAND_SMS",
    "callback": "https://partner.example.com/sms/callback",
    "uniqueArgs": { "orderId": "12345" },
    "settings": {
      "urlShorteningStatus": true,
      "urlShorteningDomain": "insdr.io",
      "urlTrackingStatus": true,
      "smartEncoding": true
    }

Sample Responses

202 Accepted

A 202 response means the message was accepted and queued for delivery. Final delivery status is sent to your callback URL as a webhook event.

{
  "message": "Accepted",
  "messageId": "sms-a1234567-b123-c123-d123-e123f123456"
}

400 Bad Request: Malformed JSON

{ "message": "Invalid JSON content supplied", "errorCode": "1000" }

400 Bad Request: Validation failure

{
  "message": "Failed to validate request",
  "errorCode": "1001",
  "errors": [
    { "field": "to",      "error": "must be a valid phone number" },
    { "field": "content", "error": "must be between 1 and 670 characters" }
  ]
}

403 Forbidden

{ "message": "Transactional messaging is disabled", "errorCode": "1025" }

For other error codes, refer to the table below.

errorCode	HTTP	Description
1000	400	Invalid JSON content supplied (single send).
1001	400	Request body failed validation. Per-field errors are included in the response.
1004	400	Country quota lookup failed, or the message content domain is not allowed for this account.
1011	400	Invalid JSON content supplied (batch send).
1017	400	Batch exceeds 50 messages.
1015	500	Provider maintenance mode is active. Retry later.
1022	403	Your panel is suspended.
1024	403	Your panel is deactivated.
1025	403	Transactional messaging is disabled on your account.
1016	403	The specified sender was not found or is inactive.
1018	403	Sender provider settings are missing or invalid.

Limitations

Requests made with the sms-transactional scope are limited to 60,000 requests per 60 seconds, with a burst limit of 1,000 requests.
If the limit is exceeded, the API returns a 429 Too Many Requests response with a Retry-After header indicating when you can retry the request.
SMS body must be between 1 and 670 characters.
Emojis and non-GSM-7 characters switch the encoding to UCS-2, which uses 70 characters per segment instead of 160. Use smartEncoding to automatically convert common characters.
Request body size is capped at ~19.9 MB.

Documentation Index