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 for a mailing list

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	bool	Enables the test mode: if set, the campaign will be formed, but not sent, and it will not be displayed in user panel. By default, `false`	optional
use_dynamic_list	bool	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
stat_link_tracking	bool	Enables collecting click-trough stats. By default, `false`	optional
stat_link_need_protocol	bool	Enables the HTTPS protocol on links. 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",
    "addressBookId":88891974,
    "body":"body",
    "emulate":false,
    "date":"2024-07-07 10:00:00",
    "use_dynamic_list":true,
    "stat_link_tracking":true,
    "stat_link_need_protocol":true
}

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	bool	Used to activate test mode: if set, the campaign will be formed, but not sent, and it will not be displayed in user panel. By default, `false`	optional
stat_link_tracking	bool	Enables collecting click-trough stats. By default, `false`	optional
stat_link_need_protocol	bool	Enables the HTTPS protocol on links. By default, `false`	optional

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":false,
   "date":"2024-07-07 10:00:00",
   "stat_link_tracking":true,
   "stat_link_need_protocol":true
}

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
}