Bulk SMS Service API

Add Phone Numbers to a Mailing List without Variables

To add phone numbers to a mailing list, send a POST request to:

https://api.sendpulse.com/sms/numbers

Request parameters:

Parameter Type Description  
addressBookId int Mailing list ID required
phones array List of telephone numbers required

Request example:

{
    "addressBookId": 434443,
    "phones": ["380986235698", "3800685321598"]
}

If the request is successful, you will receive a response:

{
   "result": true,
   "counters": {
      "added": 2,
      "exceptions": 0,
      "exists": 0
   }
}

Add Phone Numbers to a Mailing List with Variables

To add phone numbers to a mailing list with variables, send a POST request to:

https://api.sendpulse.com/sms/numbers/variables

Request parameters:

Parameter Type Description  
addressBookId int Mailing list ID required
phones object List of phone numbers required

Request example:

{
   "phones":{
      "380632631234":[
         [
            {
               "name":"Date",
               "type":"date",
               "value":"2018-10-10"
            },
            {
               "name":"Name",
               "type":"string",
               "value":"Name"
            }
         ]
      ],
      "38063333333":[
         [
            {
               "name":"Date",
               "type":"date",
               "value":"2018-10-10"
            },
            {
               "name":"Name",
               "type":"string",
               "value":"Name"
            }
         ]
      ]
   },
   "addressBookId":434443
}

Note that value of the date variable must NOT include time, e.g.: 2018-10-10 23:00:00 is incorrect value format, and 2018-10-10 is correct.

If request is successful, you will receive a response:

[
   {
      "result":true,
      "counters":{
         "added":2,
         "exceptions":0,
         "exists":83
      }
   }
]

Update a List of Variables for a Phone Number

To update a list of variables by a phone number, send a PUT request to:

https://api.sendpulse.com/sms/numbers

Request parameters:

Parameter Type Description  
addressBookId int Mailing list ID required
phones array List of phone numbers required
variables array List of variables required

phones parameter example:

["380933170413","380988365096","380956045455","380635962561"]

variables parameter example:

[
   {"name":"test1","type":"date", "value":"2018-10-10"},
   {"name":"test2","type":"string", "value":"czxczxczx"},
   {"name":"test3", "type":"number", "value":12312312312}
]

If request is successful, you will receive a response:

[
 {
   "result": true,
   "counters": {
     "updated": 4
   }
 }
]

Change a Phone Number for a Contact

To change or add a phone number value for a contact in the address book, send a PUT request to:

https://api.sendpulse.com/addressbooks/{{id}}/phone

Request parameters:

Parameter Type Description  
id int Mailing list ID required
email string Email address required
phone string Phone number required

Request example:

{
    "email":" user1@example.com",
    "phone":"1234567890"
}

If the request is successful, you will receive a response:

{
    "result": true
}

Remove Phone Numbers from a Mailing List

To remove phone numbers from a mailing list, send a DELETE request to:

https://api.sendpulse.com/sms/numbers

Request parameters:

Parameter Type Description  
phones array List of phone numbers required
addressBookId int Mailing list ID required

Request example:

{
    "addressBookId": 434443,
    "phones": ["380986235698", "380685321598"]
}

If request is successful, you will receive a response:

{
    "result": true,
    "counters": {
        "deleted": 2
    }
}

Change Variables for a Phone Contact

To change a variable for a phone number, send a POST request to:

https://api.sendpulse.com/addressbooks/{id}/phones/variable

Request parameters:

Parameter Type Description  
id int Mailing list ID containing the necessary phone contact required
phone string Recipient, that has the variable required
variables array List of variables required

Request example:

{
   "phone":"380931112233",
   "variables":[
      {
         "name":"name",
         "value":"John"
      },
      {
         "name":"date",
         "value":"2019-02-01"
      }
   ]
}

Variables in string format accept either numeric values, or values expressing date in the following format: YYYY-MM-DD. number variables accept only numbers and the date variable in the following format: YYYY-MM-DD. Other formats are not supported. E.g.: a valid date : 2017-01-01, invalid date: 2017-1-1.

If the request is successful, you will receive a response:

{
    "result": true
}

Get Information for a Specific Phone Number

To get information for a specific phone number, send a GET request to:

https://api.sendpulse.com/sms/numbers/info/{addressBookId}/{phoneNumber}

Request parameters:

Parameter Type Description  
phoneNumber string Phone number required
addressBookId int Mailing list ID required

If the request is successful, you will receive a response:

