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 The mailing list name

Request example:

{
   "bookName": "My New Book"
}

If request is successful, you will receive a response:

{
   "id":422325 
}

Response parameter:

Parameter Type Description
id int The 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 The mailing list ID
name string The new name of the mailing list

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 (optional):

Parameter Type Description
limit int A number of records
offset int An 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

If request is successful, you will receive a responce:

[
   {
      "id":1,
      "name":"My first book",
      "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 book",
      "all_email_qty":6,
      "active_email_qty":0,
      "inactive_email_qty":6,
      "creationdate":"2015-04-20 09:02:39",
      "status":0,
      "status_explain":"Active"
   }
]

Response parameters:

Parameter Type Description
id int The mailing list ID
name string The mailing list name
all_email_qty int A total number of emails
active_email_qty int A number of active emails
inactive_email_qty int A number of inactive emails
creationdate string A date of mailing list creation
status int A status code
status_explain string A status explanation

Possible mailing list status:

Status code Status description
0 An active mailing list
1 A mailing list marked as «deleted»
3 An awaiting user's reply to the moderator's clarification question
4 A mailing list blocked by the service 
5 A 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 The mailing list ID

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,
      "creationdate":"2015-04-20 08:52:40",
      "status":0,
      "status_explain":"Active"
   }
]

Response parameters:

Parameter Type Description
id int The mailing list ID
name string The mailing list name
all_email_qty int A total number of emails
active_email_qty int A number of active emails
inactive_email_qty int A number of inactive emails
creationdate string A date of creation
status int A status code
status_explain string A 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 The mailing list ID

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 A variable name
type string A 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 The mailing list ID
limit int A number of records, optional
offset  int An offset (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

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
email string An email address
status int An email address status
phone string A phone number
status_explain string A status description
variables array An array of variables, for example, {"variable_name": "variable_value"}

Possible email address status:

Status code Status name 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 Confirmation 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 A recipient unsubscribed from emails sent by this sender
5 Rejected by the admin Rejected by the service admin
6 Unsubscribed from all newsletters An email address is blocked by the service admin due to recipient's complaints or recipient clicked «Unsubscribe from everything from this sender»
7 Activation is requested An activation email sent to the recipient
8 Blocked An 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 An email address is blocked by the list of hosts
11 Blocked An email address is blocked by the sender's name
12 Blocked An email address is blocked by the part of the address
13 Deleted by the user An email address deleted by the user
14 Temporarily unavailable An 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 The mailing list ID

If request is successful, you will receive a response:

{
   "total": 1
}

Response parameters:

Parameter Type Description
total int A 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 The mailing list ID
variableName string A variable name
searchValue string A variable value

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
email string An email address
status int An email address status code
status_explain string An 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 The mailing list ID
emails array A 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:

email string A subscriber's email address
variables (optional) array

A serialized array of variables, for example, {"name of variable":"value of variable"};

to add a phone number, use the system variable Phone

Request example:

{
   "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 The mailing list ID
emails array A 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:

email string A subscriber's email address
variables (optional) array A serialized array of variables, for example, {"name of variable":"value of variable"}
confirmation string force
sender_email string A sender's email address
template_id string The confirmation email ID (optional); 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
message_lang string A confirmation email's language. It can take "en", "ru", "ua", "tr", "es", "pt" values

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
}
 

Delete Emails from a Mailing List

To delete emails from a mailing list, send a DELETE request to:

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

Request parameters:

Parameter Type Description
id int The mailing list ID
emails array A serialized array of emails

Request example:

{
   "emails": ["test1@test.com", "test2@test.com", "test3@test.com"]
}

If request is successful, you will receive a response:

{
   "result": true
}
 

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 The mailing list ID
email string The email address

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
email string The email address
abook_id string The mailing list ID
phone string A phone number
status int An email address status code
status_explain string An email address status description
variables array An array of variables for this email (equals [] if the contact has no variables, or the variable is empty):
name string A variable name
type string A variable type
value string A variable value
 

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 The mailing list ID

If request is successful, you will receive a response:

{
   "result": true
}
 

Calculate 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 The mailing list ID

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 A currency used for calculation
sent_emails_qty int A total number of email addresses
overdraftAllEmailsPrice int A price for exceeding the email address limit
addressesDeltaFromBalance int A number of email addresses user balance will be charged for
addressesDeltaFromTariff int A number of email addresses that will be charged by the tariff
max_emails_per_task int An email address tariff restrictions
result boolean Determines whether there is enough money (true or false)
 

Campaigns

 

Create a Campaign

To create a 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 A sender's name
sender_email string A sender's email address
subject string An email subject
body1 string An HTML code of the template, encoded in Base64
template_id1 int An ID of the template 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)
list_id2 int A mailing list ID
segment_id2 int An 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)
is_test boolean Is used to send a test email to the sender's address specified in the sender_email parameter (optional parameter)
send_date string A 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 parameter)
name string A campaign name (optional parameter)
attachments string 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"} (an optional parameter)
attachments_binary string 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"} (an optional parameter)
type string A possible value - draft [a campaign will be created as a draft] (optional parameter)
body_amp3 string An AMP version of the email, encoded in base64 (optional parameter)

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:

