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 |
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 , campaignwill 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
}
veya