Schedule SMS API

POST Method

kaleyra.io enables you to schedule an SMS to be sent at a future point in time using this API. You can schedule to send your SMS from 15 minutes after the request time and within 3 months from the request date.

Prerequisites

  • Before sending the SMS, you must configure the SMS channel in kaleyra.io.
  • After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in kaleyra.io.
  • Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
  • You must have an approved SenderID or a specific number to be used as SenderID.

Base URL

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

API Domain and Value

api_domainValue
IN podapi.in.kaleyra.io
SG Podapi.kaleyra.io
EU Podapi.eu.kaleyra.io
NA podapi.na.kaleyra.ai

API request to send scheduled SMS

To send scheduled SMS use the <api_domain>/v1/<sid>/sms endpoint with the following request method:

Request Format

The following is the request format to send scheduled SMS:

curl --location --request POST 'https://<api_domain>/v1/<sid>/sms' \
--header 'Content-Type:<content-type>' \
--header 'api-key:<api_key>' \
--data-urlencode 'to=<to>' \
--data-urlencode 'sender=<sender>' \
--data-urlencode 'body=<body>' \
--data-urlencode 'type=<type>' \
--data-urlencode 'time=<time>' \
--data-urlencode 'callback_profile_id=<callback_profile_id>'

Sample Request Format

The following is the sample request format to send the scheduled SMS:

curl --location --request POST 'https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/sms' \
--header 'Content-Type:application/json' \
--header 'api-key:Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--data-urlencode 'to=+91XXXXXXXXXX' \
--data-urlencode 'sender=KLRHXA' \
--data-urlencode 'body=Hi, your appointment with Dr. John is scheduled for today at 4.00 PM.' \
--data-urlencode 'type=MKT' \
--data-urlencode 'time=2023-02-02T12:58:00+04:30' \
--data-urlencode 'callback_profile_id=IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX'

URL Parameters and Headers

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

Parameter / Headers

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 scheduled SMS:

Parameter

Data Type

Description

Example

Mandatory?

body

String

Body of the SMS. It is required if template_id is not provided.

"Hi, your appointment with Dr. John is scheduled for today at 4.00 PM"

Conditional

type

String

Route type.

  • *Note**: This is not a mandatory field. For customers in the Indian region, the available SMS Types are Transactional (TNX), Transactional DND (TXND), and Marketing (MKT). OTP is not supported for the scheduled SMS.

MKT

Yes

time

ISO Date

The time at which the message should be sent. The time must be specified in the YYYY-MM-DDThh:mm:ss<Time_Zone>

"2023-02-02T12:58:00+04:30"

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

Success Response

The following success response is received when the JSON script has the correct syntax:

{
  "id": "0xxxxxxx-xxxx-4xxx-9xxx-2xxxxxxxxxxx",
  "sender": "KLRHXA",
  "type": "MKT",
  "body": "Hi, your appointment with Dr. John is scheduled for today at 4.00 PM.",
  "createdDateTime": "2023-02-02T12:58:00+04:30",
  "totalCount": 1,
  "data": [
    {
      "message_id": "0xxxxxxx-xxxx-4xxx-9xxx-2xxxxxxxxxxx:1",
      "recipient": "+1202XXXXXXX"
    }
  ],
  "dlrurl": null
}

Failure Response

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

  • Invalid Time
    You can schedule the SMS from 15 minutes from the current time and before three months from now.
{
  "code": "E402",
  "message": "Message can be scheduled for after 15 minutes from current time and before 3 months from now.",
  "error": {
    "time": "Message can be scheduled for after 15 minutes from current time and before 3 months from now."
  }
}

SMS Error Codes, SMS Status and Status Trace Codes

Refer to the following links for Error Codes, Status and Status Trace Codes:





© 2025 Kaleyra Inc. All rights reserved.
Trademarks, logos and service marks displayed on this site are registered and unregistered trademarks of Kaleyra Inc.