Send Transactional Bulk SMS

This 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.

You can use transactional SMS messages to:

• Send a post-purchase SMS to share details about a purchase/booking,

• Help your users reset their password if they forget it,

• Confirm an order a user places,

• Share delivery tracking details of a purchase (when it is shipped, on the way, and delivered) and take many other actions.

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}, order #{orderNumber} was 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

Endpoint and Headers

Headers

Body Parameters

Sample Request

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

Below is a sample request to send multiple SMS messages in a single request, each with optional tracking and URL shortening settings.

curl --location 'https://sms.useinsider.com/v1/sendMultipleMessage' \
--header 'x-ins-auth-key: INS.Abcd1234' \
--header 'Content-Type: application/json' \
--data '{
    "messages": [
        {
            "phoneNumber": "+905555555555",
            "content": "This is SMS body.",
            "callback": "http://callback.url",
            "settings": {
                "urlExcludeProtocol": true,
                "urlShorteningDomain": "insdr.io",
                "urlShorteningStatus": true,
                "urlTrackingStatus": true,
                "smartEncoding": true
            },
            "uniqueArgs": {
                "additionalProp1": "string",
                "additionalProp2": "string",
                "additionalProp3": "string"
            }
        },
        {
            "phoneNumber": "90 (555) 55",
            "content": "This is SMS body.",
            "callback": "http://callback.url",
            "settings": {
                "urlExcludeProtocol": true,
                "urlShorteningDomain": "insdr.io",
                "urlShorteningStatus": true,
                "urlTrackingStatus": true,
                "smartEncoding": true               
            },
            "uniqueArgs": {
                "additionalProp1": "string",
                "additionalProp2": "string",
                "additionalProp3": "string"
            }
        }
    ]
}'

Sample Callback Responses

SMS Accepted

{
    "message": "Accepted",
    "messageIds": [
        {
            "phoneNumber": "+905555555555",
            "messageSid": "sms-a1234567-b123-c123-d123-e123f123456"
        }
    ],
    "errors": [
        {
            "field": "messages[1].phoneNumber",
            "error": "This field must be a valid phone number."
        }
    ]
}

SMS Sent

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

SMS Delivered

{
  "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
}

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.

• You can send a maximum of 5 requests per second, and each request can include up to 50 messages, which means you can send up to 250 message parts per second.

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