{
    "sender_name":"my_sender_name",
    "sender_email":"my_sender@test.com",
    "subject":"hello customer",
    "list_id":"756589",
    "name":"my_api_campaign",
    "body": "bXkgYXBpIGJvZHk=",
    "send_date":"2016-02-02 23:34:23"
}

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

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 The campaign ID
status int A task status for sending (13 - copying addresses for sending, 26 - draft)
count int A number of recipients to which the campaign is sent
tariff_email_qty int A number of emails written off from the user's balance
overdraft_price string Price for one email at an increase
ovedraft_currency string A currency
 

Edit Planned Campaign

To edit planned campaign, send a PATCH request to:

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

Request parameters:

Parameter Type Description
id int The ID of the created campaign
name string A campaign name
sender_name string A sender's name
sender_email string A sender's email address
subject string An email subject
body string HTML code of template, encoded in base64
template_id int/string The ID of the template 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)
send_date string A 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
 

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 The campaign ID

If request is successful, you will receive a 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 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 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 The email campaign ID
email string The email address

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 A date of sending the email campaign
global_status int A global email campaign status code
global_status_explain string A global status description
detail_status int A detailed email campaign status code
detail_status_explain string A detailed status description
 

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 A number of records, optional
offset int An offset (first record to display), optional

When using optional parameters limit and offset, form a URL of the following type:

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

If request is successful, you will receive a 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"
  }
]

Response parameters:

Parameter Type Description
id int The campaign ID
name string The campaign name
sender_name string The sender name
sender_email string Rhe sender email address
subject string A subject of an email
body string A body of an email
list_id int The mailing list ID
attachments string Attachments
status int An email campaign status code
all_email_qty int A total number of email addresses
tariff_email_qty int A number of emails written off the user's balance
paid_email_qty int A number of email addresses paid from the balance above the tariff limit
overdraft_price int Price per letter if exceeded
overdraft_currency string Currency
 

Get 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 The mailing List ID
limit A number of entries (optional parameter)
offset Offset issue (stating the record to display from)
 

Get a Country Statistics

Submit a GET request to:

https://api.sendpulse.com/campaigns/{id}/countries

Request parameters:

id The campaign ID

Response parameters:

US A country code
34567 Emails opened

A sample response:

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

Get a 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 A cumber of clicks

A sample response:

[
  {
    "link": "http://first_link.com"
    "count": 123454
  },
  {
    "link": "http://second_link.com"
    "count": 5463
  }
]
 

Cancel a Campaign

Submit a DELETE request to:

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

Request parameters:

id The campaign ID

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

 

Templates

 

Create a Template

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

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

Get a list of all system templates

Submit a GET request to:

https://api.sendpulse.com/templates/?owner=sendpulse
 

Get a list of all user templates

Submit a GET request to:

https://api.sendpulse.com/templates/?owner=me
 

Get a template by name

Submit a GET request to:

https://api.sendpulse.com/templates//template/slug/{name_slug}

Request parameter:

name_slug the system name of the template, you can find it in the api response for creating or searching for templates by other parameters.
 

Get a list of all templates in a specific language

Submit a GET request to:

https://api.sendpulse.com/templates/ru/?owner=me
 

Senders

 

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

Add a Sender

Submit a POST request to:

https://api.sendpulse.com/senders

Request parameters:

email A sender’s email address
name A sender’s name

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

 

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

 

Activate a New Sender

Submit a POST request to:

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

Request parameters:

code An activation code

A sample response (if successful):

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

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

Get 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 An 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 The Mailing list ID containing the necessary email contact with the variable with “name” value
email An email contact, that will have the variable with “name” value changed to “John”
variables An 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

 

View the Blacklist

Submit a GET request to:

https://api.sendpulse.com/blacklist

A sample response:

[
  "JohnDoe@test.com",
  "JaneDoe@test.com",
]

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

Delete 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

 

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

Get a 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 The webhook ID

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_emails 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 The webhook ID

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 The webhook ID
url The URL 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
    ]
}