1. Anasayfa
  2. Entegrasyonlar
  3. API
  4. API Email Service
 

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"

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, 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

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, form a URL of the following type:

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

Sample response to retrieving a 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"
      }
    ]
  }
    ]

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:
email subscriber's email address
variables (optional)

a serialized array of variables {"name of variable":"value of variable"}

To add a phone number, use the system variable Phone

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

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"
    }
  }
],
"confrimation":"force",
"sender_email":"test2@domain.com"
}

Example of request adding emails DOI principle without variables:

{
"emails":["example@gmail.com", "example@outlook.com"],
"confrimation":"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 Email address information is requested about

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

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)
{"name":"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

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",
      "body": "<p>\ \	Hello 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 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:

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

WebHook is a mechanism for receiving notifications about events. To add a webhook, go to "Account settings" → "API."

Specify a URL to send notifications to and select events you would like to be notified about.

List of events the webhook can notify you about with our email service:

  • Marked as spam
  • Email opened
  • Click-through
  • New subscriber
  • Email address deleted from the mailing list
  • Subscriber opted-out
  • Campaign status changed

When a webhook is triggered, data is sent to the specified URL:

  • Data type: JSON
  • Request type: POST

The data is sent every minute or when the event count reaches 100.

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

In a 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

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);
?>