[
  {
    "result": true,
    "data": {
      "status": 1,
      "variables": {
        "test1": "2018-10-10",
        "test2": "czxczxczx",
        "test3": 12312312312
     },
     "added": "2017-02-21 13:19:47" 
    }
  }
]

Add Phone Number to the Blacklist

To add a phone number to the blacklist, send a POST request to:

https://api.sendpulse.com/sms/black_list

Request parameters:

Parameter Type Description  
phones array List of phone numbers required
description string Description required

Request example:

{
    "phones": ["350905623479", "350915623471"],
    "description": "description"
}

If request is successful, you will receive a response:

[
  {
    "result": true,
    "counters": {
      "added": 2,
      "exists": 3 
    }
  }
]

Remove a Phone Number from the Blacklist

To remove a phone number from the blacklist, send a DELETE request to:

https://api.sendpulse.com/sms/black_list

Request parameters:

Parameter Type Description  
phones array List of phone numbers required

If the request is successful, you will receive a response:

[
  {
    "result": true,
    "counters": {
       "removed": 3
    }
  }
]

Get a List of Contacts in the Blacklist

To get a list of contacts in the blacklist, send a GET request to:

https://api.sendpulse.com/sms/black_list

If request is successful, you will receive a response:

{
    "result": true,
    "data": [
        {
            "phone": "350965623471",
            "description": "description",
            "add_date": "2021-08-02 12:10:25"
        },
        {
            "phone": "350965623479",
            "description": "description",
            "add_date": "2021-08-02 12:10:25"
        }
    ]
}

Get Information about Phone Numbers on the Blacklist

To get information about phone numbers in the blacklist, send a GET request to:

https://api.sendpulse.com/sms/black_list/by_numbers

Request parameters:

Parameter Type Description  
phones array List of phone numbers required

If request is successful, you will receive a response:

{
    "result": true,
    "data": [
       {
          "phone": "350965623471",
          "description": "description",
          "add_date": "2021-08-02 12:10:25"
       }
    ]
}

Create a Campaign

To create a campaign, send a POST request to:

https://api.sendpulse.com/sms/campaigns

Request parameters:

Parameter Type Description  
sender string Alphanumeric value, 11 symbols maximum required
addressBookId int Mailing list ID required
body string Message body required
route* object List of routes for various countries in JSON, example {"UA":"national", "BY":"international"} optional
date string Date of the campaign in YYYY-MM-DD HH:MM:SS format optional
emulate int This parameter activates Test mode: if emulate=1, the campaign
will be formed, but not sent, and it will not be displayed in user panel;
in API reply, the campaign id will be 0		 optional

* Note, that some operators require specification of the message delivery route: national or international. Operators of some countries also require a registered sender ID. If you don't have a registered sender ID for such countries, the international route must be used.

All messages undergo moderation, so it may take up to several minutes to deliver your SMS to the recipient.

Request example:

{
   "sender":"Sender",
   "addressBookId":422325,
   "body":"body",
   "route":{
      "UA":"international"
   },
   "date":"2021-07-07 10:00:00",
   "emulate":0
}

If request is successful, you will receive a response:

{
    "result": true,
    "campaign_id": 5033111
}

Create a Campaign for a List of Phone Numbers

To create a campaign for a list of phone numbers, send a POST request to:

https://api.sendpulse.com/sms/send

Request parameters:

Parameter Type Description  
sender string Sender information as an alphanumeric value, 11 symbols maximum required
phones array Bulk telephone mailing list in JSON format required
body string Message body required
date string Date of the campaign in YYYY-MM-DD HH:MM:SS format optional
route* object List of routes for various countries in JSON optional
emulate int This parameter activates Test mode: if emulate=1, campaign
will be formed, but not sent, and it will not be displayed in user panel;
in API reply, the campaign id will is 0		 optional
use_dynamic_list boolean Used to send to a dynamic list for scheduled campaign. A dynamic list includes contacts that were added to your mailing list after you created a campaign, but before you send the campaign. Available on any paid pricing plan. By default, false optional

* Note, that some operators require specification of the message delivery route: national or international. Operators of some countries also require a registered sender ID. If you don't have a registered sender ID for such countries, the international route must be used.

All messages undergo moderation, so it may take up to several minutes to deliver your SMS to the recipient. 

Request example:

{
   "sender":"Sender",
   "phones":[
      "380986158966",
      "380930452313"
   ],
   "body":"body",
   "route":{
      "UA":"international"
   },
   "emulate":0,
   "use_dynamic_list":true,
   "date":"2021-07-07 10:00:00"
}

