Send Bulk SMS

POST Method

Description

The Bulk SMS API allows you to send messages to more than one customer in one go. Our Bulk SMS API enables you to send messages to 100 recipients in a single 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 Bulk SMS, follow the below steps:

Signup or Login to Kaleyra.io and create your API key.

Refer to the Create an API Key page for steps to create your API key. To view the API Key and the SID, see View API Key and SID.

📘
Note:
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.

API command to Send Bulk 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 Bulk SMS, use the /messages endpoints.

curl -X POST "https://<api_domain>/v1/<SID>/messages" \
     -H "api-key: <API_KEY>" \
     -d "to=+1XXXXXXXXXX,+39XXXXXXXXXX,+91XXXXXXXXXX" \
     -d "type=<TYPE>" \
     -d "sender=<SENDER_ID>" \
     -d "body=Hello! This is my first SMS to multiple recipient."

Request Format-Indian Customers

curl -X POST "https://<api_domain>/v1/<SID>/messages" \
     -H "api-key: <API_KEY>" \
     -d "to=+1XXXXXXXXXX,+39XXXXXXXXXX,+91XXXXXXXXXX" \
     -d "type=<TYPE>" \
     -d "sender=<SENDER_ID>" \
     -d "body=Hello! This is my first SMS to multiple recipient." \
     -d "template_id=<TEMPLATE_ID>"

📘
Note:

You can add multiple recipients separated by commas in the To parameter.

Ensure to replace the parameter values with the proper inputs in the above code.

Parameters and Variables

Below is the list of parameters and variables used:

Parameter	Variable	Description	Example	Mandatory
`SID`	String	Account SID (Security Identifier)	HXXXXXXX071IN	Yes
`API_KEY`	String	API Key generated by Kaleyra.io	Ac4XXXXX21f	Yes
`TYPE`	String	Type of route understand route types	DEFAULT / MKT / TXN	Optional
`SENDER_ID`	String	Originator/Alphanumeric ID	KLRHXA	Yes
`TEMPLATE_ID`	Integer	Unique ID of the template (Only for Indian Customers)	2xxxxxxxxxxxx	Yes

Response Format

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

Success Response

{
  "id": "648xxx2c-xxxx-xxxx-80c5-3c2xxxb391",
  "sender": "KLRHXA",
  "type": "DEFAULT",
  "body": "Hello! This is my first SMS to multiple recipient.",
  "createdDateTime": "2019-11-04 10:42:23+00:00",
  "totalCount": 1,
  "data": [
    {
      "message_id": "648xxx2c-xxxx-xxxx-80c5-3c2xxxb391:1",
      "recipient": "1XXXXXXXXXX"
    },
    {
      "message_id": "6489712c-xxxx-xxxx-80c5-3c2d201db391:2",
      "recipient": "39XXXXXXXXXX"
    },
    {
      "message_id": "6489xxxx12c-xxxx-xxxx-80c5-3c2d201db391:3",
      "recipient": "91XXXXXXXXXX"
    }
  ],
  "dlrurl": null,
  "error": {}
}

Success Response - Indian Customers

{
  "id": "648xxx2c-xxxx-xxxx-80c5-3c2xxxb391",
  "sender": "KLRHXA",
  "type": "DEFAULT",
  "template_id": "2xxxxxxxxxxxx",
  "body": "Hello! This is my first SMS to multiple recipient.",
  "createdDateTime": "2019-11-04 10:42:23+00:00",
  "totalCount": 1,
  "data": [
    {
      "message_id": "648xxx2c-xxxx-xxxx-80c5-3c2xxxb391:1",
      "recipient": "1XXXXXXXXXX"
    },
    {
      "message_id": "6489712c-xxxx-xxxx-80c5-3c2d201db391:2",
      "recipient": "39XXXXXXXXXX"
    },
    {
      "message_id": "6489xxxx12c-xxxx-xxxx-80c5-3c2d201db391:3",
      "recipient": "91XXXXXXXXXX"
    }
  ],
  "dlrurl": null,
  "error": {}
}

Failure Response

Exceeds Maximum Mobile Number Limit
You cannot send the TXN type message to more than 100 numbers in a single attempt.

{
  "code": "E405",
  "message": "If Type is TXN then mobile numbers should not be more than 100.",
  "error": {
    "time": "If Type is TXN then mobile numbers should not be more than 100."
  }
}

Invalid Sender ID
You must have entered an invalid or incorrect Sender ID. Include the appropriate ID and re-execute the command.

{
  "code": "E418",
  "message": "Invalid or In-Correct sender",
  "error": {
    "sender": "Invalid or In-Correct sender"
  }
}

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

Sample Request

curl -X POST "https://api.in.kaleyra.io/v1/HXXXXXXX071IN/messages" \
     -H "api-key:Ac4XXXXX21f" \
     -d "to=+1XXXXXXXXXX,+39XXXXXXXXXX,+91XXXXXXXXXX" \
     -d "type=TXN" \
     -d "sender=KLRHXA" \
     -d "body=Hello! This is my first SMS to multiple recipient."

curl -X POST "https://api.in.kaleyra.io/v1/HXXXXXXX071IN/messages" \
     -H "api-key:Ac4XXXXX21f" \
     -d "to=+1XXXXXXXXXX,+39XXXXXXXXXX,+91XXXXXXXXXX" \
     -d "type=TXN" \
     -d "sender=KLRHXA" \
     -d "body=Hello! This is my first SMS to multiple recipient." \
     -d "template_id=2xxxxxxxxxxxx"

Updated about 1 month ago

What’s Next