Bulk SMS API - Send a Bulk SMS Request

This page details how to send a bulk SMS request.


To send a bulk SMS request, you must have:

  • TeleSign API credentials (Customer ID, API key)
  • Access to the Bulk SMS API
  • A list of comma separated MSISDNs you want to send your message to. You can have up to 1000 in your request. An MSISDN is the mapping of the telephone number to the SIM card in a mobile phone.


The simplest way to implement a request is to use Basic authentication. Read about setting up Basic authentication on the Authentication page.


  1. Implement Basic authentication for your request.
  2. For the body of your request, add your message using the template parameter. You would set up your message like so: template="Hello from TeleSign!".
  3. Use the recipients parameter to provide a comma separated list of MSISDNs. If you wish, you do not need to include a unique session ID for each MSISDN. If you do it this way, it looks like this: recipients=381606878232,381647559476.
  4. For this example, we will also use session IDs. You can assign a unique ID to each MSISDN. You do this with the session_id parameter, but you use the parameter as part of the recipients string. If you choose to use these IDs, you create them, and you assign one to each MSISDN. It looks like this: recipients=381606878232:255E3E34382C0E049046BF14FF7F3435,381647559476:255DEBF29DA410049042F97AF48F3D04. Or recipients=MSISDN:session_id,MSISDN:session_id if you want to see it presented generically. (See available parameters on the API reference page - POST /v1/verify/bulk_sms.)



TeleSign recommends using the session_id parameter if you think you will want to individually review messages in your bulk request. The session_id allows you to uniquely identify each message.


This section provides examples of the DLR you receive and other responses.

Here is an example of what a DLR payload looks like:

DLR Payload

  "status": {
    "updated_on": "Wed, 05 Oct 2016 14:51:28 GMT",
    "code": 200,
    "description": "Delivered to handset"
  "errors": [],
  "sub_resource": "bulk_sms",
  "session_id": "255E3E34382C0E049046BF14FF7F3435",
  "reference_id": "B56259E45884010488343BAA15FB0002"

Here is an example of a successful response body:

Successful Response Body

  "reference_id": "B562A981D0E0010488434B07861B1862",
  "sub_resource": "bulk_sms",
  "errors": [],
  "status": {
    "updated_on": "2016-10-21T14:05:36.181346Z",
    "code": 293,
    "description": "Bulk request accepted"

Here is an example of a generic unsuccessful response body:

Unsuccessful Response

  "status": {
    "updated_on": "2016-10-25T12:33:45.420798Z",
    "code": 500,
    "description": "Transaction not attempted"
  "errors": [
      "code": -90001,
      "description": "System Unavailable, Please try again later."
  "sub_resource": "bulk_sms"

Did this page help you?