If the request is successful, you will receive a response:

{
    "result": true,
    "campaign_id": 503422,
    "counters": {
        "exceptions": 0,
        "sends": 2
    }
}

Get a List of Campaigns by Date

To get a list of campaigns by date, send a GET request to:

https://api.sendpulse.com/sms/campaigns/list

Request parameters:

Parameter Type Description  
dateFrom string The date from in YYYY-MM-DD HH:MM:SS format optional
dateTo string The date until in YYYY-MM-DD HH:MM:SS format optional

URL example with additional parameters:

https://api.sendpulse.com/sms/campaigns/list?dateFrom=2021-07-05 07:48:22&dateTo=2021-07-07 07:48:22

If request is successful, you will receive a response:

{
   "result":true,
   "data":[
      {
         "id":508962,
         "address_book_id":0,
         "company_price":"1.28000",
         "company_currency":"UAH",
         "send_date":"2021-07-07 07:00:00",
         "date_created":"2021-07-06 11:20:01",
         "sender_name":"Sender"
      },
      {
         "id":503358,
         "address_book_id":4225856,
         "company_price":"0.64000",
         "company_currency":"UAH",
         "send_date":"2021-07-07 07:48:22",
         "date_created":"2021-07-06 11:04:52",
         "sender_name":"Sender"
      }
   ]
}

Get Campaign Information

To get campaign information, send a GET request to:

https://api.sendpulse.com/sms/campaigns/info/{id}

Request parameter:

Parameter Type Description  
id int Campaign ID required

If request is successful, you will receive a response:

[  
   {  
      "result":true,
      "data":{  
         "id":7520226,
         "address_book_id":12458,
         "currency":"USD",
         "company_price":0.044,
         "send_date":"2018-09-13 11:03:22",
         "date_created":"2018-09-13 11:03:22",
         "sender_name":"111111",
         "task_phones_info":[  
            {  
               "phone":18085426859,
               "status":2,
               "status_explain":"Delivered",
               "сountry_code":"USA",
               "money_spent":0.022
            },
            {  
               "phone":18037080295,
               "status":2,
               "status_explain":"Delivered",
               "сountry_code":"USA",
               "money_spent":0.022
            }
         ]
      }
   }
]

Description of status sending to the phone:

Status code Status Status description
0 Ready to send The message is ready to be sent
1 Sent The message has been sent
2 Delivered The message has been delivered
12 Not delivered The message was not delivered

Cancel a Campaign Before Sending Has Started

To cancel a campaign before sending has started, send a PUT request to:

https://api.sendpulse.com/sms/campaigns/cancel/{id}

Request parameter:

Parameter Type Description  
id int Campaign ID required

If request is successful, you will receive a response:

{
   "result": true
}

Calculate the Cost of a Campaign

To calculate the cost of a campaign, send a GET request to:

https://api.sendpulse.com/sms/campaigns/cost

Request parameters:

Parameter Type Description  
addressBookId int Mailing list ID required*
phones array List of phone numbers in JSON format required*
body string Message body required
sender string Sender required
route object List of routes for various countries in JSON format, for example, {"UA":"national", "BY":"international"} optional

Please note that the parameters need to be encoded to URL format.

* If a mailing list is not specified, the list of phone numbers should be specified and vice versa.

Request example:

{
   "addressBookId":422325,
   "body":"body",
   "sender":"Sender",
   "route":{
      "UA":"national"
   }
}

A sample response:

 {
   "result": true,
   "data": {
     "price": 0.05,
     "currency": "UA" 
   }
 }

Get List of Sender IDs

To get information about sender IDs, send a GET request to:

https://api.sendpulse.com/sms/senders

If request is successful, you will receive a response:

[
      {
        "id": 4786,
        "sender": "iQA",
        "country": "Turkey",
        "country_code": "TR",
        "status": 1,
        "status_explain": "Active"
    },
    {
        "id": 4787,
        "sender": "iQA",
        "country": "Turkey",
        "country_code": "TR",
        "status": 1,
        "status_explain": "Active"
    },
    {
        "id": 18027,
        "sender": "rejectit",
        "country": "Turkey",
        "country_code": "TR",
        "status": 0,
        "status_explain": "On moderation"
    }
]

Description of status codes:

Code Description
0 In moderation
1 Active
2 Rejected

Delete a Campaign

To delete a campaign, send a DELETE request to:

https://api.sendpulse.com/sms/campaigns

Request parameters:

Parameter Type Description  
id int Campaign ID required

If request is successful, you will receive a response:

{
   "result": true
}