Send Transactional Single SMS

  • Updated on Dec 9, 2025
  • Published on Sep 2, 2022
  • 5 minute(s) read
Prev Next

The Transactional Single SMS API enables you to send targeted transactional SMS to your users. You can trigger these SMS messages once a user takes a specific action on your platform.

Use Cases

You can send transactional SMS messages for:

  • System notifications

  • Order confirmation/information

    • Thank you for your purchase! Your order number is {orderNumber}. View more information about your order here: {Link}

    • Hey, {firstName}! Thanks for your purchase! View more information about your order ({orderNumber}) here: {Link}

  • Shipping Confirmation

    • Great news, {firstName}! Your order ({orderNumber}) has shipped and will arrive soon. Click here to view your order details: {Link}

    • Get excited! Your order ({orderNumber}) has shipped and is coming to you. Click here to view your order details: {Link}

  • Ticket booking confirmation or cancellation

    • Hey {firstName}, your order #{orderNumber} has been successfully canceled. You can check the status of your order here {Link}

  • Information about shipping and delivery updates

  • Recurring billing/payment updates

  • Appointment confirmations

  • Welcome Messages

  • Helping your users reset their passwords if they forget them

Endpoint and Headers

POSThttps://sms.useinsider.com/v1/send

Visit our Postman collection to test this request.

Headers

Header

Sample Value

Description

X-INS-AUTH-KEY

1a2b3c4d5e6f

This key is required to authorize your request. Refer to API Authentication Tokens to generate your token. If needed to test Transactional SMS, please request an API key from the Insider One team.

Content-Type

application/json

This header specifies the media type of the resource.

Body Parameters

Parameter

Description

Data Type

Required

to

Phone Number

String

Yes

content

Content of the SMS

String

Yes

unique_args

Unique arguments of transactional SMS used for tracking purposes

Object

No

callback

The endpoint that you define to receive the webhook events. If the response does not return a 200 (Success) code, the Insider system will respond with "Callback URL value is not valid".

URL

No

settings.UrlShorteningStatus

To use the URL shortening for status in your messages.

Boolean

No

settings.UrlShorteningDomain

To use the URL shortening for your domain in your messages. e.g. insdr.io

String

No

settings.UrlTrackingStatus

For using the URL click tracking in your messages. If you do not add this parameter to the payload, the default version will not provide usage. If you do not open urlTracking and if you do not have Insider Tag integration on the related link’s webpage, you will see the clickthrough metric under the analytics page as zero.

Boolean

No

settings.smartEncoding

This smart encoding will automatically convert special characters from UCS-2 to GSM-7.

Boolean

No

settings.UrlExcludeProtocol

For excluding URL protocol (e.g., 'http://' or 'https://')

Boolean

No

sendAt

Specifies the desired date and time at which the SMS message should be sent. For example: datetime=2006-01-02T15:04:05Z
This parameter is valid only for Twilio and Sinch partners.

String

No

You can enhance your transactional messages with emojis and special characters. Add them to the content field when sending a request to the endpoint, and they will be seamlessly delivered to the end user.


Please note that using emojis in your content changes the encoding system to UCS-2. Refer to the Smart Encoding and SMS Part articles for more details.

SMS Status Callback

The current status of your SMS messages while they are being sent is provided to you through the API URL you specify in the callback parameter. If you don't respond to code between 200 and 300, the system retries the request 10 times. The retry policy process is as follows; 

  • The first request is tried again 1 minute later.

  • The second request is tried again 2 minutes later after the first attempt.

  • The third request is tried again 3 minutes later after the first attempt.

  • The fourth request is tried again 8 minutes later after the first attempt.

  • The fifth request is tried again 13 minutes later after the first attempt.

  • The sixth request is tried again 18 minutes later after the first attempt.

  • The seventh request is tried again 28 minutes later after the first attempt.

  • The eighth request is tried again 38 minutes later after the first attempt.

  • The ninth request is tried again 48 minutes later after the first attempt.

  • The tenth request is tried again an hour later after the first attempt.

