Mailing lists

With the API you can create mailing lists, edit them, delete them, as well as perform other operations with the available mailing lists.

 

Creating a mailing list

To create a mailing list, a POST request is sent to:

https://api.sendpulse.com/addressbooks

 Request parameter:

bookName list name

If successful, the server returns a response with the ID value of the mailing list created.

 

Editing a mailing list

To edit the mailing list, a PUT request is sent to:

https://api.sendpulse.com/addressbooks/{id}

Request parameters:

id the ID of the mailing list
name the new name of the list

If successful, the server returns a response stating result = true

 

Retrieving a list of mailing lists

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, the URL formed is of the following format:

https://api.sendpulse.com/addressbooks?limit=10&offset=5

Response parameters:

id List ID
name/td> 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

A sample response when retrieving the 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"
  }
    ]
 

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}

Request Parameters:

id List ID
name/td> 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

A sample response when 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"
  },
    ]
 

Retrieving a list of emails from a mailing list

To retrieve a list of email addresses from a particular mailing list, submit a GET request to:

https://api.sendpulse.com/addressbooks/{id}/emails

Request parameters:

id List ID
limit (optional) Number of entries
offset (optional) offset (stating the first record to display)

When using optional parameters, the URL formed is of the following format:

https://api.sendpulse.com/addressbooks/{id}/emails?limit=10&offset=5

Response parameters:

email Email address
status Status code
status_explain Status explanation
variables An array of variables for this address

A sample response when retrieving the list of mailing lists:

[
  {
    "email": "test@test.com",
    "status": "0",
    "status_explain": "New",
    "variables": [
      {
	"name": "variable name",
	"type": "string",
	"value": "variable value"
      },
      {
	"name": "variable name",
	"type": "string",
	"value": "variable value"
      }
    ]
  },
  {
    "email": "test2@test.com",
    "status": "0",
    "status_explain": "New",
    "variables": [
      {
	"name": "variable name",
	"type": "string",
	"value": "variable value"
      },
      {
	"name": "variable name",
	"type": "string",
	"value": "variable value"
      }
    ]
  }
    ]
 

Adding emails to a mailing list

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

An example of an email address array structure

[
  {
    "email": "test@test.com",
    "variables": {
      "variable name": "value",
      "variable name": "value"
    }
  },
  {
    "email": "test2@test.com",
    "variables": {
      "variable name": "value",
      "variable name": "value"
    }
  }
]

If successful, the server will return a response stating result = true

To add a phone number, use the system variable "Phone"

 

Deleting emails 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 will receive a JSON response stating result = true

 

Retrieving information for 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 Email address information is desired on

Response parameters:

email Email address
a list_id Mailing list ID
status Status code
status_explain Status explanation
variables An array of variables for this email

A 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"
    }
  ]
    }
 

Erasing 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 carried out by 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 The price for exceeding the email address limit
addressesDeltaFromBalance The number of email addresses that will be charged from the balance
addressesDeltaFromTariff The 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

 

Template creation

Submit a POST request to:

https://api.sendpulse.com//template

Request parameters:

name The name of the template (optional parameter, in case of its absence, the name will be displayed as Template YYYY.mm.dd H:i:s)
body Coded base64 encoding

A sample response:

 {
"result": true
    }
 

Creating a campaign

Submit a POST request to:

https://api.sendpulse.com/campaigns

Request parameters:

sender_name Sender name
sender_email Sender email address
subject Email subject
body The email body, encoded in base64
list_id Mailing list ID
send_date Date of the scheduled email campaign (optional parameter). It must be in such format: Y-m-d H:i:s (for example: 2016-02-02 23:34:23) and can not be less than the current date
name Campaign name (an optional parameter)
type Possible value - "draft" (a newsletter will be created as a draft). An 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)

A sample response:

{
  "id": "27",
  "status": "0",
  "count": "0",
  "tariff_email_qty": "1",
  "paid_email_qty": "0",
  "overdraft_price": "0",
  "ovedraft_currency": "USD"
    }
 

 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 first campaign",
    "body": "<p>\ \Hi World!<\/p>",
    "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 the 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, the URL formed is 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",
      "body": "<p>\ \Hi World!<\/p>",
      "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"
		}
	  ]
}
 

Retrieving information for 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"
}
 

Country statistics

Submit a GET request to:

https://api.sendpulse.com/campaigns

Request parameters:

id Campaign ID

Response parameters:

US Country code
34567 Emails opened

A sample response:

{
  "RU": 23,
  "US": 34567
    } 
 

Referrals 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
  }
    ] 
 

Cancelling 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

 

Senders

 

Retrieving a list of all of the 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:

email 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:

email Sender’s email address

If the request was successful, you will receive a JSON response stating result = true

 

Activating a sender

Submit a POST request to:

