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.

Base URL

<https://api.kaleyra.io/v1/><SID>

To send Bulk SMS, follow the below steps:

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

  1. API command to Send Bulk SMS

Request Format

To send Bulk SMS, use the /messages endpoints.

curl -X POST "https://api.kaleyra.io/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.kaleyra.io/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:

ParameterVariableDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier)HXXXXXXX071USYes
API_KEYStringAPI Key generated by Kaleyra.ioAc4XXXXX21fYes
TYPEStringType of route
understand route types
DEFAULT / MKT / TXNOptional
SENDER_IDStringOriginator/Alphanumeric IDKLRHXAYes
TEMPLATE_IDIntegerUnique ID of the template (Only for Indian Customers)2xxxxxxxxxxxxYes
  1. 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.kaleyra.io/v1/HXXXXXXX071US/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.kaleyra.io/v1/HXXXXXXX071US/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"