Send the First SMS

POST Method

SMS is a simple and a cost-effective way to communicate with customers. Before starting to send the SMS APIs, make sure that you have configured the SMS channel in Kaleyra.io. This section details how to send your first outbound SMS using an API request.

📘
Notes:

It is recommended to use /sms endpoints instead of /message endpoints for more efficient API requests and responses.

For North America (NA) pod users, use /sms endpoints for SMS API services provided by Kaleyra platform.

To send your first SMS, follow the below steps:

Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID. 
API request to Send Your First SMS.

Base URL

https://<api_domain>/v1/<SID>

API Domain and Value

api_domain	Value
IN pod	api.in.kaleyra.io
SG Pod	api.kaleyra.io
EU Pod	api.eu.kaleyra.io

Request Format

To send your first SMS, use the /messages endpoints.

curl --location --request POST 'https://<api_domain>/v1/<SID>/messages' \
--header 'api-key: <api-key>' \
--header 'Content-Type: <content-type>' \
--data '{
       "to": "<to>",
       "sender": "<sender>",
       "type": "<type>",
       "unicode": "<unicode>",
       "flash": "<flash>",
       "time": "<time>",
       "prefix": "<prefix>",
       "body": "<body>",
       "template_id": "<template_id>",
       "template_data": {
             "example_key0": "<example_key0>",
             "example_key1": "<example_key1>",
             "example_key2": "<example_key2>"
         },
       "ref_custom: "['<ref_custom>']",
       "callback_profile_id": "<callback_profile_id>"

Sample Request Format