https://api.sendpulse.com/senders/{email}/code

Request parameters:

code Activation code

 

A sample response (if succeed):

 

{
  "result": true,
  "email": JohnDoe@test.com
    }
 

Receiving the activation code at 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 containing the activation code.

 

Email Address

 

Retrieve general information for a specific email address

Submit a GET request to:

https://api.sendpulse.com/emails/{email}

 

A sample response:

 

[
  {
    "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"
      }
    ]
  }
    ]
 

Erasing 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 by campaigns

Submit a GET request to:

https://api.sendpulse.com/emails/{email}/campaigns

 

A sample response:

 

{
  "statistic": {
    "sent": 0,
    "open": 0,
    "link": 0
  },
  "blacklist": false
}
 

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 encoded in base64 (an optional parameter)

 

An example of a string containing email addresses separated by commas:

user1@mailserver.com,user2@mailserver.com,user3@mailserver.com

If the request was successful, you will receive a JSON response stating result = true

 

Erasing an email address from the blacklist

Submit a DELETE request to:

https://api.sendpulse.com/blacklist

Request parameters:

email A string containing email addresses separated by commas

 

An example of a string containing email addresses separated by commas:

user1@mailserver.com,user2@mailserver.com,user3@mailserver.com

If the request was successful, you will receive a JSON response stating result = true

 

Balance

 

Checking the user’s balance

Submit a GET request to:

https://api.sendpulse.com/balance

An optional request parameter: the currency value

When using optional parameter, the URL formed is of the following format:

https://api.sendpulse.com/balance/USD

 

A sample response:

 

{
  "currency": "USD",
  "balance_currency": 0.02
    }
 

WebHooks

WebHooks is a way for for receiving notifications about certain events. To add a webhook please go to "Account settings" → "API".

Enter the URL where the notifications will be sent to and specify the events for them.

The list of events that can be selected for webhook about email sent via email service:

  • Get marked as spam
  • Email open rate
  • Email click-through rate
  • New subscriber
  • Removing from an email list
  • A subscriber decided to opt out
  • A mailing status changing

When webhook is triggered we send data to the URL configured by you:

  • Data type: JSON
  • Request type: POST

The data is sent every minute or when the number of events reaches 100 events.

The main data format for a request:

[
  {
    "event": "event_name",
    "timestamp": 1490954061,
    "recipient": "john.doe@sendpulse.com",
    "sender": "doe.john@sendpulse.com",
    "subject": "hello world" 
  }
]

In case when there are several events, they will be grouped in one or several requests

[
  {
    "timestamp": 1496827422,
    "event": "delete",
    "book_id": "490686",
    "email": "john.doe@sendpulse.com" 
  },
  {
    "timestamp": 1496827422,
    "event": "delete",
    "book_id": "490686",
    "email": "doe.john@sendpulse.com" 
  },
  {
    "timestamp": "1496827625",
    "variables": [],
    "email": "john.doe@sendpulse.com",
    "source": "address book",
    "book_id": "490686",
    "event": "new_emails" 
  }
]

Examples of requests for each event:

Get marked as spam

[
  {
    "timestamp": 1496827422,
    "event": "spam",
    "task_id": 3668141,
    "email": "john.doe@sendpulse.com" 
  }
]

Email open rate

[
  {
    "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" 
  }
]

Email click-through rate

 [
  {
    "event": "opened",
    "timestamp": 1490962764,
    "recipient": "doe.john@sendpulse.com",
    "sender": "john.doe@sendpulse.com",
    "subject": "utf8_hello_world" 
  }
]

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" 
  }
]

Изменение статуса рассылки

[
  {
    "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 part",
    "task_id": 3668139,
    "timestamp": 1496827843,
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "only_active",
    "status_explain": "Will be sent only on active adresses",
    "task_id": 3668140,
    "timestamp": 1496827843,
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "confirm_addresses",
    "status_explain": "Rejected: you need to confirm your mailing list",
    "task_id": 3668142,
    "timestamp": 1496827843,
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "need_edit",
    "status_explain": "Rejected: You need to edit your mail body",
    "task_id": 3668143,
    "timestamp": 1496827843,
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "rejected",
    "status_explain": "Campaign was rejected",
    "task_id": 3668144,
    "timestamp": 1496827843,
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "on_moderation",
    "status_explain": "Your campaign on moderation",
    "task_id": 3668145,
    "timestamp": 1496827843,
    "book_id": "490686",
    "event": "task_status_update" 
  },
  {
    "status": "sending",
    "status_explain": "Your campaign in sending queue",
    "task_id": 3668146,
    "timestamp": 1496827843,
    "book_id": "490686",
    "event": "task_status_update" 
  },
]

An example of script that processes a webhook in PHP

<?php
$json_string = file_get_contents('php://input');
$data_array = json_decode($json_string, true);
?>