Bulk Email Service API
Mailing lists
With our API, you can create, edit, and delete mailing lists as well as perform other operations with available lists.
Create a mailing list
To create a mailing list, send a POST request to:
https://api.sendpulse.com/addressbooks |
Request parameter:
Parameter | Type | Description | |
bookName | string | Mailing list name | required |
Request example:
{
"bookName": "My New Book"
}
If request is successful, you will receive a response:
{
"id":422325
}
Response parameter:
Parameter | Type | Description |
id | int | Mailing list ID |
Edit a mailing list
To edit a mailing list, send a PUT request to:
https://api.sendpulse.com/addressbooks/{id} |
Request parameters:
Parameter | Type | Description | |
id | int | Mailing list ID | required |
name | string | Mailing list new name | required |
Request example:
{
"name": "New Name"
}
If request is successful, you will receive a response:
{
"result": true
}
Get a list of mailing lists
To get a list of all of the mailing lists that have been created, send a GET request to:
https://api.sendpulse.com/addressbooks |
Request parameters:
Parameter | Type | Description | |
limit | int | Number of records | optional |
offset | int | Offset (first record to be displayed) | optional |
When using optional parameters, form a URL of the following type:
https://api.sendpulse.com/addressbooks?limit=10&offset=5 |
If request is successful, you will receive a response:
[
{
"id":1,
"name":"My first book",
"all_email_qty":1,
"active_email_qty":0,
"inactive_email_qty":1,
"new_phones_quantity": 0,
"active_phones_quantity": 0,
"exc_phones_quantity": 0,
"creationdate":"2015-04-20 08:52:40",
"status":0,
"status_explain":"Active"
},
{
"id":2,
"name":"My second book",
"all_email_qty":6,
"active_email_qty":0,
"inactive_email_qty":6,
"new_phones_quantity": 0,
"active_phones_quantity": 0,
"exc_phones_quantity": 0,
"creationdate":"2015-04-20 09:02:39",
"status":0,
"status_explain":"Active"
}
]
Response parameters:
Parameter | Type | Description |
id | int | Mailing list ID |
name | string | Mailing list name |
all_email_qty | int | Total number of emails |
active_email_qty | int | Number of active emails |
inactive_email_qty | int | Number of inactive emails |
new_phones_quantity | int | Number of new phone numbers |
active_phones_quantity | int | Number of active phone numbers |
exc_phones_quantity | int | Number of inactive phone numbers |
creationdate | string | Date of mailing list creation |
status | int | Status code |
status_explain | string | Status explanation |
Possible mailing list status:
Status code | Status description |
0 | Active mailing list |
1 | Mailing list marked as "deleted" |
3 | Awaiting user's reply to the moderator's clarification question |
4 | Mailing list blocked by the service |
5 | Mailing list blocked by the daemon to transfer email addresses into a campaign; once unblocked, the status will change to 0 |
Get mailing list information
To get detailed information regarding a specific mailing list, send a GET request to:
https://api.sendpulse.com/addressbooks/{id} |
Request parameter:
Parameter | Type | Description | |
id | int | Mailing list ID | required |
If request is successful, you will receive a response:
[
{
"id":1,
"name":"My first book",
"all_email_qty":1,
"active_email_qty":0,
"inactive_email_qty":1,
"active_phones_quantity": 0,
"exc_phones_quantity": 0,
"creationdate":"2015-04-20 08:52:40",
"status":0,
"status_explain":"Active"
}
]
Response parameters:
Parameter | Type | Description |
id | int | Mailing list ID |
name | string | Mailing list name |
all_email_qty | int | Total number of emails |
active_email_qty | int | Number of active emails |
inactive_email_qty | int | Number of inactive emails |
active_phones_quantity | int | Number of active phone numbers |
exc_phones_quantity | int | Number of inactive phone numbers |
creationdate | string | Date of creation |
status | int | Status code |
status_explain | string | Status explanation |
Get a list of variables for a mailing list
To get a list of variables available on a mailing list, send a GET request to:
https://api.sendpulse.com/addressbooks/{id}/variables |
Request parameter:
Parameter | Type | Description | |
id | int | Mailing list ID | required |
If request is successful, you will receive a response:
[
{
"name": "email",
"type": "string"
},
{
"name": "name",
"type": "string"
},
{
"name": "date",
"type": "date"
},
{
"name": "code",
"type": "number"
}
]
Response parameters:
Parameter | Type | Description |
name | string | Variable name |
type | string | Variable type |
Get a list of emails from a mailing list
To get a list of emails from a mailing list, send a GET request to:
https://api.sendpulse.com/addressbooks/{id}/emails |
Request parameters:
Parameter | Type | Description | |
id | int | Mailing list ID | required |
limit | int | Number of records | optional |
offset | int | Offset (first record to display) | optional |
active | boolean | Use this parameter to get a list of contacts with Active and New statuses |
optional |
not_active | boolean | Use this parameter to get a list of inactive contacts. Learn more Email statuses and their description. | optional |
The method returns up to 100 records, use the limit
and offset
parameters to offset the results.
When using optional parameters, enter your URL in the following format:
https://api.sendpulse.com/addressbooks/{id}/emails?limit=10&offset=5 |
If request is successful, you will receive a response:
[
{
"email":"test@test.com",
"status": 0,
"status_explain":"New",
"variables":{
"name":"John",
"country":"UK"
}
},
{
"email":"test2@test.com",
"status": 0,
"status_explain":"New",
"variables":{
"name":"Michael",
"country":"UK"
}
}
]
Response parameters:
Parameter | Type | Description |
string | Email address | |
status | int | Email address status |
phone | string | Phone number |
status_explain | string | Status description |
variables | array | List of variables, for example, {"variable_name": "variable_value"} |
Possible email address status:
Status code | Status name | Status description |
0 | New | Newly added address; delivery to this address is blocked until the service admin activates it |
1 | Active | Delivery to this address is allowed; if the address hasn't been activated, delivery is blocked |
2 | Confirmation requested | Email has been sent to the address holder to confirm the subscription |
3 | Activation requested | Pending activation by the admin of the service |
4 | Unsubscribed | Recipient unsubscribed from emails sent by this sender |
5 | Rejected by the admin | Rejected by the service admin |
6 | Unsubscribed from all newsletters | Email address is blocked by the service admin due to recipient's complaints or recipient clicked |
7 | Activation is requested | Activation email sent to the recipient |
8 | Blocked | Email address is blocked by the user |
9 | Sending error | Emails can't be sent to this address (this status follows delivery errors) |
10 | Blocked | Email address is blocked by the list of hosts |
11 | Blocked | Email address is blocked by the sender's name |
12 | Blocked | Email address is blocked by the part of the address |
13 | Deleted by the user | Email address deleted by the user |
14 | Temporarily unavailable | Email address is temporarily unavailable |
Get the total number of contacts in a mailing list
To get the total number of contacts in a mailing list, send a GET request to:
https://api.sendpulse.com/addressbooks/{id}/emails/total |
Request parameter:
Parameter | Type | Description | |
id | int | Mailing list ID | required |
If request is successful, you will receive a response:
{
"total": 1
}
Response parameters:
Parameter | Type | Description |
total | int | Total number of email addresses in the mailing list |
Get all of the contacts in a mailing list by variable
To find all of the contacts in a mailing list by variable, send a GET request to:
https://api.sendpulse.com/addressbooks/{id}//variables/{variableName}/{searchValue} |
Request parameters:
Parameter | Type | Description | |
id | int | Mailing list ID | required |
variableName | string | Variable name | required |
searchValue | string | Variable value | required |
If request is successful, you will receive a response:
[
{
"email": "a.kozlov@art-industria.ru",
"status": 0,
"status_explain": "New"
},
{
"email": "darkling@gmail.com",
"status": 1,
"status_explain": "Active"
}
]
Response parameters:
Parameter | Type | Description |
string | Email address | |
status | int | Email address status code |
status_explain | string | Email address status description |
Add emails to a mailing list (single-opt-in)
To add emails to a mailing list, send a POST request to:
https://api.sendpulse.com/addressbooks/{id}/emails |
Request parameters:
Parameters | Type | Description | ||||
id | int | Mailing list ID | required | |||
emails | array | Serialized array of emails, for example ["example@gmail.com", "example@outlook.com"] ).
If it is necessary to add an email with variables, use this structure: |
required | |||
string | Subscriber's email address | required | ||||
variables | array |
Serialized array of variables, for example, You can use the following characters in the variable name: all Unicode alphabetic characters (regex meta group); To add a phone number, use the system variable |
required |
Request example without variables:
{
"emails":["test1@test.com", "test2@test.com"]
}
Request example with variables:
When you add a contact with variables, the email should only be under the corresponding key, as in the example below.
{
"emails":[
{
"email":"test@test.com",
"variables":{
"name":"Elizabeth",
"Phone":"380632727700"
}
},
{
"email":"test2@test.com"
}
]
}
If request is successful, you will receive a response:
{
"result": true
}
Add emails to a mailing list (double-opt-in)
To use double-opt-in (DOI) activation for recipients, add a new parameter to the request: confirmation=force
. This will require another parameter: sender_email
— provide the sender's email address as its value;
Sender's email address must be activated in your SendPulse account settings.
Request parameters:
Parameter | Type | Description | ||||
id | int | Mailing list ID | required | |||
emails | array | Serialized array of email addresses, for example ["example@gmail.com", "example@outlook.com"] .
If it is necessary to add an email with variables, use this structure: |
required | |||
string | Subscriber's email address | required | ||||
variables | array | Serialized array of variables, for example, {"name of variable":"value of variable"} |
required | |||
confirmation | string | force |
required | |||
sender_email | string | Sender's email address | required | |||
template_id | string | Confirmation email ID; it is created in the Service Settings (if the parameter is not specified, a default email will be sent); for example, a3e45169-7ae7-4a39-b457-72fd04401f26 |
optional | |||
message_lang | string | Confirmation email's language. It can take "en" , "ru" , "ua" , "tr" , "es" , "pt" values |
required |
Request example:
{
"emails":[
{
"email":"test@gmail.com",
"variables":{
"name":"Alona"
}
}
],
"confirmation":"force",
"sender_email":"sender@sendpulse.com",
"template_id":"a3e45169-7ae7-4a39-b457-72fd04401f2l",
"message_lang":"en"
}
If request is successful, you will receive a response:
{
"result": true
}
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
}
Delete emails from a mailing list
To delete emails from a mailing list, send a DELETE request to:
https://api.sendpulse.com/addressbooks/{id}/emails |
Request parameters:
Parameter | Type | Description | |
id | int | Mailing list ID | required |
emails | array | Serialized array of emails. You can specify up to 100 email addresses to delete in one request. | required |
Request example:
{
"emails": ["test1@test.com", "test2@test.com", "test3@test.com"]
}
If request is successful, you will receive a response:
{
"result": true
}
Delete a mailing list
To delete a mailing list, send a DELETE request to:
https://api.sendpulse.com/addressbooks/{id} |
Request parameters:
Parameter | Type | Description | |
id | int | Mailing list ID | required |
If request is successful, you will receive a response:
{
"result": true
}
Get the cost of a campaign carried by mailing list
To calculate the cost of a campaign carried by mailing list, send a GET request to:
https://api.sendpulse.com/addressbooks/{id}/cost |
Request parameter:
Parameter | Type | Description | |
id | int | Mailing list ID | required |
If request is successful, you will receive a response:
{
"cur": "USD",
"sent_emails_qty": 16,
"overdraftAllEmailsPrice": 0,
"addressesDeltaFromBalance": 0,
"addressesDeltaFromTariff": 16,
"max_emails_per_task": 500,
"result": true
}
Response parameters:
Parameter | Type | Description |
cur | string | Currency used for calculation |
sent_emails_qty | int | Total number of email addresses |
overdraftAllEmailsPrice | int | Price for exceeding the email address limit |
addressesDeltaFromBalance | int | Number of email addresses user balance will be charged for |
addressesDeltaFromTariff | int | Number of email addresses that will be charged by the tariff |
max_emails_per_task | int | Email address tariff restrictions |
result | boolean | Determines whether there is enough money (true or false ) |
Campaigns
Create a campaign
To create an email campaign, send a POST request to:
https://api.sendpulse.com/campaigns |
Please note that you can send a maximum of 4 campaigns per hour.
Request parameters:
Parameter | Type | Description | ||||
sender_name | string | Sender's name | required | |||
sender_email | string | Sender's email address | required | |||
subject | string | Email subject | required | |||
body1 | string | HTML code of the template, encoded in Base64 | required | |||
template_id1 | int/string | Template ID uploaded or created in the service. Use Get a list of all templates method to get the template ID (use either real_id or id parameter from the reply) |
required | |||
list_id2 | int/array |
Mailing list ID or array of mailing list ID's (for example, If you send a test campaign with the |
required | |||
segment_id2 | int | Segment ID created in your account (Mailing lists -> select mailing list -> Segments > My segments-> select segment -> copy segment id from URL in address bar) | required | |||
is_test | boolean | Is used to send a test email to the sender's address specified in the sender_email parameter |
optional | |||
send_date | string | Date of the scheduled email campaign (optional parameter), must fit the following format: Y-m-d H:i:s (for example: 2016-02-02 23:34:23 ) and can not be less than the current date and time |
optional | |||
name | string | Campaign name | optional | |||
use_dynamic_list | boolean | Used to send to a dynamic list for scheduled email сampaign. 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. | optional | |||
attachments | array | Attached files, you can add up to 5 items in which the key is the name of the attachment, and the value is the content of the attachment {"name1.extension": "content_1_file", "name2.extension": "content_2_file"} |
optional | |||
attachments_binary | array | Attached files, you can add up to 5 items in which the key is the name of the attachment, and the value is the content of the attachment {"name1.extension": "base64_content_1_file", "name2.extension": "base64_content_2_file"} |
optional | |||
type | string | Possible value - draft [a campaign will be created as a draft] |
optional | |||
body_amp3 | string | AMP version of the email, encoded in base64 | optional | |||
stats | object |
Used to enable the collection of statistics on email opens and link clicks
|
optional | |||
clicks
|
bool
|
Click on links. By default —
true |
optional
|
|||
opens
|
bool | Campaign opens. By default — true |
optional | |||
utm_campaign | string | Adds custom UTM tags in all links in your campaing for Google Analytics and Yandex.Metrica | optional |
1. To specify the body of your email, you can send your template directly in the request using the body
parameter, or use a template created in the service using the template_id
parameter. One of the two parameters is required.
2. To specify the list of recipients, you can use the list_id
or segment_id
parameter, one of the two parameters is required.
3. The AMP body code must be valid and can be used only after confirmation from google and mail.ru. You can submit an application for consideration in the Service Settings.
Example of a request to create a campaign with a template:
{
"sender_name":"my_sender_name",
"sender_email":"my_sender@test.com",
"subject":"hello customer",
"list_id":"756589",
"name":"my_api_campaign",
"template_id": "775667"
}
Example of a request to create a scheduled campaign to a dynamic list:
{
"sender_name":"API_TEST",
"sender_email":"my_sender@test.com",
"subject":"API campaign",
"list_id":"756589",
"name":"api campaign",
"body": "SmFja2llIENoYW4=",
"send_date":"2016-02-02 23:34:23",
"use_dynamic_list": true
}
Example of a request to create a draft:
{
"sender_name":"my_sender_name",
"sender_email":"my_sender@test.com",
"subject":"hello customer",
"list_id":"756589",
"name":"my_api_campaign",
"body": "bXkgYXBpIGJvZHk=",
"type":"draft"
}
Example of a request to create a campaign with an attachment:
{
"sender_name":"my_sender_name",
"sender_email":"my_sender@test.com",
"subject":"hello customer",
"list_id":"756589",
"name":"my_api_campaign",
"body": "bXkgYXBpIGJvZHk=",
"attachments":{
"text.txt":"my content file"
}
}
Example of a request to create a campaign with an attachment (attachments_binary):
{
"sender_name":"my_sender_name",
"sender_email":"my_sender@test.com",
"subject":"hello customer",
"list_id":"756589",
"name":"my_api_campaign",
"body": "bXkgYXBpIGJvZHk=",
"attachments_binary":{
"text.txt":"bXkgY29udGVudCBmaWxlIGluIGJhc2U2NA=="
}
}
Example of a request to create a campaign with a custom collecting statistic options:
{
"sender_name":"my_sender_name",
"sender_email":"my_sender_email@test.com",
"subject":"API campaign",
"list_id":"89286777",
"name":"My Campaign",
"body": "SmFja2llIENoYW4=",
"stats":{
"opens":true, //enabled collection of opens statistics
"clicks":false, //disabled collection of clicks statistics
"utm_campaign":"MY_UTM"
}
}
If request is successful, you will receive a response:
{
"id": 245587,
"status": 13,
"count": 1,
"tariff_email_qty": 1,
"overdraft_price": "0.0044",
"ovedraft_currency": "RUR"
}
Response parameters:
Parameter | Type | Description |
id | int | Email campaign ID |
status | int | Task status for sending (13 - copying addresses for sending, 26 - draft) |
count | int | Number of recipients to which the campaign is sent |
tariff_email_qty | int | Number of emails written off from the user's balance |
overdraft_price | string | Price for one email at an increase |
ovedraft_currency | string | Currency |
Edit scheduled campaign
To edit scheduled campaign, send a PATCH request to:
https://api.sendpulse.com/campaigns/{id} |
Request parameters:
Parameter | Type | Description | |
id | int | Email campaign ID | required |
name | string | Email campaign name | required |
sender_name | string | Sender's name | required |
sender_email | string | Sender's email address | required |
subject | string | Email subject | required |
body | string | HTML code of template, encoded in base64 | required |
template_id | int/string | Template ID uploaded in the service. Use Get a list of all templates on an account method to get the template ID (use either real_id or id parameter from the response) |
required |
send_date | string | Date of the scheduled email campaign (optional parameter). Must fit the following format: Y-m-d H:i:s (for example, 2016-02-02 23:34:23 ) and can not be less than the current date and time |
optional |
Request example:
{
"name":"my_api_campaign",
"sender_name":"Sender",
"sender_email":"sender@gmail.com",
"subject":"Hello customer",
"template_id":123348,
"send_date":"2021-07-06 11:45:00"
}
If request is successful, you will receive a response:
{
"result": true,
"id": 470791
}
Get campaign information
To get campaign information, send a GET request to:
https://api.sendpulse.com/campaigns/{id} |
Request parameter:
Parameter | Type | Description | |
id | int | Email campaign ID | required |
If request is successful, you will receive a response:
{
"id": 14973974,
"name": "test check link",
"is_sms": false,
"is_viber": false,
"message": {
"sender_name": "test",
"sender_email": "e.b@sendpulse.com",
"subject": "test check link",
"body": "<!DOCTYPE html><html>...</html>",
"preheader": "",
"attachments": "",
"list_id": 89311111
},
"external_stat": {
"check_open_email": true,
"check_redirect_link": true
},
"status": 3,
"all_email_qty": 2,
"tariff_email_qty": 2,
"paid_email_qty": 0,
"overdraft_price": 0,
"company_price": "0.05",
"overdraft_currency": "UAH",
"send_date": "2021-09-01 10:55:39",
"permalink": "http://archive.sendpulse.com//u/NzA0MzY2sdghM34w==/8wxdgwz43q/",
"statistics": {
"general": [
{
"code": 0,
"count": 0,
"explain": "In queue"
},
{
"code": 1,
"count": 2,
"explain": "Sent"
},
{
"code": 2,
"count": 2,
"explain": "Delivered"
},
{
"code": 3,
"count": 2,
"explain": "Opened"
},
{
"code": 4,
"count": 2,
"explain": "Link redirected"
},
{
"code": 5,
"count": 0,
"explain": "User unsubscribe"
},
{
"code": 6,
"count": 0,
"explain": "Mail server answer :: No such email"
},
{
"code": 7,
"count": 0,
"explain": "Temporary unavailable (will be sent later)"
},
{
"code": 8,
"count": 0,
"explain": "Unavailable"
},
{
"code": 9,
"count": 0,
"explain": "Mail server answer :: Rejected by server as spam"
},
{
"code": 10,
"count": 0,
"explain": "Mail server answer :: Mailbox is full"
},
{
"code": 11,
"count": 0,
"explain": "Mail server answer :: Marked as spam by user"
},
{
"code": 12,
"count": 0,
"explain": "Delivery failure"
},
{
"code": 13,
"count": 0,
"explain": "Not sent"
},
{
"code": 14,
"count": 0,
"explain": "Not such domain"
},
{
"code": 15,
"count": 0,
"explain": "Unsubscribe from newsletter"
},
{
"code": 16,
"count": 0,
"explain": "Not valid email"
},
{
"code": 17,
"count": 0,
"explain": "Temporary blocked"
},
{
"code": 18,
"count": 0,
"explain": "Disable by administrator"
},
{
"code": 20,
"count": 0,
"explain": "Already unsubscribed"
}
],
"clicks": [
{
"url": "https://s7043663.sendpul.se/views/ru/{{CampaignId}}/{{EmailCode}}/h/e5203e703e95d001c286990chdfh45fc87ee",
"count": 0
},
{
"url": "https://habr.com/ru/all/",
"count": 3
},
{
"url": "",
"count": 0
},
{
"url": "https://sendpulse.com/ru/email-powered-by-sendpulse?sn=d3BsgjksfsfhadGVzdA%3D%3D&amp;from=70474573563663",
"count": 0
}
]
}
}
Possible campaign statuses:
Status code | Status description |
0 | New |
1 | Pending (in moderation) |
2 | Sending in progress |
3 | Sent |
4 | Test campaign (sent to user's email address) |
5 | Campaign blocked (by the service) |
6 | The campaign marked to be deleted |
7 | Status updating (status 3 will follow) |
8 | Test campaign sent |
9 | Delivery in progress |
10 | The campaign being processed to be sent out |
11 | Awaiting the user's response to the moderator's query |
12 | No active addresses |
13 | Campaign creation in progress — emails are transferring into the campaign from the mailing list. Status 2 will follow if there are less than 20 emails on the list; otherwise, code 1 will follow. |
14 | Campaign created and sent to the queue. Status 3 will follow when all messages are sent. |
15 | Campaign awaiting A/B testing results |
16 | Campaign canceled by a user |
22 | Sending partially |
23 | Sent partially |
25 | Campaign partially sent and blocked by service admin |
26 | Draft |
27 | Requires editing |
28 | Scheduled to resend the message to unread |
33 | Automations. Balance exceeded |
36 | Automations draft |
Get a list of campaigns
To get a list of campaigns, send a GET request to:
https://api.sendpulse.com/campaigns |
Request parameters:
Parameter | Type | Description | |
limit | int | Number of records | optional |
offset | int | Offset (first record to display) | optional |
order | string | Sort parameter, asc — from highest to lowest, desc — from lowest to highest |
optional |
status | array | List of email campaign statuses (int) | optional |
planed | boolean | A parameter that allows you to return scheduled campaigns | optional |
When using optional parameters, form a URL of the following type:
https://api.sendpulse.com/campaigns?order=desc&status[]=3&planed=1&limit=100&offset=10 |
If request is successful, you will receive a response:
[
{
"id": 14911111,
"name": "test check link",
"status": 3,
"is_sms": false,
"is_viber": false,
"send_date": "2021-09-01 10:55:39",
"all_email_qty": 2,
"tariff_email_qty": 2,
"paid_email_qty": 0,
"overdraft_price": 0,
"company_price": "0.05",
"overdraft_currency": "UAH",
"message": {
"sender_name": "test",
"sender_email": "e.b@sendpulse.com",
"subject": "test check link",
"attachments": "",
"list_id": 89311111
},
"statistics": {
"sent": 2,
"delivered": 2,
"opening": 2,
"link_redirected": 2,
"unsubscribe": 0,
"error": 0
}
}
]
Response parameters:
Parameter | Type | Description |
id | int | Email campaign ID |
name | string | Email campaign name |
is_sms | boolean | Parameter that determines whether this campaign is an SMS campaign |
is_viber | boolean | Parameter that determines whether this campaign is a Viber campaign |
send_date | string | Campaign sending date |
company_price | string | Campaign price |
sender_name | string | Sender's name |
sender_email | string | Sender's email address |
subject | string | Email subject |
body | string | Email body |
list_id | int | Mailing list ID |
attachments | string | Attachments |
status | int | Email campaign status code |
all_email_qty | int | Total number of email addresses |
tariff_email_qty | int | Number of emails written off the user's balance |
paid_email_qty | int | Number of email addresses paid from the balance above the tariff limit |
overdraft_price | int | Price per letter if exceeded |
overdraft_currency | string | Currency |
sent | int | Sent message total |
delivered | int | Delivered messages total |
opening | int | Opened messages total |
link_redirected | int | Number of link redirections |
unsubscribe | int | Unsubscribed users total |
error | int | Errors number |
Get a list of campaigns created that use a specific mailing list
To get a list of campaigns created that use a specific mailing list, send a GET request to:
https://api.sendpulse.com/addressbooks/{id}/campaigns |
Request parameters:
Parameter | Type | Description | |
id | int | Mailing List ID | required |
limit | int | Number of records | optional |
offset | int | Offset (first record to display) | optional |
If request is successful, you will receive a response:
[
{
"task_id": 9147593,
"task_name": "Test",
"task_status": 3
},
{
"task_id": 9156095,
"task_name": "Campaign_6741804_UM99",
"task_status": 3
}
]
Response parameters:
Parameter | Type | Description |
task_id | int | Email campaign ID |
task_name | string | Email campaign name |
tast_status | int | Email campaign status code |
Get a country statistics
To get a country statistics, send a GET request to:
https://api.sendpulse.com/campaigns/{id}/countries |
Request parameter:
Parameter | Type | Description | |
id | int | Email campaign ID | required |
If request is successful, you will receive a response:
{
"US": 23,
"UA": 34567
}
Response parameters:
Parameter | Type | Description |
US (UA) | int | Emails opened |
Get referrals statistics
To get referrals statistics, send a GET request to:
https://api.sendpulse.com/campaigns/{id}/referrals |
Request parameter:
Parameter | Type | Description | |
id | int | Email campaign ID | required |
If request is successful, you will receive a response:
[
{
"link": "http://first_link.com"
"count": 123454
},
{
"link": "http://second_link.com"
"count": 5463
}
]
Response parameters:
Parameter | Type | Description |
link | string | URL from the email |
count | int | Number of link clicks |
Cancel a campaign
To cancel a campaign, send a DELETE request to:
https://api.sendpulse.com/campaigns/{id} |
Request parameter:
Parameter | Type | Description | |
id | int | Email campaign ID | required |
If request is successful, you will receive a response:
{
"result": true
}
Templates
Create a template
To create a template, send a POST request to:
https://api.sendpulse.com/template |
Request parameters:
Parameter | Type | Description | |
name | string | Name of the template (the parameter is optional, if not specified, the name will be displayed as Template YYYY.mm.dd H:i:s ) |
required |
body | string | HTML version of the email, encoded in base64 | required |
lang | string | Template language, can take "ru" , "en" , "ua" , "tr" , "es" , "pt" values |
required |
Request example:
{
"name": "My Template",
"body": "PGlucHV0IHR5cGU9ImVtYWlsIiBuYW1lPSJlbWFpbCIgcmVxdWlyZWQKb25pbnZhbGlkPSJ0aGlzLnNldEN1c3RvbVZhbGlkaXR5KCfQn9C+0LbQsNC70YPQudGB0YLQsCwg0L3QsNC/0LjRiNC40YLQtSBlbWFpbCDQu9Cw0YLQuNC90YHQutC40LzQuCDQsdGD0LrQstCw0LzQuCcpIiBvbmlucHV0PSJzZXRDdXN0b21WYWxpZGl0eSgnJykiIC8+",
"lang": "ru"
}
If request is successful, you will receive a response:
{
"result": true,
"real_id": 1042220
}
Response parameter:
Parameter | Type | Description |
real_id | int | Created template ID |
Edit a template
To edit a template, send a POST request to:
https://api.sendpulse.com/template/edit/{id} |
Request parameters:
Parameter | Type | Description | |
id | int/string | Template ID uploaded in the service. Use Get a list of all templates on an account method to get the template ID (use either real_id or id parameter from the reply) |
required |
body | string | HTML version of the email, encoded in base64 | required |
lang | string | Template language | optional |
Please note that the template language lang
must be the one that was specified during the creation of this template.
Request example:
{
"body": "PGlucHV0IHR5cGU9ImVtYWlsIiBuYW1lPSJlbWFpbCIgcmVxdWlyZWQKb25pbnZhbGlkPSJ0aGlzLnNldEN1c3RvbVZhbGlkaXR5KCfQn9C+0LbQsNC70YPQudGB0YLQsCwg0L3QsNC/0LjRiNC40YLQtSBlbWFpbCDQu9Cw0YLQuNC90YHQutC40LzQuCDQsdGD0LrQstCw0LzQuCcpIiBvbmlucHV0PSJzZXRDdXN0b21WYWxpZGl0eSgnJykiIC8+",
"lang": "ru"
}
If request is successful, you will receive a response:
{
"result" : true
}
Get information about a template
To get information about template, send a GET request to:
https://api.sendpulse.com/template/{template_id} |
Request parameters:
Parameter | Type | Description | |
template_id | int/string | Template ID uploaded in the service. Use Get a list of all templates on an account method to get the template ID (use either real_id or id parameter from the reply) |
required |
If request is successful, you will receive a response:
{
"id":"f3266876955c9d21e214deed49b97446",
"real_id":1153018,
"lang":"en",
"name":"Webinar Speakers",
"name_slug":"",
"created":"2020-09-04 13:54:30",
"full_description":"Use this template as a webinar invitation for your subscribers. Specify who is going to host the webinar and what it will be about. Remember to include the date and time of the webinar.",
"is_structure":true,
"category":"education",
"category_info":{
"id":109,
"name":"Education",
"meta_description":"These “Education” free email templates were developed by SendPulse for all those who wish to make their email communication colorful and unforgettable. You can use these templates to create your email campaigns in SendPulse.",
"full_description":"",
"code":"education",
"sort":6
},
"tags":{
"webinar":"webinar",
"study":"study",
"marketing":"marketing",
"museum":"museum",
"exhibition":"exhibition"
},
"owner":"sendpulse",
"preview":"https://login.sendpulse.com/files/emailservice/userfiles/templates/preview/f3266876955c9d21e214deed49b97446_thumbnail_300.png"
}
Get a List of Templates on an Account
To get a list of templates on an account, send a GET request to:
https://api.sendpulse.com/templates |
If request is successful, you will receive a response:
[
{
"id":"c7a94d4f8395ae5a4183423309d5e99b",
// Please note, value changes each time you edit template
"real_id":775667,
"lang":"en",
"name":"Nov. 9, 2018 08:24:10",
"name_slug":"nov-9-2018-08-24-10",
"created":"2018-11-09 05:24:10",
"full_description":null,
"category":"",
"category_info":[
],
"tags":[
],
"owner":"you",
"preview":"https://login.sendpulse.com/files/emailservice/templates/preview/e52678826db12b069358f159fde800726741804/c7a94d4f8395ae5a4183423309d5e99b.png"
},
{
"id":"5979adc7712b8c822a28b486f9778a15",
"real_id":508742,
"lang":"en",
"name":"Valentine\\'s Day: sweet",
"name_slug":"sweet-valentines-day",
"created":"2018-02-01 08:55:04",
"full_description":"",
"category":"holiday",
"category_info":{
"id":146,
"name":"Holiday",
"meta_description":"These “Holiday” free email templates were developed by SendPulse. Congratulate your customers, friends or relatives. Use these templates to create your own email campaigns in SendPulse.",
"full_description":"",
"code":"holiday",
"sort":2
},
"tags":{
"valentine":"valentine"
},
"owner":"sendpulse",
"preview":"https://login.sendpulse.com/files/emailservice/templates/preview/5979adc7712b8c822a28b486f9778a15_thumbnail.png"
}
]
Get a list of all system templates
To get a list of all system templates, send a GET request to:
https://api.sendpulse.com/templates/?owner=sendpulse |
Get a list of all user templates
To get a list of all user templates, send a GET request to:
https://api.sendpulse.com/templates/?owner=me |
Get a template by name
To get a template by name, send a GET request to:
https://api.sendpulse.com/template/slug/{name_slug} |
Request parameter:
Parameter | Type | Description | |
name_slug | string | System name of the template, you can find it in the API response for creating or searching for templates by other parameters | required |
Get a list of all templates in a specific language
To get a list of all templates in a specific language, send a GET request to:
https://api.sendpulse.com/templates/ru/?owner=me |
Senders
Get a list of all senders
To get a list of all senders, send a GET request to:
https://api.sendpulse.com/senders |
If request is successful, you will receive a response:
[
{
"email": "user1@example.com",
"name": "user1",
"status": "Active",
"is_allowed_for_smtp": true*
},
{
"email": "user2@example.com",
"name": "user2",
"status": "Active",
"is_allowed_for_smtp": false*
}
Response parameters:
Parameter | Type | Description | |
name | string | Sender name | |
string | Sender email | ||
status | string | Sender status | |
is_allowed_for_smtp | boollean | Specifies whether an email address is allowed in the SMTP service. SendPulse has merged sender email addresses for the Email and SMTP service. For all email addresses you add after 2023-05-17, the Email service will add a parameter with the true value, which means that you can use these email addresses in the SMTP service as well. |
Add a sender
To add a sender, send a POST request to:
https://api.sendpulse.com/senders |
SendPulse has merged sender email addresses for the Email and SMTP service. You can use email addresses you add to the Email service after 2023-05-17 in the SMTP service as well.
Request parameters:
Parameters | Type | Description | |
string | Sender’s email address | required | |
name | string | Sender’s name | required |
Request example:
{
"email": "sender@example.com",
"name": "Sender"
}
If request is successful, you will receive a response:
{
"result": true
}
Delete a sender
To delete a sender, send a DELETE request to:
https://api.sendpulse.com/senders |
Request parameter:
Parameter | Type | Description | |
string | Sender’s email address | required |
Request example:
{
"email": "sender@example.com"
}
If request is successful, you will receive a response:
{
"result": true
}
Activate a sender
To activate a sender, send a POST request to:
https://api.sendpulse.com/senders/{email}/code |
Request parameters:
Parameter | Type | Description | |
string | Sender's email address | required | |
code | string | Activation code | required |
Request example:
{
"code": "50405325fdbb31e79759e7b8ae305ef75"
}
If request is successful, you will receive a response:
{
"result": true,
"email": JohnDoe@test.com
}
Get an activation code to the sender’s email address
To get an activation code to the sender's email address, send a GET request to:
https://api.sendpulse.com/senders/{email}/code |
Request parameter:
Parameter | Type | Description | |
string | Sender's email address | required |
If request is successful, you will receive a response:
{
"result": true,
"email": JohnDoe@test.com
}
If the request was successful, the sender will receive an email with the activation code.
Email address
Get general information about a specific email address
To get general information about a specific email address, send a GET request to:
https://api.sendpulse.com/emails/{email} |
Request parameter:
Parameter | Type | Description | |
string | Email address | required |
If request is successful, you will receive a response:
[
{
"book_id":154441,
"email":"test@gmail.com",
"status":0,
"status_explain":"New",
"variables":[]
},
{
"book_id":422325,
"email":"test@gmail.com",
"status":1,
"status_explain":"Active",
"variables":[
{
"name":"Name",
"type":"string",
"value":"Alona"
}
]
}
]
Get detailed information about a specific email address
To get detailed information about a specific email address, send a GET request to:
https://api.sendpulse.com/emails/{email}/details |
Request parameter:
Parameter | Type | Description | |
string | Email address | required |
If request is successful, you will receive a response:
[
{
"list_name": "test1",
"list_id": 1375516,
"add_date": "2017-11-21 11:45:41",
"source": "panel"
},
{
"list_name": "test2",
"list_id": 1415158,
"add_date": "2018-01-23 07:07:08",
"source": "panel"
},
{
"list_name": "subscriptions",
"list_id": 1649207,
"add_date": "2018-04-02 13:55:38",
"source": "form"
}
]
Get general information for a list of email addresses
To get general information for a list of email addresses, send a POST request to:
https://api.sendpulse.com/emails |
Request parameter:
Parameter | Type | Description | |
emails | array | List of email adresses | required |
Request example:
{
"emails": ["test1@gmail.com", "test2@gmail.com"]
}
If request is successful, you will receive a response:
{
"test1@gmail.com":[
{
"book_id":154441,
"status":0,
"variables":[]
},
{
"book_id":422325,
"status":1,
"variables":[
{
"name":"Name",
"type":"string",
"value":"Test"
}
]
}
],
"test2@gmail.com":[
{
"book_id":422325,
"status":1,
"variables":[
{
"name":"Name",
"type":"string",
"value":"Test"
}
]
}
]
}
Get information for a specific email address from a specific campaign
To get information for a specific email address from, send a GET request to:
https://api.sendpulse.com/campaigns/{id}/email/{email} |
Request parameters:
Parameter | Type | Description | |
id | int | Email campaign ID | required |
string | Email address | required |
If request is successful, you will receive a response:
{
"sent_date": "2021-03-29 07:46:58",
"global_status": 1,
"global_status_explain": "Sent",
"detail_status": 3,
"detail_status_explain": "Opened"
}
Response parameters:
Parameter | Type | Description |
send_date | string | Date of sending the email campaign |
global_status | int | Global email campaign status code |
global_status_explain | string | Global status description |
detail_status | int | Detailed email campaign status code |
detail_status_explain | string | Detailed status description |
Get information for an email address from a mailing list
To get information for an email address from a mailing list, send a GET request to:
https://api.sendpulse.com/addressbooks/{id}/emails/{email} |
Request parameters:
Parameter | Type | Description | |
id | int | Mailing list ID | required |
string | Email address | required |
If request is successful, you will receive a response:
{
"email": "test@gmail.com",
"abook_id": "422325",
"phone": "",
"status": 1,
"status_explain": "Active",
"variables": [
{
"name": "Name",
"type": "string",
"value": "Test"
}
]
}
Response parameters:
Parameter | Type | Description | ||
string | Email address | |||
abook_id | string | Mailing list ID | ||
phone | string | Phone number | ||
status | int | Email address status code | ||
status_explain | string | Email address status description | ||
variables | array | Array of variables for the email (equals [] if the contact has no variables, or the variable is empty): |
||
name | string | Variable name | ||
type | string | Variable type | ||
value | string | Variable value |
Delete an email address from all mailing lists
To delete an email address from all mailing lists, send a DELETE request to:
https://api.sendpulse.com/emails/{email} |
Request parameter:
Parameter | Type | Description | |
string | Email address | required |
If request is successful, you will receive a response:
{
"result": true
}
Get statistics for an email address and campaigns it is in
To get statistics for an email address and campaigns it is in, send a GET request to:
https://api.sendpulse.com/emails/{email}/campaigns |
Request parameter:
Parameter | Type | Description | |
string | Email address | required |
If request is successful, you will receive a response:
{
"statistic": {
"sent": 9,
"open": 2,
"link": 0
},
"blacklist": false,
"addressbooks": [
{
"id": 154441,
"address_book_name": "Mailing list 1"
},
{
"id": 154472,
"address_book_name": "Mailing list 2"
}
]
}
Get statistics for multiple email addresses and campaigns they are in
To get statistics for multiple email addresses and campaigns they are in, send a POST request to:
https://api.sendpulse.com/emails/campaigns |
Request parameter:
Parameter | Type | Description | |
emails | array | List of email addresses | required |
Request example:
{
"emails": ["example@yourdomain.com", "example2@yourdomain.com"]
}
If request is successful, you will receive a response:
{
"example@yourdomain.com": {
"sent": 21,
"open": 11,
"link": 3,
"adressbooks": [
{
"id": 1375516,
"name": "book1"
},
{
"id": 1415158,
"name": "book3"
},
{
"id": 1649207,
"name": "book10"
}
],
"blacklist": false
},
"example2@yourdomain.com": {
"sent": 1,
"open": 1,
"link": 0,
"adressbooks": [
{
"id": 1734397,
"name": "тест1"
}
],
"blacklist": true
}
}
Change a variable for an email contact
To change a variable for an email, send a POST request to:
https://api.sendpulse.com/addressbooks/{addressBookId}/emails/variable |
Request parameters:
Parameter | Type | Description | |
addressBookId | int | Mailing list ID | required |
string | Email contact address | required | |
variables | array | List of variables, for example, {"name":"name", "value":"John"} |
required |
Request example:
{
"email":"myemail@example.com",
"variables":[
{
"name":"name",
"value":"John"
},
{
"name":"date",
"value":"2019-02-01"
}
]
}
If request is successful, you will receive a response:
{
"result": true
}
You can change only one email per request
Variables of string
type accept either numeric values or values expressing the date in the following format: YYYY-MM-DD
.
Variables of number
type accepts only numbers.
Variable of date
type only accepts a date 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
.
Blacklist
Get a list of contacts in blacklist
To view the blacklist, send a GET request to:
https://api.sendpulse.com/blacklist |
If request is successful, you will receive a response:
[
"JohnDoe@test.com",
"JaneDoe@test.com",
]
Add an email address to blacklist
To add to blacklist an email address, send a POST request to:
https://api.sendpulse.com/blacklist |
Request parameters:
Parameter | Type | Description | |
emails | string | Email addresses separated by commas and encoded in Base64 | required |
comment | string | Comment | optional |
Request example:
{
"emails": "dXNlcjFAbWFpbHNlcnZlci5jb20sdXNlcjJAbWFpbHNlcnZlci5jb20sdXNlcjNAbWFpbHNlcnZlci5jb20=",
"comment": "comment"
}
If request is successful, you will receive a response:
{
"result": true
}
Unsubscribe a contact from a specific mailing list
To unsubscribe a contact from a specific mailing list, send a POST request to:
https://api.sendpulse.com/addressbooks/{id}/emails/unsubscribe |
Request parameters:
Parameter | Type | Description | |
id | int | Mailing list ID | required |
emails | array | List of email addresses that you want to unsubscribe from the defined mailing list | required |
Request example:
{
"emails": ["test1@gmail.com","test2@gmail.com"]
}
If request is successful, you will receive a response:
{
"result": true
}
Delete an email address from the blacklist
To delete an email address from the blacklist, send a DELETE request to:
https://api.sendpulse.com/blacklist |
Request parameters:
Parameter | Type | Description | |
emails | string | List of email addresses separated by commas and encoded in base64 | required |
Example of a string with email addresses (before base64 encoding):
user1@mailserver.com,user2@mailserver.com,user3@mailserver.com
Request example:
{
"emails": "dXNlcjFAbWFpbHNlcnZlci5jb20sdXNlcjJAbWFpbHNlcnZlci5jb20sdXNlcjNAbWFpbHNlcnZlci5jb20="
}
If request is successful, you will receive a response:
{
"result": true
}
Balance
Get your balance information
To get your balance information, send a GET request to:
https://api.sendpulse.com/balance |
An optional request parameter — the currency value.
When using an optional parameter, form a URL of the following format:
https://api.sendpulse.com/balance/USD |
If request is successful, you will receive a response:
{
"currency": "USD",
"balance_currency": 0.02
}
Get detailed balance information
To get detailed balance information, send a GET request to:
https://api.sendpulse.com/user/balance/detail |
If request is successful, you will receive a response:
{
"balance": {
"main": "9.36",
"bonus": "5.00",
"currency": "USD"
},
"email": {
"tariff_name": "Pay as you go 10 000",
"finished_time": "2019-04-25 08:03:02",
"emails_left": 9914,
"maximum_subscribers": 10000,
"current_subscribers": 0
},
"smtp": {
"tariff_name": "SMTP Free",
"end_date": "2018-11-21 15:05:39",
"auto_renew": 1
},
"push": {
"tariff_name": "White Label",
"end_date": "2018-11-30",
"auto_renew": 1
}
}
Webhooks
For more information about webhooks, how to connect them in your personal SendPulse account, and examples of the received webhooks format for events, check out the article How to connect webhooks in an email service.
You can also create, edit and receive information about webhooks through the following API methods:
Get a list of webhooks
To get a list of webhooks, send a GET request to:
https://api.sendpulse.com/v2/email-service/webhook |
If request is successful, you will receive a response:
{
"success": true,
"data": [
{
"id": 162242,
"user_id": 7043663,
"url": "https://site.com/callback",
"action": "unsubscribe"
},
{
"id": 162241,
"user_id": 7043663,
"url": "https://site.com/callback",
"action": "open"
}
]
}
Get a webhook by ID
To get a webhook by ID, send a GET request to:
https://api.sendpulse.com/v2/email-service/webhook/{id} |
Request parameters:
Parameter | Type | Description | |
id | int | Webhook ID | required |
If request is successful, you will receive a response:
{
"success": true,
"data": {
"id": 162242,
"user_id": 7043663,
"url": "https://site.com/callback",
"action": "unsubscribe"
}
}
Create a webhook
To create a webhook, send a POST request to:
https://api.sendpulse.com/v2/email-service/webhook/ |
Request parameters:
Parameter | Type | Description | |
actions | string/array | Tracked events, for example, ["open","unsubscribe"] |
required |
url | string | URL to the handler, for example, https://site.com/callback | required |
Possible values for actions:
Action | Description |
new_emails | Adding a new email address |
delete | Email address deleted from the mailing list |
unsubscribe | User unsubscribed |
task_status_update | Campaign status changed |
open | Campaign was opened |
delivered | Delivered |
redirect | Following link |
spam | User marked as spam |
hard_bounces | Received Hard Bounce |
soft_bounces | Received Soft Bounce |
The data is sent with the x-www-form-urlencoded
type.
Request example:
{
"url":"https://site.com/callback",
"actions":["delivered"]
}
If request is successful, you will receive a response:
{
"success": true,
"data": [
{
"user_id": 7043663,
"url": "https://site.com/callback",
"id": 162241,
"action": "open"
},
{
"user_id": 7043663,
"url": "https://site.com/callback",
"id": 162242,
"action": "unsubscribe"
}
]
}
Delete a webhook
To delete a webhook, send a DELETE request to:
https://api.sendpulse.com/v2/email-service/webhook/{id} |
Request parameter:
Parameter | Type | Description | |
id | int | Webhook ID | required |
If request is successful, you will receive a response:
{
"success": true,
"data": [
true
]
}
Update a webhook
To update a webhook, send a PUT request to:
https://api.sendpulse.com/v2/email-service/webhook/{id} |
The data is sent with the x-www-form-urlencoded type.
Request parameters:
Parameter | Type | Description | |
id | int | Webhook ID | required |
url | string | URL to the handler, for example, https://site.com/callback | required |
If request is successful, you will receive a response:
{
"success": true,
"data": [
true
]
}
или