Mailing Lists
With our API, you can create, edit, and delete mailing lists as well as perform other operations with available lists.
Creating a Mailing List
To create a mailing list, send a POST request to:
https://api.sendpulse.com/addressbooks |
Request parameter:
bookName | name of the book |
If successful, our server will return a response with the ID of the created mailing list.
Editing the Name of a Mailing List
To edit a mailing list, send a PUT request to:
https://api.sendpulse.com/addressbooks/{id} |
Request parameters:
id | the mailing list ID |
name | the new name of the list |
If successful, the server will return the response "result = true"
To retrieve a list of all of the mailing lists that have been created, along with detailed information on each of them, a GET request is sent to:
https://api.sendpulse.com/addressbooks |
Request parameters (optional):
limit | the number of records |
offset | offset (first record to be displayed) |
When using optional parameters, form a URL of the following type:
https://api.sendpulse.com/addressbooks?limit=10&offset=5 |
Response parameters:
id | List ID |
name | List name |
all_email_qty | Total number of emails |
active_email_qty | Number of active emails |
inactive_email_qty | Number of inactive emails |
creationdate | Date of creation |
status | Status code |
status_explain | Status explanation |
Sample response to retrieving a list of mailing lists:
[
{
"id": "1",
"name": "My first list",
"all_email_qty": "1",
"active_email_qty": "0",
"inactive_email_qty": "1",
"creationdate": "2015-04-20 08:52:40",
"status": "0",
"status_explain": "Active"
},
{
"id": "2",
"name": "My second list",
"all_email_qty": "6",
"active_email_qty": "0",
"inactive_email_qty": "6",
"creationdate": "2015-04-20 09:02:39",
"status": "0",
"status_explain": "Active"
}
]
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» |
Retrieving Mailing List Information
To retrieve detailed information regarding a specific mailing list, a GET request is sent to:
https://api.sendpulse.com/addressbooks/{id} |
Response Parameters:
id | List ID |
name | List name |
all_email_qty | Total number of emails |
active_email_qty | Number of active emails |
inactive_email_qty | Number of inactive emails |
creationdate | Date of creation |
status | Status code |
status_explain | Status explanation |
Sample response to retrieving mailing list information:
[
{
"id": "1",
"name": "My first list",
"all_email_qty": "1",
"active_email_qty": "0",
"inactive_email_qty": "1",
"creationdate": "2015-04-20 08:52:40",
"status": "0",
"status_explain": "Active"
}
]
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 the campaign; once unblocked, the status will change to «0» |
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 the URL
https://api.sendpulse.com/addressbooks/{id}/variables |
Request parameters:
id | mailing list identifier |
Retrieving a List of Emails from a Mailing List
Submit a GET request to:
https://api.sendpulse.com/addressbooks/{id}/emails |
Request parameters:
id | mailing list identifier |
limit | number of entries, optional |
offset | offset (starting the first record to display), 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 |
Sample 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"
}
}
]
Sample response if variable's value is empty:
[
{
"email": "test@test.com",
"status": 0,
"phone": "",
"status_explain": "New",
"variables": []
}
]
Possible mailing list status:
Status code | Status description |
0 | New — a 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 | Activation requested — an 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 service admin. |
6 | Unsubscribed from all newsletters — the address is blocked by the service admin due to recipient's complaints or recipient clicked «Unsubscribe from everything from this sender». |
7 | Activation email sent to the recipient. |
8 | Address blocked by the user. |
9 | Emails can't be sent to this address (this status follows delivery errors). |
10 | Blocked by the list of hosts. |
11 | Blocked by the sender's name. |
12 | Blocked by the address. |
13 | Address deleted by the user. |
14 | Temporarily unavailable. |
Get Total Number of Contacts in a Mailing List
Send a GET request to the URL
https://api.sendpulse.com/addressbooks/{id}/emails/total |
Request parameters:
id | the ID of the mailing list |
Find All Contacts in Mailing List by Value of Variable
Send a GET request to the URL
https://api.sendpulse.com/addressbooks/{id}//variables/{variableName}/{searchValue} |
Request parameters:
id | mailing list ID |
variableName | name of variable |
searchValue | value of variable |
Sample response:
[
{
"email": "a.kozlov@art-industria.ru",
"status": 0,
"status_explain": "New"
},
{
"email": "e.darkling@gmail.com",
"status": 1,
"status_explain": "Active"
}
]
Adding Emails to a Mailing List (with single-opt-in)
To add emails to a mailing list, submit a POST request to:
https://api.sendpulse.com/addressbooks/{id}/emails |
Request parameters:
id | List ID | |
emails | A serialized array of emails (example ["example@gmail.com", "example@outlook.com"] )
if it is necessary to add an email with variables, use this structure: |
|
subscriber's email address | ||
variables (optional) |
a serialized array of variables To add a phone number, use the system variable |
Example of request adding emails without variables:
{
"emails": ["example@gmail.com", "example@outlook.com"]
}
Example of request adding emails with variables:
{
"emails":
[
{
"email": "test@test.com",
"variables": {
"Name": "Elise",
"Phone": "15747072233"
}
},
{
"email": "test2@test.com",
"variables": {
"variable name": "value",
"variable name": "value"
}
}
]
}
If successful, the server will return a response stating "result = true"
Adding Emails to a Mailing List (with double-opt-in)
To use double-opt-in (DOI) activation for recipients, add a new parameter to the request: confirmation=force (optional parameter).
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 in Email-Service settings-From address menu.
Request parameters:
id | list ID | |
emails | a serialized array of email addresses (example ["example@gmail.com", "example@outlook.com"] )
if it is necessary to add an email with variables, use this structure: |
|
subscriber's email address | ||
variables (optional) | a serialized array of variables {"name of variable":"value of variable"} |
|
confirmation | force | |
sender_email | your sender's email | |
template_id | the identifier of a confirmation email is created in the service settings (if the parameter is not specified, a default email will be sent). Example a3e45169-7ae7-4a39-b457-72fd04401f26 | |
message_lang | confirmation email's language. It can take "en", "ru", "ua", "tr", "es", "pr" values |
Example of request for adding emails with variables and DOI principle:
{
"emails":
[
{
"email": "test@test.com",
"variables": {
"Name": "Elise",
"Phone": "15747072233"
}
},
{
"email": "test2@test.com",
"variables": {
"variable name": "value",
"variable name": "value"
}
}
],
"confirmation":"force",
"sender_email":"test2@domain.com"
}
Example of request adding emails DOI principle without variables:
{
"emails":["example@gmail.com", "example@outlook.com"],
"confirmation":"force",
"sender_email":"test2@domain.com"
}
Deleting Email Addresses from a Mailing List
To delete emails from a mailing list, submit a DELETE request to:
https://api.sendpulse.com/addressbooks/{list_id}/emails |
Request parameters:
id | List ID |
emails | A serialized array of emails |
An example of an email address array structure:
[
"test@test.com",
"test2@test.com",
"test3@test.com",
"test4@test.com",
"test5@test.com"
]
If the request was successful, you would receive a JSON response stating "result = true"
Retrieving Information for a Specific Email Address from a Mailing List
Submit a GET request to:
https://api.sendpulse.com/addressbooks/{id}/emails/{email} |
Request parameters:
id | List ID |
Email address information is requested about |
Response parameters:
Email address | |
a list_id | Mailing list ID |
status | Status code |
status_explain | Status explanation |
variables | An array of variables for this email |
Sample response:
{
"email": "test@test.com",
"abook_id": "34",
"status": "1",
"status_explain": "Active",
"variables": [
{
"name": "variable name",
"type": "string",
"value": "value"
},
{
"name": "variable name",
"type": "string",
"value": "value"
},
{
"name": "variable name",
"type": "string",
"value": "value"
}
]
}
Deleting a Mailing List
Submit a DELETE request to:
https://api.sendpulse.com/addressbooks/{id} |
Request parameters:
id | List ID |
If the request was successful, you will receive a JSON response stating "result = true"
Calculating the Cost of a Campaign Sent to a Mailing List
Submit a GET request to:
https://api.sendpulse.com/addressbooks/{id}/cost |
Request parameter:
id | List ID |
Response parameters:
cur | Currency used for calculation |
sent_emails_qty | Total number of email addresses used |
overdraftAllEmailsPrice | Price for exceeding the email address limit |
addressesDeltaFromBalance | Number of email addresses user balance will be charged for |
addressesDeltaFromTariff | Number of email addresses that will be charged by the tariff |
max_emails_per_task | Email address tariff restrictions |
result | Whether there is enough money (true – "enough", false – "not enough") |
A sample response:
{
"cur": "USD",
"sent_emails_qty": 16,
"overdraftAllEmailsPrice": 0,
"addressesDeltaFromBalance": 0,
"addressesDeltaFromTariff": 16,
"max_emails_per_task": "500",
"result": true
}
Campaigns
Creating a Campaign
Submit a POST request to:
https://api.sendpulse.com/campaigns |
Request parameters:
sender_name | Sender's name |
sender_email | Sender's email address |
subject | Email subject |
body | HTML code of the template, encoded in Base64 |
template_id | ID of the template uploaded in the service. Use this method to get the template ID (use either real_id or id parameter from the reply) |
body_amp* | AMP version of the letter, encoded in base64 (additional optional parameter) |
list_id | Mailing list ID |
segment_id | ID of created segment in your account ([Mailing lists] -> select mailing list -> [Segments] > [My segments]-> select segment -> copy segment id from URL in address bar) |
send_test_only | bulk emails in JSON format ["harward@test.com"] if you use this parameter, the campaign will be sent only to those addresses that are specified in this parameter. You can add a maximum of 3 addresses You can send a maximum of 20 such messages per hour |
send_date | 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 |
name | Campaign name (optional parameter) |
type | Possible value - draft [a campaign will be created as a draft] (optional parameter) |
attachments | Attached files, a serialized array in which the key is the name of the attachment, and the value is the content of the attachment (an optional parameter)
content_of_the_attachment/path_to_your_data"} |
Users can create and send a maximum of 4 campaigns per hour.
*Please note: code of AMP body must be valid and can be used only after confirmation from google and mail.ru. You can apply for review here.
A sample response:
{
"id": "27",
"status": "0",
"count": "0",
"tariff_email_qty": "1",
"paid_email_qty": "0",
"overdraft_price": "0",
"ovedraft_currency": "USD"
}
Editing a Scheduled Campaign
Submit a PATCH request to:
https://api.sendpulse.com/campaigns/{id} |
Request parameters:
id | The ID of the created campaign |
name | Campaign name |
sender_name | Sender's name |
sender_email | Sender's email address |
subject | Email subject |
body | HTML code of template, encoded in base64 |
template_id | The ID of the template uploaded in the service. Use this method to get the template ID (use either real_id or id parameter from the reply) |
send_date | 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 |
Retrieving a List of Campaigns
Submit a GET request to:
https://api.sendpulse.com/campaigns |
Request parameters:
limit | Number of entries (optional parameter) |
offset | Offset issue (stating the record to display from) |
When using optional parameters, form a URL of the following format:
https://api.sendpulse.com/campaigns?limit=10&offset=5 |
A sample response:
[
{
"id": "27",
"name": "Test campaign",
"message": {
"sender_name": "John Doe",
"sender_email": "JohnDoe@test.com",
"subject": "My first campaign",
"list_id": "28",
"attachments": "file.zip, file2.zip"
},
"status": "3",
"all_email_qty": 9712,
"tariff_email_qty": "9712",
"paid_email_qty": "0",
"overdraft_price": 0,
"overdraft_currency": "USD"
}
]
Retrieving Information for a Specific Email Address from a Specific Campaign
Submit a GET request to:
https://api.sendpulse.com/campaigns/{id}/email/{email} |
Example: https://api.sendpulse.com/campaigns/3767327/email/john@gmail.com
A sample response:
{
"sent_date": "2017-06-19 15:14:46",
"global_status": 0,
"global_status_explain": "In queue",
"detail_status": 0,
"detail_status_explain": "In queue"
}
Campaign Information
Submit a GET request to:
https://api.sendpulse.com/campaigns/{id} |
Request parameters:
id | Campaign ID |
A sample response:
{
"id": "27",
"name": "Test campaign",
"message": {
"sender_name": "John Doe",
"sender_email": "JohnDoe@test.com",
"subject": "My test campaign>",
"list_id": "28",
"attachments": "file.zip, file2.zip"
},
"status": "3",
"all_email_qty": 25,
"tariff_email_qty": "25",
"paid_email_qty": "0",
"overdraft_price": 0,
"overdraft_currency": "USD",
"statistics": [
{
"code": 0,
"count": 1,
"explain": "In queue"
},
{
"code": 1,
"count": 24,
"explain": "Sent"
},
{
"code": 2,
"count": 22,
"explain": "Delivered"
},
{
"code": 3,
"count": 7,
"explain": "Opened"
},
{
"code": 4,
"count": 1,
"explain": "Link redirected"
},
{
"code": 17,
"count": 1,
"explain": "Temporary blocked"
}
]
}
Possible campaign status:
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 |
Retrieving a List of Campaigns
Submit a GET request to:
https://api.sendpulse.com/campaigns |
Request parameters:
limit | Number of entries (optional parameter) |
offset | Offset issue (stating the record to display from) |
When using optional parameters, form a URL of the following type:
https://api.sendpulse.com/campaigns?limit=10&offset=5 |
A sample response:
[
{
"id": "27",
"name": "test,
"message": {
"sender_name": "John Doe",
"sender_email": "JohnDoe@test.com",
"subject": "my first",
"body": "Hello world",
"list_id": "28",
"attachments": "file.zip, file2.zip"
},
"status": "3",
"all_email_qty": 9712,
"tariff_email_qty": "9712",
"paid_email_qty": "0",
"overdraft_price": 0,
"overdraft_currency": "USD"
}
]
Retrieving a List of Campaigns Created that Use a Specific Mailing List
Submit a GET request to:
https://api.sendpulse.com/addressbooks/{id}/campaigns |
Request parameters:
id | Mailing List ID |
limit | Number of entries (optional parameter) |
offset | Offset issue (stating the record to display from) |
Country Statistics
Submit a GET request to:
https://api.sendpulse.com/campaigns/{id}/countries |
Request parameters:
id | Campaign ID |
Response parameters:
US | Country code |
34567 | Emails opened |
A sample response:
{
"RU": 23,
"US": 34567
}
Referral Statistics
Submit a GET request to:
https://api.sendpulse.com/campaigns/{id}/referrals |
Request parameters:
id | Campaign ID |
Response parameters:
link | The URL from the email |
count | Number of clicks |
A sample response:
[
{
"link": "http://first_link.com"
"count": 123454
},
{
"link": "http://second_link.com"
"count": 5463
}
]
Canceling a Campaign
Submit a DELETE request to:
https://api.sendpulse.com/campaigns/{id} |
Request parameters:
id | Campaign ID |
If the request was successful, you will receive a JSON response stating "result = true"
Templates
Template Creation
Submit a POST request to:
https://api.sendpulse.com/template |
Request parameters:
name | The name of the template (the parameter is optional, if not specified, the name will be displayed as Template YYYY.mm.dd H:i:s) |
body | HTML version of the email, encoded in base64 |
Sample response:
{
"result": true,
"real_id": 1042220
}
real_id
- id of the template can be used in other API functions (for example while creating a campaign)
Editing a Template
Submit a POST request to:
https://api.sendpulse.com/template/edit/{id} |
Request parameters:
id | The ID of the template uploaded in the service. Use this method to get the template ID (use either real_id or id parameter from the reply) |
body | HTML version of the email, encoded in base64 |
lang | language of template, two-character language code |
Get Information About a Template
Submit a GET request to:
https://api.sendpulse.com/template/{template_id} |
Request parameters:
template_id | The ID of the template uploaded in the service. Use this method to get the template ID (use either real_id or id parameter from the reply) |
Retrieving a List of All Templates on an Account
Submit a GET request to:
https://api.sendpulse.com/templates |
A sample 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"
}
]
Retrieving a List of All System Templates
Submit a GET request to:
https://api.sendpulse.com/templates/?owner=sendpulse |
Retrieving a List of All User's Templates
Submit a GET request to:
https://api.sendpulse.com/templates/?owner=me |
Retrieving a List of All User's Templates In a Specific Language (Russian for example)
Submit a GET request to:
https://api.sendpulse.com/templates/ru/?owner=me |
Senders
Retrieving a List of All Senders
Submit a GET request to:
https://api.sendpulse.com/senders |
A sample response:
[
{
"name": "John Doe",
"email": "JohnDoe@test.com",
"status": "Active"
},
{
"name": "John Doe",
"email": "JaneDoe@test.com",
"status": "Active"
}
]
Adding a Sender
Submit a POST request to:
https://api.sendpulse.com/senders |
Request parameters:
Sender’s email address | |
name | Sender’s name |
If the request was successful, you will receive a JSON response stating "result = true"
Deleting a Sender
Submit a DELETE request to:
https://api.sendpulse.com/senders |
Request parameters:
Sender’s email address |
If the request was successful, you will receive a JSON response stating "result = true"
Activating a New Sender
Submit a POST request to:
https://api.sendpulse.com/senders/{email}/code |
Request parameters:
code | Activation code |
A sample response (if successful):
{
"result": true,
"email": JohnDoe@test.com
}
Receiving an Activation Code to the Sender’s Email Address
Submit a GET request to:
https://api.sendpulse.com/senders/{email}/code |
A sample response:
{
"result": true,
"email": JohnDoe@test.com
}
If the request was successful, the sender will receive an email with the activation code.
Email Address
Retrieve General Information About a Specific Email Address
Submit a GET request to:
https://api.sendpulse.com/emails/{email} |
A sample response:
VALID JSON (RFC 4627)
Formatted JSON Data
[
{
"book_id":"39359",
"email":"test@test.com",
"status":"3",
"variables":[
{
"name":"variable name",
"type":"string",
"value":"variable value"
},
{
"name":"variable name",
"type":"string",
"value":"variable value"
},
{
"name":"variable name",
"type":"string",
"value":"variable value"
}
]
},
{
"book_id":"39362",
"email":"test@test.com",
"status":"3",
"variables":[
{
"name":"variable name",
"type":"string",
"value":"variable value"
}
]
}
]
Retrieve Detailed Information About a Specific Email Address
Submit a GET request to:
https://api.sendpulse.com/emails/{email}/details |
Sample 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"
}
]
Retrieve General Informaion for a List of Email Addresses
Submit a POST request to:
https://api.sendpulse.com/emails |
Request parameters:
emails | array of email adresses |
Deleting an Email Address From All Mailing Lists
Submit a DELETE request to:
https://api.sendpulse.com/emails/{email} |
If the request was successful, you will receive a JSON response stating "result = true"
Retrieving Statistics for an Email Address and Campaigns It Is In
Submit a GET request to:
https://api.sendpulse.com/emails/{email}/campaigns |
Sample response:
{
"statistic": {
"sent": 0,
"open": 0,
"link": 0
},
"blacklist": false
}
Retrieving Statistics for Multiple Email Addresses and Campaigns They are In
Submit a POST request to:
https://api.sendpulse.com/emails/campaigns |
Request parameters:
emails | array of contacts ["example@yourdomain.com", "example2@yourdomain.com"] |
A sample 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
}
}
Changing 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:
addressBookId | Mailing list ID containing the necessary email contact with the variable with “name” value |
email contact, that will have the variable with “name” value changed to “John” | |
variables | array with variables, which is defined by the parameters name (variable name) and value (variable value) |
*Note: You can change only one email per request
String variables accept either numeric values or values expressing the date in the following format: YYYY-MM-DD.
"Number" variable accepts only numbers, and the “Date” variable 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.
Sample request parameters:
{
"email":"myemail@example.com",
"variables":[
{
"name":"name",
"value":"John"
},
{
"name":"number",
"value":1
},
{
"name":"date",
"value":"2019-02-01"
},
{
"name":"asdasd",
"value":"asdasd"
}
]
}
Blacklist
Viewing the Blacklist
Submit a GET request to:
https://api.sendpulse.com/blacklist |
A sample response:
[
"JohnDoe@test.com",
"JaneDoe@test.com",
]
Blacklisting an Email Address
Submit a POST request to:
https://api.sendpulse.com/blacklist |
Request parameters:
emails | A string containing email addresses separated by commas encoded in Base64 |
comment | A comment, string format (optional parameter) |
If the request was successful, you will receive a JSON response stating "result = true"
Unsubscribe a Contact From a Defined Mailing List
Submit a POST request to:
https://api.sendpulse.com/addressbooks/{id}/emails/unsubscribe |
Request parameters:
id | the mailing list ID |
emails | the contact that you want to unsubscribe from the defined mailing list ["example@yourdomain.com"] |
Deleting an Email Address From the Blacklist
Submit a DELETE request to:
https://api.sendpulse.com/blacklist |
Request parameters:
emails | A string containing email addresses separated by commas encoded in base64 |
If the request was successful, you will receive a JSON response stating "result = true"
Balance
Checking Your Balance
Submit 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 |
A sample response:
{
"currency": "USD",
"balance_currency": 0.02
}
Detailed Balance Information
Submit a GET request to:
https://api.sendpulse.com/user/balance/detail |
A sample 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
Summary
A webhook is a mechanism for receiving notifications about certain events. You can set up notifications about email deliverability and subscriber activity.
To create and send webhooks automatically, go to the "Account Settings" section in the "API" tab and click "Create a webhook."
Select the event triggered by the webhook in the email service regarding sending an email:
- email marked as spam;
- email opened;
- link in the email clicked;
- new subscriber;
- subscriber unsubscribed;
- subscriber deleted from the list;
- campaign status changed.
Next, specify the URL, to which notifications will be sent.
For each event you should create separate webhooks.
When a webhook is triggered, SendPulse sends a POST request to the specified URL with
the JSON data type.
Data is sent every minute or when the limit of 1000 events is reached.
The primary data format for a request:
[
{
"event": "event_name",
"timestamp": 1490954061,
"recipient": "john.doe@sendpulse.com",
"sender": "doe.john@sendpulse.com",
"subject": "hello world"
}
]
Examples of requests for each event
Marked as spam:
[
{
"timestamp": 1496827422,
"event": "spam",
"task_id": 3668141,
"email": "john.doe@sendpulse.com"
}
]
Email opened:
[
{
"task_id": 3668141,
"timestamp": "1496827941",
"open_device": "Desktop",
"open_platform": "Windows",
"browser_ver": "11.0",
"browser_name": "Firefox",
"email": "john.doe@sendpulse.com",
"event": "open"
}
]
Link clicked:
[
{
"link_url": http://google.com,
"task_id": 3668141,
"timestamp": "1496828000",
"open_device": "Desktop",
"open_platform": "Linux",
"browser_ver": "58.0.3029.110",
"browser_name": "Chrome",
"link_id": 71741389,
"email": "john.doe@sendpulse.com",
"event": "redirect"
}
]
Client opted-out:
[
{
"task_id": "3668141",
"timestamp": "1496827872",
"from_all": 1,
"email": "john.doe@sendpulse.com",
"reason": null,
"book_id": 490686,
"event": "unsubscribe",
"categories": ""
}
]
New subscriber:
[
{
"timestamp": "1496827625",
"variables": [],
"email": "john.doe@sendpulse.com",
"source": "address book",
"book_id": "490686",
"event": "new_emails"
},
{
"timestamp": "1496827625",
"variables": [],
"email": "doe.john@sendpulse.com",
"source": "subscription form",
"book_id": "490686",
"event": "new_emails"
}
]
Removing from an email list:
[
{
"timestamp": 1496827422,
"event": "delete",
"book_id": "490686",
"email": "john.doe@sendpulse.com"
}
]
Changing email campaign status:
[
{
"status": "approve",
"status_explain": "Approved and will be sent",
"task_id": 3668138,
"timestamp": 1496827843,
"book_id": "490686",
"event": "task_status_update"
},
{
"status": "approve_part",
"status_explain": "Approved and will be sent by parts",
"task_id": 3668139,
"timestamp": 1496827843,
"book_id": "490686",
"event": "task_status_update"
},
{
"status": "only_active",
"status_explain": "Will be sent only to active adresses",
"task_id": 3668140,
"timestamp": 1496827843,
"book_id": "490686",
"event": "task_status_update"
},
{
"status": "confirm_addresses",
"status_explain": "Rejected: confirm the mailing list",
"task_id": 3668142,
"timestamp": 1496827843,
"book_id": "490686",
"event": "task_status_update"
},
{
"status": "need_edit",
"status_explain": "Rejected: edit the email body",
"task_id": 3668143,
"timestamp": 1496827843,
"book_id": "490686",
"event": "task_status_update"
},
{
"status": "rejected",
"status_explain": "Campaign rejected",
"task_id": 3668144,
"timestamp": 1496827843,
"book_id": "490686",
"event": "task_status_update"
},
{
"status": "on_moderation",
"status_explain": "Campaign is on moderation",
"task_id": 3668145,
"timestamp": 1496827843,
"book_id": "490686",
"event": "task_status_update"
},
{
"status": "sending",
"status_explain": "Campaign is in the sending queue",
"task_id": 3668146,
"timestamp": 1496827843,
"book_id": "490686",
"event": "task_status_update"
},
]
Example of the script that processes a webhook in PHP:
<?php
$json_string = file_get_contents('php://input');
$data_array = json_decode($json_string, true);
?>
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 the request is successful, the server will return a response:
{
"success": true,
"data": [
{
"id": 162242,
"user_id": 7043663,
"url": "https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68",
"action": "unsubscribe"
},
{
"id": 162241,
"user_id": 7043663,
"url": "https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68",
"action": "open"
}
]
}
Get a webhook by ID
To receive a webhook by ID, send a GET request to:
https://api.sendpulse.com/v2/email-service/webhook/{id} |
Request parameters:
id | webhook identifier |
If the request is successful, the server will return a response:
{
"success": true,
"data": {
"id": 162242,
"user_id": 7043663,
"url": "https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68",
"action": "unsubscribe"
}
}
Create webhook
To create a webhook, send a POST request to:
https://api.sendpulse.com/v2/email-service/webhook/ |
Request parameters:
actions | tracked events, example["open","unsubscribe"] |
url | link to the handler, example https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68 |
Possible values for actions:
new_email | adding a new email address |
delete | email address deleted from the mailing list |
unsubscribe | user unsubscribed |
task_status_update | campaign status changed |
open | campaing was opened |
redirect | following link |
spam | user marked as spam |
The data is sent with the x-www-form-urlencoded type.
If the request is successful, the server will return a response:
{
"success": true,
"data": [
{
"user_id": 7043663,
"url": "https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68",
"id": 162241,
"action": "open"
},
{
"user_id": 7043663,
"url": "https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68",
"id": 162242,
"action": "unsubscribe"
}
]
}
Delete webhook
To delete a webhook, send a DELETE request to:
https://api.sendpulse.com/v2/email-service/webhook/{id} |
Request parameters:
id | webhook identifier |
If the request is successful, the server will return a response:
{
"success": true,
"data": [
true
]
}
Update 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:
id | webhook identifier |
url | link to the handler, example https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68 |
If the request is successful, the server will return a response:
{
"success": true,
"data": [
true
]
}
Şununla kaydol
Facebook ile giriş yapın Google ile giriş yapın