Bulk SMS Service API - API Documentation

Adding Telephone Numbers to a Mailing List

To add telephone numbers to a list of recipients, submit a POST request to

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

Request parameters:

addressBookId	Mailing list ID (int)
phones	Bulk telephone mailing list in json format

A sample response for retrieving mailing list information request:

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

Updating a List of Variables for a Phone Number

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

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

Request parameters:

addressBookId	Mailing list ID (int)
phones	Bulk telephone mailing list in json format
variables	Array of variables in json format

Sample Phones parameter:


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

Sample Variables parameter:


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

Sample response:

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

Deleting Telephone Numbers from a Mailing List

To delete a phone number from a mailing list, submit a DELETE request to

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

Request parameters:

phones	Bulk telephone mailing list in json format
addressBookId	Mailing list ID

A sample response:

[
 {
   "result": true,
   "counters": {
     "added": 0,
     "exists": 3

   }
 }
]

Retrieving Information for a Specific Phone Number

To retrieve information for a specific phone number, submit a GET request to

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

Request parameters:

phoneNumber	a phone number
addressBookId	Mailing list ID

A sample response:

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

Adding a Telephone Number to the Blacklist

To add a telephone number to the blacklist submit a POST request to

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

Request parameters:

phones	Bulk telephone list in json format
description	Description

A sample response:

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

To delete a phone number from the blacklist, submit a DELETE request to

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

Request parameters:

phones

Bulk telephone list in json format

A sample response:

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

Viewing the Blacklist

To view the blacklist, submit a GET request to

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

A sample response:


[
 {
   "result": true,
   "data": [ {
		"phone": 380506383302,
		"description": "texst",
		"add_date": "2017-02-27 10:48:22"
	},
	]
  }
]

Retrieving Information About Telephone Numbers on the Blacklist

To retrieve information of telephone numbers in the blacklist submit a GET request to

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

Request parameters:

phones

a ist of telephone numbers in json format

A sample response:


[
  {
   "result": true,
   "data": [ {
		"phone": 380506383302,
		"description": "texst",
		"add_date": "2017-02-27 10:48:22"
	},
	]
}
]

Creating a Campaign

To create a campaign submit a POST request to

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

Request parameters:

sender	Alphanumeric value, 11 symbols max
addressBookId	Aailing list ID
body	Text of the messages in the Campaign
transliterate	1 or 0, transliteration of the body
route*	List of routes for various countries in JSON (optional), example `{"UA":"national", "BY":"international"}`
date	Date of the campaign in YYYY-MM-DD HH:MM:SS format (optional)
emulate	This optional 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 =0.

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.

A sample response:


[
 {
  "result": true,
  "campaign_id": 2623084
 }
]

Creating a Campaign for a List of Phone Numbers

To create a campaign by a list of phone numbers, submit a POST request to

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

Request parameters:

sender	Sender information as an alphanumeric value, 11 symbols max
phones	Bulk telephone mailing list in JSON format
body	Text of the messages in the Campaign
transliterate	1 or 0, transliteration of the message body
date	Date of the campaign in YYYY-MM-DD HH:MM:SS format (optional)
route	List of routes for various countries in JSON (optional)
emulate	This optional 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 =0.

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

A sample response:


[
 {
   "result": true,
   "campaign_id": 2623085,
   "counters": {
     "exceptions": 0,
     "sends": 3
   }
 }
]

Retrieving a List of Campaigns by Date

To retrieve a list of campaigns by date, submit a GET request to

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

Request parameters:

dateFrom	The date from in YYYY-MM-DD HH:MM:SS format
dateTo	The date until in YYYY-MM-DD HH:MM:SS format

Sample response:


[
 {
   "result": true,
   "data": [ {
     "id": 2136035,
     "address_book_id": 0,
     "company_price": 0.81,
     "company_currency": "USD",
     "send_date": "2017-01-18 08:15:18",
     "date_created": "2017-01-18 08:15:18",
     "sender_mail_address": "",
     "sender_mail_name": "",
     "external_stat": []
   }, 
   {
   "id": 2136036,
   "address_book_id": 0,
   "company_price": 0.27,
   "company_currency": "USD",
   "send_date": "2017-01-18 11:59:52",
   "date_created": "2017-01-18 11:59:52",
   "sender_mail_address": "",
   "sender_mail_name": "",
   "external_stat": []
   },
   ]
 }
]

Retrieving Campaign Information

To retrieve a campaign information submit a GET request to

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

Request parameters:

{id}	the ID of the campaign

A sample 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

Canceling a Campaign Before Sending Has Started

To cancel a campaign submit a PUT request to

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

Request parameters:

{id}	the ID of the mailing

A sample response:


[
 {
   "result": false
 }
]

Calculating the Cost of a Campaign

To calculate the cost of a campaign submit a GET request to

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

Request parameters:

addressBookId	Mailing list ID
phones	Bulk telephone list in JSON format (optional)
body	Body of the message
sender	Sender
route	List of routes for various countries in (JSON optional), example `{"UA":"national", "BY":"international"}`

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.

A sample response:


[
 {
   "result": true,
   "data": {
     "price": 0.05,
     "currency": "USD" 
   }
 }
]

Retrieving List of Sender IDs

To retrieve information about sender ID's in account submit a GET request to

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

A sample 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:

0	In moderation
1	Active
2	Rejected

Deleting a Campaign

To delete a campaign submit a DELETE request to

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

Request parameters:

id	a campaign ID

A sample response:

[
 {
   "result": false | true
 }
]

Adding Telephone Numbers to a Mailing List by Variable

To add telephone numbers to a mailing list by variable submit a POST request to

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

Request parameters:

addressBookId	Mailing list ID (int)
phones	Array of phone numbers in JSON format (find example below)

Array of phone numbers in Json format:


{  
   "phones":{  
      "380632631234":[  
         [  
            {  
               "name":"test1",
               "type":"date",
               "value":"2018-10-10"
            },
            {  
               "name":"test2",
               "type":"string",
               "value":"czxczx"
            },
            {  
               "name":"test3",
               "type":"number",
               "value":"123"
            }
         ]
      ],
      "38063333333":[  
         [  
            {  
               "name":"test1",
               "type":"date",
               "value":"2018-10-10"
            },
            {  
               "name":"test2",
               "type":"string",
               "value":"czxczxczx"
            },
            {  
               "name":"test3",
               "type":"number",
               "value":"456"
            }
         ]
      ]
   },
   "addressBookId":1886620
}

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 be correct.

A sample response:


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

Changing Variables for a Phone Contact

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

https://api.sendpulse.com/addressbooks/addressBookId/phones/variable

Sample request parameters:

addressBookId	Mailing list ID containing the necessary phone contact with the variable with “name” value
phone	Recipient, that will have the variable with “name” value changed to “John”

Array of phone numbers in Json format

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

*Note: Variables in string form 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."