Sample Request

Every request made to the request endpoint requires a request body formatted in JSON and containing your SMS content.

Before sending your request, ensure that you replace the sample values in the request header(s) and body where required.

Below is a sample request to send an SMS message with optional scheduling, URL shortening, and tracking settings.

curl --location 'https://sms.useinsider.com/v1/send' \
--header 'x-ins-auth-key: INS.Abcd1234' \
--header 'Content-Type: application/json' \
--data '{
    "content": "This is SMS body.",
    "to": "+105555555555",
    "callback": "http://callback.url",
    "sendAt" : "2024-03-30T11:30:27Z",
    "uniqueArgs": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
    },
    "settings": {
        "urlExcludeProtocol": true,
        "urlShorteningDomain": "insdr.io",
        "urlShorteningStatus": true,
        "urlTrackingStatus": true,
        "smartEncoding": true
    }
}'

Sample Callback Responses

SMS Accepted

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

SMS Sent

{
  "id": "sms-a1234567-b123-c123-d123-e123f123456",
  "uniqueArgs": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "event": "sent",
  "partCount": 1
}

SMS Delivered

This response indicates that your request was successfully completed.

{
  "id": "sms-a1234567-b123-c123-d123-e123f123456",
  "uniqueArgs": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "event": "delivered",
  "phoneNumber": "+901234567890",
  "timestamp": 1234567890
}

SMS Undelivered

{
  "id": "sms-a1234567-b123-c123-d123-e123f123456",
  "uniqueArgs": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "event": "undelivered",
  "reason": {
    "message": "Soft Bounce",
    "code": 1404
  },
  "phoneNumber": "+901234567890",
  "timestamp": 1234567890
}

SMS Dropped

{
  "id": "sms-a1234567-b123-c123-d123-e123f123456",
  "uniqueArgs": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "event": "failed",
  "reason": {
    "message": "Invalid Phone Number",
    "code": 1500
  },
  "partCount": 1,
  "phoneNumber": "+901234567890",
  "timestamp": 1234567890
}

SMS Scheduled

{
  "id": "sms-a1234567-b123-c123-d123-e123f123456",
  "uniqueArgs": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "event": "scheduled",
  "sendAt": "2006-01-02T15:04:05Z",
  "partCount": 1,
  "phoneNumber": "+901234567890",
  "timestamp": 1234567890
}

SMS Sent

{
  "id": "sms-a1234567-b123-c123-d123-e123f123456",
  "uniqueArgs": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "event": "sent",
  "sendAt": "2006-01-02T15:04:05Z",
  "partCount": 1,
  "phoneNumber": "+901234567890",
  "timestamp": 1234567890
}

Transactional SMS Events Now Logged in UCD by Default

You can track your transactional SMS delivery performance directly in UCD automatically and without any setup required.

Transactional SMS events (delivered, undelivered, and dropped) are now written to UCD by default. Previously, these events had to be manually enabled through a support request.

With this update, you’ll benefit from:

- Consistent data tracking across all transactional SMS use cases

- No need for manual enablement or configuration

Limitations

  • All functions must be executed with a simple HTTPS POST request.

  • The API Key should be provided as the authorization key in the request header. If the key is incorrect, the operation will not be executed, and an authorization error will be returned in the response.

  • The transactional API cannot be used to send promotional SMS. It is designed to set transactional SMS only.

  • The phone number should be in E164 format.

  • Content can’t be empty. The maximum limit is 670 characters.

  • The rate limit is 100 requests per second.

  • The maximum speed will be determined based on the Provider Setup.

  • Insider will send a sample request to the callback URL you provide. If the response does not return a 200 (Success) code, the Insider system will respond with "Callback URL value is not valid".

The default limit shown here is a standard baseline. If your use case requires higher capacity, feel free to reach out to the Insider One team — we can adjust it to fit your needs.

Related articles