SMSWhatsAppVoiceVideoAPIIntegrationRelease NotesFAQs
Guides
Contact UsKaleyra.io Sign InSupport

Send Bulk SMS

POST Method

Suggest Edits

The Bulk SMS API allows you to send the same message to multiple customers in one go. kaleyra.io Bulk SMS API enables you to send message to 100 recipients in a single request.

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 bulk SMS

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

Request Format

The following is the request format to send the bulk SMS if your company is not onboarded in kaleyra.io with registration country set to India:

curl -X POST "https://<api_domain>/v1/<sid>/sms" \
     -H "Content-Type:<content-type>" \
     -H "api-key:<api-key>" \
     -d "to=<to>" \
     -d "type=<type>" \
     -d "sender=<sender>" \
     -d "body=<body>"

The following is the request format to send the bulk SMS if your company is onboarded on kaleyra.io with registration country set to India:

curl -X POST "https://<api_domain>/v1/<sid>/sms" \
     -H "Content-Type:<content-type>" \
     -H "api-key:<api-key>" \
     -d "to=<to>" \
     -d "type=<type>" \
     -d "sender=<sender>" \
     -d "body=<body>" \
     -d "template_id=<template_id>"

Sample Request Format

The following is the sample request format to send bulk SMS for non-Indian companies:

curl -X POST "https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/sms" \
     -H "Content-Type:application/json" \
     -H "api-key:Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3" \
     -d "to=+91XXXXXXXXXX,+91XXXXXXXXXX,+1XXXXXXXXXX" \
     -d "sender=KLRHXA" \
     -d "type=TXN" \
     -d "body=Hello! This is my first SMS to multiple recipients."

The following is the sample request format to send bulk SMS for customers from India:

curl -X POST "https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/sms" \
     -H "Content-Type:application/json" \
     -H "api-key:Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3" \
     -d "to=+91XXXXXXXXXX,+91XXXXXXXXXX,+1XXXXXXXXXX" \
     -d "sender=KLRHXA" \
     -d "type=TXN" \
     -d "body=Hello! This is my first SMS to multiple recipients."\
     -d "template_id=101XXXXXX012"

📘

Note:

The template_id should be the same as the one registered in the DLT system.

URL Parameters and Headers

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

Parameter / HeadersData TypeDescriptionExampleMandatory?
sidStringAccount SID (Security Identifier).HXAP16XXXXXX97INYes
api-keyStringAPI key generated from kaleyra.io account.Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3Yes
content-typeStringIndicates the format of the content the API will be processing.The only allowed value is application/json.Yes
toStringPhone number of the end customer you want to send a message to.+91XXXXXXXXXXYes
(valid phone numbers only)
senderStringAlphanumeric Sender ID displayed on recipient devices.KLRHXAYes

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

ParameterData TypeDescriptionExampleMandatory?
typeStringRoute 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 in the case of bulk SMS.		TNXYes
bodyStringBody of the SMS. It is required if template_id is not provided."Hello! This is my first SMS to multiple recipients."Conditional
template_idStringTemplate ID for pre-registered templates. Required if the body is not provided. template_id must be 12 to 30 digits and must exist as a tag.101XXXXXX012Conditional

📘

Notes:

  • In the to parameter you can use multiple phone numbers separated by commas. In the case of sending the OTP, multiple numbers are not supported.
  • For template_id, if the body parameter is passed together, then the Body will have priority, and the template ID and template data will have less priority.

Success Response

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

Success response for non-Indian companies:

{
  "id": "648xxx2c-xxxx-xxxx-80c5-3c2xxxb391",
  "sender": "KLRHXA",
  "type": "DEFAULT",
  "body": "Hello! This is my first SMS to multiple recipients.",
  "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 for customers from India:

{
  "id": "648xxx2c-xxxx-xxxx-80c5-3c2xxxb391",
  "sender": "KLRHXA",
  "type": "DEFAULT",
  "template_id": "2xxxxxxxxxxxx",
  "body": "Hello! This is my first SMS to multiple recipients.",
  "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

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

  • Exceeds Maximum Mobile Number Limit
    You cannot pass more than 100 numbers in a single API call.
{
  "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."
  }
}

SMS Error Codes, SMS Status and Status Trace Codes

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

Updated 5 months ago