curl --location --request POST 'https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/messages' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/json' \
--data '{
       "to": "+91XXXXXXXXXX",
       "sender": "KLRHXA",
       "type": "MKT",
       "unicode": "Auto",
       "flash": "1",
       "time": "2025-07-11T12:58:00+04:30",
       "prefix": "+91",
       "body": "Hello, this is your first SMS.",
       "template_id": "101XXXXXX012",
       "template_data": {
             "example_key0": "John",
             "example_key1": "23.43",
             "example_key2": "USD"
         },
       "ref_custom: "['John','Doe']",
       "callback_profile_id": "IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX"

📘
Note:
Make sure you replace the parameter values with the proper inputs in the above code.

Parameters and Data Types

The following is the list of parameters and headers to send the outgoing message request:

Parameter	Data type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	HXAP16XXXXXX97IN	Yes
`api-key`	String	API key generated from kaleyra.io account.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3	Yes
`content-type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/json.	Yes
`to`	String	Phone number of the end customer you want to send a message to.	+91XXXXXXXXXX	Yes (valid phone numbers only)
`sender`	String	Alphanumeric Sender ID displayed on recipient devices.	KLRHXA	Yes

Following is the list of attributes to be used in the payload to send the outgoing message:

Parameter	Data type	Description	Example	Mandatory?
`type`	String	Route type. Note: This is not a mandatory field. For customers in the Indian region, the available SMS Types are OTP, Transactional (TXN), Transactional DND (TXND), and Marketing (MKT). For Europe, America, and Singapore regions, only OTP and Default (to be used for Marketing and Transactional) route types are available.	MKT	Yes
`unicode`	String	Determines message encoding. Acceptable values are "AUTO", "0", or "1". If you know it is a unicode message, then use 1. If you know it is not a unicode message, then use 0. If you are not sure about the unicode, then use Auto.	"Auto"	No
`flash`	String	Determines if the message is a flash SMS. Acceptable values are "0" or "1". Use 1, if you want to send the message as a flash message else use 0.	"0"	No
`time`	ISO Date	The time at which the message should be sent. Must be in ISO date format YYYY-MM-DDTHH:MM:SS+HH:MM.	"2025-07-11T12:58:00+04:30"	No
`prefix`	String	Country code prefix. If the mobile number does not have a country code and you want to add it as a prefix you have the option to update it here.	"+91"	No
`body`	String	Body of the SMS. It is required irrespective of whether template_id is present or not.	"Hello, this is your first SMS."	Yes
`template_id`	String	Template ID for pre-registered templates. Required if the body is not provided. template_id must be 12 to 30 digits and exist as a tag. Note: For Indian customers, it is mandatory to use the Template ID and the template must contain a variable parameter, then only the message will get delivered successfully. For example,  `otp` for the OTP message template. Users must provide either template_id or body. If a user provides a body in the request then template_id and template_data will be ignored and body will have priority.	101XXXXXX012	Conditional
`ref_custom`	List	It contains an array of max 5 values that will be available in detailed reports and callback associated to the message. The values inside the array can have a maximum of 50 lengths in strings.	["John","Doe"]	No
`callback_profile_id`	String	The callback profile ID of the callback profile to be used to send webhook to your system about SMS status updates. For more information related to callback profiles, see callback profiles page.	IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX	Yes

The following table describes the different attributes used for the template_data JSON object, please note that the attribute name is not static but must be the same name as the name given to the placeholders (also known as dynamic variables) used in the template:

Parameter	Data type	Description	Example	Mandatory?
`example_key0`	String	The template_data attribute will be validated for string size (maximum of 30 characters per value).	John	No

📘
Note:
The following are the validations for template-based SMS API's:

The template_data attribute will be validated for string size (maximum of 30 characters per value).

A check is performed to ensure all keys in the template are included in template_data parameter.

Users must provide either template_id or body. If a user provides a body in the request template_id and template_data will be ignored and we will give priority to the body.

Optional Parameters

Add the required contextual information to your SMS using the Optional Parameters. You can include up to three parameters in the above SMS API call, and each can have a maximum of 255 characters.

📘
Note:
For Example,
When you deliver a message to multiple customers, you can pass your own Message ID as optional parameters in the API call. This information is sent back in the callback from Kaleyra.io to your system for further reference.
You can also include information such as:

Campaign Name

Client Name

Client ID

Product ID and so on

Response Format

This section provides you the success and failure JSON response formats for different scenarios.

Success Response

{
  "id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d",
  "sender": "KLRHXA",
  "type": "DEFAULT",
  "body": "Hello! This is my first SMS.",
  "createdDateTime": "2019-11-04 10:42:23+00:00",
  "totalCount": 1,
  "data": [
    {
      "message_id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d:1",
      "recipient": "1XXXXXXXXXX"
    }
  ],
  "dlrurl": null,
  "error": {}
}

The following table describes the API Response parameters.

Parameter	Description
body	The message content that is delivered to the handset.
sender	The sender ID used to send the SMS.
type	The message type. Note: The message type. Note: For customers in the Indian region, the available SMS Types for which you can create a template are OTP, Transactional (TNX), Transactional DND (TXND), and Marketing (MKT). For Europe, America, and Singapore regions, only OTP and Default (to be used for Marketing and Transactional) message types are available.
template_ID	The template that is used by the Kaleyra customer.
ID	The unique ID of the API request.
createdDateTime	The request time of the API in UTC.
total_Count	The number of contacts present in the API request.
message_ID	This is the unique ID for each mobile number.
recipient	The mobile number in the API request.
unicode	This indicates if the customer is using message content as unicode or normal text(1/0/AUTO).
flash	This indicates if the customer wants to deliver the message as a Flash message or not (1/0).
ref, ref1, ref2	These are the additional parameters the customers can use for their reference. These parameters will return the ‘callback response’.

Failure Response

The following failure response is received when the JSON script has an incorrect syntax.

{
  "code": "E401",
  "message": "SMS length is exceeding 4000 characters.",
  "error": {
    "body": "SMS length is exceeding 4000 characters."
  }
}

📘
Note:
In case of an error, ensure that the parameter values are correct in the above code. Refer to the SMS Error Codes page for detailed information.

Two-way SMS for Customer Engagement

Kaleyra's Two-Way SMS API is designed to offer you an easy and efficient way to communicate with your customers. It allows you to instantly send and receive messages through your choice of long or short codes.

If you have purchased a two-way SMS number, you must pass the same number as a Sender ID in the above API call to initiate a two-way conversation with your customers.

Sample Request

curl --location --request POST 'https://api.in.kaleyra.io/v1/HXXXXXXX071IN/messages' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'api-key: Ac4XXXXX21f' \
--data-urlencode 'to=196xxxxxx56' \
--data-urlencode 'body=Accepting number as sender test 1' \
--date-urlencode 'template_id: 101XXXXXX012' \ 
--data-urlencode 'sender=917xxxxxx834' \
--data-urlencode 'type=MKT' \
--data-urlencode 'callback={"url":"https://webhook.site/0exxxxfd-axxc-4xx1-bxxe-cdxxxxxxxx70","method":"POST","header":{"x-api-key":"qwxxxxxxxxxxxxxxxxdv","x-randoem-id":"23xxxxey"},"retry":{"count":"3","interval":["10","10","10"]}}'

📘
Note:
For Two-way SMS, the sender variable must be String/Numeric. For example +17XXXXXXXX4.

Updated 12 days ago

What’s Next