Bulk Email Service API

Mailing lists

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

Create a mailing list

To create a mailing list, send a POST request to:

https://api.sendpulse.com/addressbooks

Request parameter:

Parameter Type Description  
bookName string Mailing list name required

Request example:

{
   "bookName": "My New Book"
}

If request is successful, you will receive a response:

{
   "id":422325 
}

Response parameter:

Parameter Type Description
id int Mailing list ID

Edit a mailing list

To edit a mailing list, send a PUT request to:

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

Request parameters:

Parameter Type Description  
id int Mailing list ID required
name string Mailing list new name required

Request example:

{
   "name": "New Name"
}

If request is successful, you will receive a response:

{
   "result": true
}

Get a list of mailing lists

To get a list of all of the mailing lists that have been created, send a GET request to:

https://api.sendpulse.com/addressbooks

Request parameters:

Parameter Type Description  
limit int Number of records optional
offset int Offset (first record to be displayed) optional

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

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

If request is successful, you will receive a response:

[
   {
      "id":1,
      "name":"My first book",
      "all_email_qty":1,
      "active_email_qty":0,
      "inactive_email_qty":1,
      "new_phones_quantity": 0,
      "active_phones_quantity": 0,
      "exc_phones_quantity": 0,
      "creationdate":"2015-04-20 08:52:40",
      "status":0,
      "status_explain":"Active"
   },
   {
      "id":2,
      "name":"My second book",
      "all_email_qty":6,
      "active_email_qty":0,
      "inactive_email_qty":6,
      "new_phones_quantity": 0,
      "active_phones_quantity": 0,
      "exc_phones_quantity": 0,
      "creationdate":"2015-04-20 09:02:39",
      "status":0,
      "status_explain":"Active"
   }
]

Response parameters:

Parameter Type Description
id int Mailing list ID
name string Mailing list name
all_email_qty int Total number of emails
active_email_qty int Number of active emails
inactive_email_qty int Number of inactive emails
new_phones_quantity int Number of new phone numbers
active_phones_quantity int Number of active phone numbers
exc_phones_quantity int Number of inactive phone numbers
creationdate string Date of mailing list creation
status int Status code
status_explain string Status explanation

Possible mailing list status:

Status code Status description
0 Active mailing list
1 Mailing list marked as "deleted"
3 Awaiting user's reply to the moderator's clarification question
4 Mailing list blocked by the service 
5 Mailing list blocked by the daemon to transfer email addresses into a campaign; once unblocked, the status will change to 0

Get mailing list information

To get detailed information regarding a specific mailing list, send a GET request to:

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

Request parameter:

Parameter Type Description  
id int Mailing list ID required

If request is successful, you will receive a response:

[
   {
      "id":1,
      "name":"My first book",
      "all_email_qty":1,
      "active_email_qty":0,
      "inactive_email_qty":1,
      "active_phones_quantity": 0,
      "exc_phones_quantity": 0,
      "creationdate":"2015-04-20 08:52:40",
      "status":0,
      "status_explain":"Active"
   }
]

Response parameters:

Parameter Type Description
id int Mailing list ID
name string Mailing list name
all_email_qty int Total number of emails
active_email_qty int Number of active emails
inactive_email_qty int Number of inactive emails
active_phones_quantity int Number of active phone numbers
exc_phones_quantity int Number of inactive phone numbers
creationdate string Date of creation
status int Status code
status_explain string Status explanation

Get a list of variables for a mailing list

To get a list of variables available on a mailing list, send a GET request to:

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

Request parameter:

Parameter Type Description  
id int Mailing list ID required

If request is successful, you will receive a response:

[
    {
        "name": "email",
        "type": "string"
    },
    {
        "name": "name",
        "type": "string"
    },
    {
        "name": "date",
        "type": "date"
    },
    {
        "name": "code",
        "type": "number"
    }
]

Response parameters:

Parameter Type Description
name string Variable name
type string Variable type

Get a list of emails from a mailing list

To get a list of emails from a mailing list, send a GET request to:

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

Request parameters:

Parameter Type Description  
id int Mailing list ID required
limit int Number of records optional
offset  int Offset (first record to display) optional
active boolean Use this parameter to get a list of contacts with Active and New statuses optional
not_active boolean Use this parameter to get a list of inactive contacts. Learn more Email statuses and their description. optional

The method returns up to 100 records, use the limit and offset parameters to offset the results.

When using optional parameters, enter your URL in the following format:

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

If request is successful, you will receive a response:

[ 
   { 
      "email":"test@test.com",
      "status": 0,
      "status_explain":"New",
      "variables":{ 
         "name":"John",
         "country":"UK"
      }
   },
   { 
      "email":"test2@test.com",
      "status": 0,
      "status_explain":"New",
      "variables":{ 
         "name":"Michael",
         "country":"UK"
      }
   }
]

Response parameters:

Parameter Type Description
email string Email address
status int Email address status
phone string Phone number
status_explain string Status description
variables array List of variables, for example, {"variable_name": "variable_value"}

Possible email address status:

Status code Status name Status description
0 New Newly added address; delivery to this address is blocked until the service admin activates it
1 Active Delivery to this address is allowed; if the address hasn't been activated, delivery is blocked
2 Confirmation requested Email has been sent to the address holder to confirm the subscription
3 Activation requested Pending activation by the admin of the service
4 Unsubscribed Recipient unsubscribed from emails sent by this sender
5 Rejected by the admin Rejected by the service admin
6 Unsubscribed from all newsletters Email address is blocked by the service admin due to recipient's complaints or recipient clicked Unsubscribe from everything from this sender
7 Activation is requested Activation email sent to the recipient
8 Blocked Email address is blocked by the user
9 Sending error Emails can't be sent to this address (this status follows delivery errors)
10 Blocked Email address is blocked by the list of hosts
11 Blocked Email address is blocked by the sender's name
12 Blocked Email address is blocked by the part of the address
13 Deleted by the user Email address deleted by the user
14 Temporarily unavailable Email address is temporarily unavailable

Get the total number of contacts in a mailing list

To get the total number of contacts in a mailing list, send a GET request to:

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

Request parameter:

Parameter Type Description  
id int Mailing list ID required

If request is successful, you will receive a response:

{
   "total": 1
}

Response parameters:

Parameter Type Description
total int Total number of email addresses in the mailing list

Get all of the contacts in a mailing list by variable

To find all of the contacts in a mailing list by variable, send a GET request to:

https://api.sendpulse.com/addressbooks/{id}//variables/{variableName}/{searchValue}

Request parameters:

Parameter Type Description  
id int Mailing list ID required
variableName string Variable name required
searchValue string Variable value required

If request is successful, you will receive a response:

[
    {
        "email": "a.kozlov@art-industria.ru",
        "status": 0,
        "status_explain": "New"
    },
    {
        "email": "darkling@gmail.com",
        "status": 1,
        "status_explain": "Active"
    }
]

Response parameters:

Parameter Type Description
email string Email address
status int Email address status code
status_explain string Email address status description

Add emails to a mailing list (single-opt-in)

To add emails to a mailing list, send a POST request to:

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

Request parameters:

Parameters Type Description  
id int Mailing list ID required
emails array Serialized array of emails, for example ["example@gmail.com", "example@outlook.com"]).

If it is necessary to add an email with variables, use this structure:

 required
email string Subscriber's email address required
variables array

Serialized array of variables, for example, {"name of variable":"value of variable"}. The variable name must be a string or contain at least one string character.

You can use the following characters in the variable name: all Unicode alphabetic characters (regex meta group);
all numeric characters (regex meta group); dots, commas, question marks, and exclamation points; single and double quotes; hyphens and underscores; right slash; space.

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

required

Request example without variables:

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

Request example with variables:

When you add a contact with variables, the email should only be under the corresponding key, as in the example below.

{
   "emails":[
      {
         "email":"test@test.com",
         "variables":{
            "name":"Elizabeth",
            "Phone":"380632727700"
         }
      },
      {
         "email":"test2@test.com"         
      }
   ]
}

If request is successful, you will receive a response:

{
   "result": true
}

Add emails to a mailing list (double-opt-in)

To use double-opt-in (DOI) activation for recipients, add a new parameter to the request: confirmation=force. This will require another parameter: sender_email — provide the sender's email address as its value;

Sender's email address must be activated in your SendPulse account settings.

Request parameters:

Parameter Type Description  
id int Mailing list ID required
emails array Serialized array of email addresses, for example ["example@gmail.com", "example@outlook.com"].

If it is necessary to add an email with variables, use this structure:

 required
email string Subscriber's email address required
variables array Serialized array of variables, for example, {"name of variable":"value of variable"} required
confirmation string force required
sender_email string Sender's email address required
template_id string Confirmation email ID; it is created in the Service Settings (if the parameter is not specified, a default email will be sent); for example, a3e45169-7ae7-4a39-b457-72fd04401f26 optional
message_lang string Confirmation email's language. It can take "en", "ru", "ua", "tr", "es", "pt" values required

Request example:

{
   "emails":[
      {
         "email":"test@gmail.com",
         "variables":{
            "name":"Alona"
         }
      }
   ],
   "confirmation":"force",
   "sender_email":"sender@sendpulse.com",
   "template_id":"a3e45169-7ae7-4a39-b457-72fd04401f2l",
   "message_lang":"en"
}

If request is successful, you will receive a response:

{
   "result": true
}

Change a phone number for a contact

To change or add a phone number value for a contact in the address book, send a PUT request to:

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

Request parameters:

Parameter Type Description  
id int Mailing list ID required
email string Email address required
phone string Phone number required

Request example:

{
    "email":" user1@example.com",
    "phone":"1234567890"
}

If the request is successful, you will receive a response:

{
    "result": true
}

Delete emails from a mailing list

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

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

Request parameters:

Parameter Type Description  
id int Mailing list ID required
emails array Serialized array of emails. You can specify up to 100 email addresses to delete in one request. required

Request example:

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

If request is successful, you will receive a response:

{
   "result": true
}

Delete a mailing list

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

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

Request parameters:

Parameter Type Description  
id int Mailing list ID required

If request is successful, you will receive a response:

{
   "result": true
}

Get the cost of a campaign carried by mailing list

To calculate the cost of a campaign carried by mailing list, send a GET request to:

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

Request parameter:

Parameter Type Description  
id int Mailing list ID required

If request is successful, you will receive a response:

{
  "cur": "USD",
  "sent_emails_qty": 16,
  "overdraftAllEmailsPrice": 0,
  "addressesDeltaFromBalance": 0,
  "addressesDeltaFromTariff": 16,
  "max_emails_per_task": 500,
  "result": true
}

Response parameters:

Parameter Type Description
cur string Currency used for calculation
sent_emails_qty int Total number of email addresses
overdraftAllEmailsPrice int Price for exceeding the email address limit
addressesDeltaFromBalance int Number of email addresses user balance will be charged for
addressesDeltaFromTariff int Number of email addresses that will be charged by the tariff
max_emails_per_task int Email address tariff restrictions
result boolean Determines whether there is enough money (true or false)

Campaigns

Create a campaign

To create an email campaign, send a POST request to:

https://api.sendpulse.com/campaigns

Please note that you can send a maximum of 4 campaigns per hour.

Request parameters:

Parameter Type Description  
sender_name string Sender's name required
sender_email string Sender's email address required
subject string Email subject required
body1 string HTML code of the template, encoded in Base64 required
template_id1 int/string Template ID uploaded or created in the service. Use Get a list of all templates method to get the template ID (use either real_id or id parameter from the reply) required
list_id2 int/array

Mailing list ID or array of mailing list ID's (for example, [88891852,88891181]). You can add up to 10 mailing lists.

If you send a test campaign with the is_test parameter or a segmented campaign with the segment_id parameter, you can specify only 1 mailing list.

 required
segment_id2 int Segment ID created in your account (Mailing lists -> select mailing list -> Segments > My segments-> select segment -> copy segment id from URL in address bar) required
is_test boolean Is used to send a test email to the sender's address specified in the sender_email parameter optional
send_date string Date of the scheduled email campaign (optional parameter), must fit the following format: Y-m-d H:i:s (for example: 2016-02-02 23:34:23) and can not be less than the current date and time optional
name string Campaign name optional
use_dynamic_list boolean Used to send to a dynamic list for scheduled email сampaign. A dynamic list includes contacts that were added to your mailing list after you created a campaign, but before you send the campaign. Available on any paid pricing plan. optional
attachments array Attached files, you can add up to 5 items in which the key is the name of the attachment, and the value is the content of the attachment {"name1.extension": "content_1_file", "name2.extension": "content_2_file"} optional
attachments_binary array Attached files, you can add up to 5 items in which the key is the name of the attachment, and the value is the content of the attachment {"name1.extension": "base64_content_1_file", "name2.extension": "base64_content_2_file"} optional
type string Possible value - draft [a campaign will be created as a draft] optional
body_amp3 string AMP version of the email, encoded in base64 optional
stats object
Used to enable the collection of statistics on email opens and link clicks
 optional
clicks
bool
Click on links. By default — true
optional
opens
 bool Campaign opens. By default — true optional
utm_campaign string Adds custom UTM tags in all links in your campaing for Google Analytics and Yandex.Metrica optional

1. To specify the body of your email, you can send your template directly in the request using the body parameter, or use a template created in the service using the template_id parameter. One of the two parameters is required.

2. To specify the list of recipients, you can use the list_id or segment_id parameter, one of the two parameters is required.

3. The AMP body code must be valid and can be used only after confirmation from google and mail.ru. You can submit an application for consideration in the Service Settings.

Example of a request to create a campaign with a template:

{
    "sender_name":"my_sender_name",
    "sender_email":"my_sender@test.com",
    "subject":"hello customer",
    "list_id":"756589",
    "name":"my_api_campaign",
    "template_id": "775667"
}

Example of a request to create a scheduled campaign to a dynamic list:

{
  "sender_name":"API_TEST",
  "sender_email":"my_sender@test.com",
  "subject":"API campaign",
  "list_id":"756589",
  "name":"api campaign",
  "body": "SmFja2llIENoYW4=",
  "send_date":"2016-02-02 23:34:23",
  "use_dynamic_list": true
}

Example of a request to create a draft:

{
    "sender_name":"my_sender_name",
    "sender_email":"my_sender@test.com",
    "subject":"hello customer",
    "list_id":"756589",
    "name":"my_api_campaign",
    "body": "bXkgYXBpIGJvZHk=",
    "type":"draft"
}

Example of a request to create a campaign with an attachment:

{
    "sender_name":"my_sender_name",
    "sender_email":"my_sender@test.com",
    "subject":"hello customer",
    "list_id":"756589",
    "name":"my_api_campaign",
    "body": "bXkgYXBpIGJvZHk=",
    "attachments":{
        "text.txt":"my content file"
    }
}

Example of a request to create a campaign with an attachment (attachments_binary):

{
    "sender_name":"my_sender_name",
    "sender_email":"my_sender@test.com",
    "subject":"hello customer",
    "list_id":"756589",
    "name":"my_api_campaign",
    "body": "bXkgYXBpIGJvZHk=",
    "attachments_binary":{
        "text.txt":"bXkgY29udGVudCBmaWxlIGluIGJhc2U2NA=="
    }
}

Example of a request to create a campaign with a custom collecting statistic options:

{
    "sender_name":"my_sender_name",
    "sender_email":"my_sender_email@test.com",
    "subject":"API campaign",
    "list_id":"89286777",
    "name":"My Campaign",
    "body": "SmFja2llIENoYW4=",
    "stats":{
        "opens":true, //enabled collection of opens statistics 
        "clicks":false, //disabled collection of clicks statistics 
        "utm_campaign":"MY_UTM"
        }
}

If request is successful, you will receive a response:

{
  "id": 245587,
  "status": 13, 
  "count": 1, 
  "tariff_email_qty": 1, 
  "overdraft_price": "0.0044",
  "ovedraft_currency": "RUR" 
}

Response parameters:

Parameter Type Description
id int Email campaign ID
status int Task status for sending (13 - copying addresses for sending, 26 - draft)
count int Number of recipients to which the campaign is sent
tariff_email_qty int Number of emails written off from the user's balance
overdraft_price string Price for one email at an increase
ovedraft_currency string Currency

Edit scheduled campaign

To edit scheduled campaign, send a PATCH request to:

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

Request parameters:

Parameter Type Description  
id int Email campaign ID required
name string Email campaign name required
sender_name string Sender's name required
sender_email string Sender's email address required
subject string Email subject required
body string HTML code of template, encoded in base64 required
template_id int/string Template ID uploaded in the service. Use Get a list of all templates on an account method to get the template ID (use either real_id or id parameter from the response) required
send_date string Date of the scheduled email campaign (optional parameter). Must fit the following format: Y-m-d H:i:s (for example, 2016-02-02 23:34:23) and can not be less than the current date and time optional

Request example:

{
   "name":"my_api_campaign",
   "sender_name":"Sender",
   "sender_email":"sender@gmail.com",
   "subject":"Hello customer",
   "template_id":123348,
   "send_date":"2021-07-06 11:45:00"
}

If request is successful, you will receive a response:

{
   "result": true,
   "id": 470791
}

Get campaign information

To get campaign information, send a GET request to:

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

Request parameter:

Parameter Type Description  
id int Email campaign ID required

If request is successful, you will receive a response:

{
    "id": 14973974,
    "name": "test check link",
    "is_sms": false,
    "is_viber": false,
    "message": {
        "sender_name": "test",
        "sender_email": "e.b@sendpulse.com",
        "subject": "test check link",
        "body": "<!DOCTYPE html><html>...</html>",
        "preheader": "",
        "attachments": "",
        "list_id": 89311111
    },
    "external_stat": {
        "check_open_email": true,
        "check_redirect_link": true
    },
    "status": 3,
    "all_email_qty": 2,
    "tariff_email_qty": 2,
    "paid_email_qty": 0,
    "overdraft_price": 0,
    "company_price": "0.05",
    "overdraft_currency": "UAH",
    "send_date": "2021-09-01 10:55:39",
    "permalink": "http://archive.sendpulse.com//u/NzA0MzY2sdghM34w==/8wxdgwz43q/", 
    "statistics": {
        "general": [ 
            {
                "code": 0,
                "count": 0,
                "explain": "In queue"
            },
            {
                "code": 1,
                "count": 2, 
                "explain": "Sent" 
            },
            {
                "code": 2,
                "count": 2, 
                "explain": "Delivered" 
            },
            {
                "code": 3,
                "count": 2, 
                "explain": "Opened"
            },
            {
                "code": 4,
                "count": 2, 
                "explain": "Link redirected"
            },
            {
                "code": 5,
                "count": 0,
                "explain": "User unsubscribe"
            },
            {
                "code": 6,
                "count": 0,
                "explain": "Mail server answer :: No such email"
            },
            {
                "code": 7,
                "count": 0,
                "explain": "Temporary unavailable (will be sent later)"
            },
            {
                "code": 8,
                "count": 0,
                "explain": "Unavailable"
            },
            {
                "code": 9,
                "count": 0,
                "explain": "Mail server answer :: Rejected by server as spam"
            },
            {
                "code": 10,
                "count": 0,
                "explain": "Mail server answer :: Mailbox is full"
            },
            {
                "code": 11,
                "count": 0,
                "explain": "Mail server answer :: Marked as spam by user"
            },
            {
                "code": 12,
                "count": 0,
                "explain": "Delivery failure"
            },
            {
                "code": 13,
                "count": 0,
                "explain": "Not sent"
            },
            {
                "code": 14,
                "count": 0,
                "explain": "Not such domain"
            },
            {
                "code": 15,
                "count": 0,
                "explain": "Unsubscribe from newsletter"
            },
            {
                "code": 16,
                "count": 0,
                "explain": "Not valid email"
            },
            {
                "code": 17,
                "count": 0,
                "explain": "Temporary blocked"
            },
            {
                "code": 18,
                "count": 0, 
                "explain": "Disable by administrator"
            },
            {
                "code": 20,
                "count": 0,
                "explain": "Already unsubscribed"
            }
        ],
        "clicks": [
            {
                "url": "https://s7043663.sendpul.se/views/ru/{{CampaignId}}/{{EmailCode}}/h/e5203e703e95d001c286990chdfh45fc87ee",
                "count": 0
            },
            {
                "url": "https://habr.com/ru/all/",
                "count": 3
            },
            {
                "url": "",
                "count": 0
            },
            {
                "url": "https://sendpulse.com/ru/email-powered-by-sendpulse?sn=d3BsgjksfsfhadGVzdA%3D%3D&amp;amp;from=70474573563663",
                "count": 0
            }
        ]
    }
}

Possible campaign statuses:

Status code Status description
0 New
1 Pending (in moderation)
2 Sending in progress
3 Sent
4 Test campaign (sent to user's email address)
5 Campaign blocked (by the service)
6 The campaign marked to be deleted
7 Status updating (status 3 will follow)
8 Test campaign sent
9 Delivery in progress
10 The campaign being processed to be sent out
11 Awaiting the user's response to the moderator's query
12 No active addresses
13 Campaign creation in progress — emails are transferring into the campaign from the mailing list. Status 2 will follow if there are less than 20 emails on the list; otherwise, code 1 will follow.
14 Campaign created and sent to the queue. Status 3 will follow when all messages are sent.
15 Campaign awaiting A/B testing results
16 Campaign canceled by a user
22 Sending partially
23 Sent partially
25 Campaign partially sent and blocked by service admin
26 Draft
27 Requires editing
28 Scheduled to resend the message to unread
33 Automations. Balance exceeded
36 Automations draft

Get a list of campaigns

To get a list of campaigns, send a GET request to:

https://api.sendpulse.com/campaigns

Request parameters:

Parameter Type Description  
limit int Number of records optional
offset int Offset (first record to display) optional
order string Sort parameter, asc — from highest to lowest, desc — from lowest to highest optional
status array List of email campaign statuses (int) optional
planed boolean A parameter that allows you to return scheduled campaigns optional

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

https://api.sendpulse.com/campaigns?order=desc&status[]=3&planed=1&limit=100&offset=10

If request is successful, you will receive a response:

[
    {
        "id": 14911111,
        "name": "test check link",
        "status": 3,
        "is_sms": false,
        "is_viber": false,
        "send_date": "2021-09-01 10:55:39",
        "all_email_qty": 2,
        "tariff_email_qty": 2,
        "paid_email_qty": 0,
        "overdraft_price": 0,
        "company_price": "0.05",
        "overdraft_currency": "UAH",
        "message": {
            "sender_name": "test",
            "sender_email": "e.b@sendpulse.com",
            "subject": "test check link",
            "attachments": "",
            "list_id": 89311111
        },
        "statistics": {
            "sent": 2,
            "delivered": 2,
            "opening": 2,
            "link_redirected": 2,
            "unsubscribe": 0,
            "error": 0
        }
    }
]

Response parameters:

Parameter Type Description
id int Email campaign ID
name string Email campaign name
is_sms boolean Parameter that determines whether this campaign is an SMS campaign
is_viber boolean Parameter that determines whether this campaign is a Viber campaign
send_date string Campaign sending date
company_price string Campaign price
sender_name string Sender's name
sender_email string Sender's email address
subject string Email subject
body string Email body
list_id int Mailing list ID
attachments string Attachments
status int Email campaign status code
all_email_qty int Total number of email addresses
tariff_email_qty int Number of emails written off the user's balance
paid_email_qty int Number of email addresses paid from the balance above the tariff limit
overdraft_price int Price per letter if exceeded
overdraft_currency string Currency
sent int Sent message total
delivered int Delivered messages total
opening int Opened messages total
link_redirected int Number of link redirections
unsubscribe int Unsubscribed users total
error int Errors number

Get a list of campaigns created that use a specific mailing list

To get a list of campaigns created that use a specific mailing list, send a GET request to:

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

Request parameters:

Parameter Type Description  
id int Mailing List ID required
limit int Number of records optional
offset int Offset (first record to display) optional

If request is successful, you will receive a response:

[
   {
      "task_id": 9147593,
      "task_name": "Test",
      "task_status": 3
   },
   {
      "task_id": 9156095,
      "task_name": "Campaign_6741804_UM99",
      "task_status": 3
   }
]

Response parameters:

Parameter Type Description
task_id int Email campaign ID
task_name string Email campaign name
tast_status int Email campaign status code

Get a country statistics

To get a country statistics, send a GET request to:

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

Request parameter:

Parameter Type Description  
id int Email campaign ID required

If request is successful, you will receive a response:

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

Response parameters:

Parameter Type Description
US (UA) int Emails opened

Get referrals statistics

To get referrals statistics, send a GET request to:

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

Request parameter:

Parameter Type Description  
id int Email campaign ID required

If request is successful, you will receive a response:

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

Response parameters:

Parameter Type Description
link string URL from the email
count int Number of link clicks

Cancel a campaign

To cancel a campaign, send a DELETE request to:

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

Request parameter:

Parameter Type Description  
id int Email campaign ID required

If request is successful, you will receive a response:

{
   "result": true
}

Templates

Create a template

To create a template, send a POST request to:

https://api.sendpulse.com/template

Request parameters:

Parameter Type Description  
name string Name of the template (the parameter is optional, if not specified, the name will be displayed as Template YYYY.mm.dd H:i:s) required
body string HTML version of the email, encoded in base64 required
lang string Template language, can take ​​"ru", "en", "ua", "tr", "es", "pt" values required

Request example:

{
   "name": "My Template",
   "body": "PGlucHV0IHR5cGU9ImVtYWlsIiBuYW1lPSJlbWFpbCIgcmVxdWlyZWQKb25pbnZhbGlkPSJ0aGlzLnNldEN1c3RvbVZhbGlkaXR5KCfQn9C+0LbQsNC70YPQudGB0YLQsCwg0L3QsNC/0LjRiNC40YLQtSBlbWFpbCDQu9Cw0YLQuNC90YHQutC40LzQuCDQsdGD0LrQstCw0LzQuCcpIiBvbmlucHV0PSJzZXRDdXN0b21WYWxpZGl0eSgnJykiIC8+",
   "lang": "ru"
}

If request is successful, you will receive a response:

{
    "result": true,
    "real_id": 1042220
}

Response parameter:

Parameter Type Description
real_id int Created template ID

Edit a template

To edit a template, send a POST request to:

https://api.sendpulse.com/template/edit/{id}

Request parameters:

Parameter Type Description  
id int/string Template ID uploaded in the service. Use Get a list of all templates on an account method to get the template ID (use either real_id or id parameter from the reply) required
body string HTML version of the email, encoded in base64 required
lang string Template language optional

Please note that the template language lang must be the one that was specified during the creation of this template.

Request example:

{
   "body": "PGlucHV0IHR5cGU9ImVtYWlsIiBuYW1lPSJlbWFpbCIgcmVxdWlyZWQKb25pbnZhbGlkPSJ0aGlzLnNldEN1c3RvbVZhbGlkaXR5KCfQn9C+0LbQsNC70YPQudGB0YLQsCwg0L3QsNC/0LjRiNC40YLQtSBlbWFpbCDQu9Cw0YLQuNC90YHQutC40LzQuCDQsdGD0LrQstCw0LzQuCcpIiBvbmlucHV0PSJzZXRDdXN0b21WYWxpZGl0eSgnJykiIC8+",
   "lang": "ru"
}

If request is successful, you will receive a response:

{
   "result" : true
}

Get information about a template

To get information about template, send a GET request to:

https://api.sendpulse.com/template/{template_id}

Request parameters:

Parameter Type Description  
template_id int/string Template ID uploaded in the service. Use Get a list of all templates on an account method to get the template ID (use either real_id or id parameter from the reply) required

If request is successful, you will receive a response:

{
   "id":"f3266876955c9d21e214deed49b97446",
   "real_id":1153018,
   "lang":"en",
   "name":"Webinar Speakers",
   "name_slug":"",
   "created":"2020-09-04 13:54:30",
   "full_description":"Use this template as a webinar invitation for your subscribers. Specify who is going to host the webinar and what it will be about. Remember to include the date and time of the webinar.",
   "is_structure":true,
   "category":"education",
   "category_info":{
      "id":109,
      "name":"Education",
      "meta_description":"These “Education” free email templates were developed by SendPulse for all those who wish to make their email communication colorful and unforgettable. You can use these templates to create your email campaigns in SendPulse.",
      "full_description":"",
      "code":"education",
      "sort":6
   },
   "tags":{
      "webinar":"webinar",
      "study":"study",
      "marketing":"marketing",
      "museum":"museum",
      "exhibition":"exhibition"
   },
   "owner":"sendpulse",
   "preview":"https://login.sendpulse.com/files/emailservice/userfiles/templates/preview/f3266876955c9d21e214deed49b97446_thumbnail_300.png"
}

Get a List of Templates on an Account

To get a list of templates on an account, send a GET request to:

https://api.sendpulse.com/templates

If request is successful, you will receive a response:

[  
   {  
      "id":"c7a94d4f8395ae5a4183423309d5e99b",
      // Please note,  value changes each time you edit template  
      "real_id":775667,
      "lang":"en",
      "name":"Nov. 9, 2018 08:24:10",
      "name_slug":"nov-9-2018-08-24-10",
      "created":"2018-11-09 05:24:10",
      "full_description":null,
      "category":"",
      "category_info":[  

      ],
      "tags":[  

      ],
      "owner":"you",
      "preview":"https://login.sendpulse.com/files/emailservice/templates/preview/e52678826db12b069358f159fde800726741804/c7a94d4f8395ae5a4183423309d5e99b.png"
   },
   {  
      "id":"5979adc7712b8c822a28b486f9778a15",
      "real_id":508742,
      "lang":"en",
      "name":"Valentine\\'s Day: sweet",
      "name_slug":"sweet-valentines-day",
      "created":"2018-02-01 08:55:04",
      "full_description":"",
      "category":"holiday",
      "category_info":{  
         "id":146,
         "name":"Holiday",
         "meta_description":"These “Holiday” free email templates were developed by SendPulse. Congratulate your customers, friends or relatives. Use these templates to create your own email campaigns in SendPulse.",
         "full_description":"",
         "code":"holiday",
         "sort":2
      },
      "tags":{  
         "valentine":"valentine"
      },
      "owner":"sendpulse",
      "preview":"https://login.sendpulse.com/files/emailservice/templates/preview/5979adc7712b8c822a28b486f9778a15_thumbnail.png"
   }
]

Get a list of all system templates

To get a list of all system templates, send a GET request to:

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

Get a list of all user templates

To get a list of all user templates, send a GET request to:

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

Get a template by name

To get a template by name, send a GET request to:

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

Request parameter:

Parameter Type Description  
name_slug string System name of the template, you can find it in the API response for creating or searching for templates by other parameters required

Get a list of all templates in a specific language

To get a list of all templates in a specific language, send a GET request to:

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

Senders

Get a list of all senders

To get a list of all senders, send a GET request to:

https://api.sendpulse.com/senders

If request is successful, you will receive a response:

[
    {
        "email": "user1@example.com",
        "name": "user1",
        "status": "Active",
        "is_allowed_for_smtp": true* 
    },
    {
        "email": "user2@example.com",
        "name": "user2",
        "status": "Active",
        "is_allowed_for_smtp": false*
    }

Response parameters:

Parameter Type Description  
name string Sender name  
email string Sender email  
status string Sender status  
is_allowed_for_smtp boollean Specifies whether an email address is allowed in the SMTP service.

SendPulse has merged sender email addresses for the Email and SMTP service. For all email addresses you add after 2023-05-17, the Email service will add a parameter with the true value, which means that you can use these email addresses in the SMTP service as well.		  

Add a sender

To add a sender, send a POST request to:

https://api.sendpulse.com/senders

SendPulse has merged sender email addresses for the Email and SMTP service. You can use email addresses you add to the Email service after 2023-05-17 in the SMTP service as well.

Request parameters:

Parameters Type Description  
email string Sender’s email address required
name string Sender’s name required

Request example:

{
   "email": "sender@example.com",
   "name": "Sender"
}

If request is successful, you will receive a response:

{
   "result": true
}

Delete a sender

To delete a sender, send a DELETE request to:

https://api.sendpulse.com/senders

Request parameter:

Parameter Type Description  
email string Sender’s email address required

Request example:

{
   "email": "sender@example.com"
}

If request is successful, you will receive a response:

{
   "result": true
}

Activate a sender

To activate a sender, send a POST request to:

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

Request parameters:

Parameter Type Description  
email string Sender's email address required
code string Activation code required

Request example:

{
   "code": "50405325fdbb31e79759e7b8ae305ef75"
}

If request is successful, you will receive a response:

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

Get an activation code to the sender’s email address

To get an activation code to the sender's email address, send a GET request to:

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

Request parameter:

Parameter Type Description  
email string Sender's email address required

If request is successful, you will receive a response:

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

If the request was successful, the sender will receive an email with the activation code.

Email address

Get general information about a specific email address

To get general information about a specific email address, send a GET request to:

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

Request parameter:

Parameter Type Description  
email string Email address required

If request is successful, you will receive a response:

[
   {
      "book_id":154441,
      "email":"test@gmail.com",
      "status":0,
      "status_explain":"New",
      "variables":[]
   },
   {
      "book_id":422325,
      "email":"test@gmail.com",
      "status":1,
      "status_explain":"Active",
      "variables":[
         {
            "name":"Name",
            "type":"string",
            "value":"Alona"
         }
      ]
   }
]

Get detailed information about a specific email address

To get detailed information about a specific email address, send a GET request to:

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

Request parameter:

Parameter Type Description  
email string Email address required

If request is successful, you will receive a response:

[
    {
        "list_name": "test1",
        "list_id": 1375516,
        "add_date": "2017-11-21 11:45:41",
        "source": "panel"
    },
    {
        "list_name": "test2",
        "list_id": 1415158,
        "add_date": "2018-01-23 07:07:08",
        "source": "panel"
    },
    {
        "list_name": "subscriptions",
        "list_id": 1649207,
        "add_date": "2018-04-02 13:55:38",
        "source": "form"
    }
]

Get general information for a list of email addresses

To get general information for a list of email addresses, send a POST request to:

https://api.sendpulse.com/emails

Request parameter:

Parameter Type Description  
emails array List of email adresses required

Request example:

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

If request is successful, you will receive a response:

{
   "test1@gmail.com":[
      {
         "book_id":154441,
         "status":0,
         "variables":[]
      },
      {
         "book_id":422325,
         "status":1,
         "variables":[
            {
               "name":"Name",
               "type":"string",
               "value":"Test"
            }
         ]
      }
   ],
   "test2@gmail.com":[
      {
         "book_id":422325,
         "status":1,
         "variables":[
            {
               "name":"Name",
               "type":"string",
               "value":"Test"
            }
         ]
      }
   ]
}

Get information for a specific email address from a specific campaign

To get information for a specific email address from, send a GET request to:

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

Request parameters:

Parameter Type Description  
id int Email campaign ID required
email string Email address required

If request is successful, you will receive a response:

{
    "sent_date": "2021-03-29 07:46:58",
    "global_status": 1,
    "global_status_explain": "Sent",
    "detail_status": 3,
    "detail_status_explain": "Opened"
}

Response parameters:

Parameter Type Description
send_date string Date of sending the email campaign
global_status int Global email campaign status code
global_status_explain string Global status description
detail_status int Detailed email campaign status code
detail_status_explain string Detailed status description

Get information for an email address from a mailing list

To get information for an email address from a mailing list, send a GET request to:

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

Request parameters:

Parameter Type Description  
id int Mailing list ID required
email string Email address required

If request is successful, you will receive a response:

{
    "email": "test@gmail.com",
    "abook_id": "422325",
    "phone": "",
    "status": 1,
    "status_explain": "Active",
    "variables": [
        {
            "name": "Name",
            "type": "string",
            "value": "Test"
        }
    ]
}

Response parameters:

Parameter Type Description
email string Email address
abook_id string Mailing list ID
phone string Phone number
status int Email address status code
status_explain string Email address status description
variables array Array of variables for the email (equals [] if the contact has no variables, or the variable is empty):
name string Variable name
type string Variable type
value string Variable value

Delete an email address from all mailing lists

To delete an email address from all mailing lists, send a DELETE request to:

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

Request parameter:

Parameter Type Description  
email string Email address required

If request is successful, you will receive a response:

{
   "result": true
}

Get statistics for an email address and campaigns it is in

To get statistics for an email address and campaigns it is in, send a GET request to:

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

Request parameter:

Parameter Type Description  
email string Email address required

If request is successful, you will receive a response:

{
    "statistic": {
        "sent": 9,
        "open": 2,
        "link": 0
    },
    "blacklist": false,
    "addressbooks": [
        {
            "id": 154441,
            "address_book_name": "Mailing list 1"
        },
        {
            "id": 154472,
            "address_book_name": "Mailing list 2"
        }
    ]
}

Get statistics for multiple email addresses and campaigns they are in

To get statistics for multiple email addresses and campaigns they are in, send a POST request to:

https://api.sendpulse.com/emails/campaigns

Request parameter:

Parameter Type Description  
emails array List of email addresses required

Request example:

{
   "emails": ["example@yourdomain.com", "example2@yourdomain.com"]
}

If request is successful, you will receive a response:

{
    "example@yourdomain.com": {
        "sent": 21,
        "open": 11,
        "link": 3,
        "adressbooks": [
            {
                "id": 1375516,
                "name": "book1"
            },
            {
                "id": 1415158,
                "name": "book3"
            },
            {
                "id": 1649207,
                "name": "book10"
            }
        ],
        "blacklist": false
    },
    "example2@yourdomain.com": {
        "sent": 1,
        "open": 1,
        "link": 0,
        "adressbooks": [
            {
                "id": 1734397,
                "name": "тест1"
            }
        ],
        "blacklist": true
    }
}

Change a variable for an email contact

To change a variable for an email, send a POST request to:

https://api.sendpulse.com/addressbooks/{addressBookId}/emails/variable

Request parameters:

Parameter Type Description  
addressBookId int Mailing list ID required
email string Email contact address required
variables array List of variables, for example, {"name":"name", "value":"John"}  required

Request example:

{
   "email":"myemail@example.com",
   "variables":[
      {
         "name":"name",
         "value":"John"
      },      
      {
         "name":"date",
         "value":"2019-02-01"
      }
   ]
}

If request is successful, you will receive a response:

{
    "result": true
}

You can change only one email per request

Variables of string type accept either numeric values or values expressing the date in the following format: YYYY-MM-DD.

Variables of number type accepts only numbers.

Variable of date type only accepts a date in the following format: YYYY-MM-DD. Other formats are not supported. E.g.: a valid date: 2017-01-01, invalid date: 2017-1-1.

Blacklist

Get a list of contacts in blacklist

To view the blacklist, send a GET request to:

https://api.sendpulse.com/blacklist

If request is successful, you will receive a response:

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

Add an email address to blacklist

To add to blacklist an email address, send a POST request to:

https://api.sendpulse.com/blacklist

Request parameters:

Parameter Type Description  
emails string Email addresses separated by commas and encoded in Base64 required
comment string Comment optional

Request example:

{
   "emails": "dXNlcjFAbWFpbHNlcnZlci5jb20sdXNlcjJAbWFpbHNlcnZlci5jb20sdXNlcjNAbWFpbHNlcnZlci5jb20=",
   "comment": "comment"
}

If request is successful, you will receive a response:

{
    "result": true
}

Unsubscribe a contact from a specific mailing list

To unsubscribe a contact from a specific mailing list, send a POST request to:

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

Request parameters:

Parameter Type Description  
id int Mailing list ID required
emails array List of email addresses that you want to unsubscribe from the defined mailing list required

Request example:

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

If request is successful, you will receive a response:

{
    "result": true
}

Delete an email address from the blacklist

To delete an email address from the blacklist, send a DELETE request to:

https://api.sendpulse.com/blacklist

Request parameters:

Parameter Type Description  
emails string List of email addresses separated by commas and encoded in base64 required

Example of a string with email addresses (before base64 encoding):

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

Request example:

{
   "emails": "dXNlcjFAbWFpbHNlcnZlci5jb20sdXNlcjJAbWFpbHNlcnZlci5jb20sdXNlcjNAbWFpbHNlcnZlci5jb20="
}

If request is successful, you will receive a response:

{
    "result": true
}

Balance

Get your balance information

To get your balance information, send a GET request to:

https://api.sendpulse.com/balance

An optional request parameter — the currency value.

When using an optional parameter, form a URL of the following format:

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

If request is successful, you will receive a response:

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

Get detailed balance information

To get detailed balance information, send a GET request to:

https://api.sendpulse.com/user/balance/detail

If request is successful, you will receive a response:

{
    "balance": {
        "main": "9.36",
        "bonus": "5.00",
        "currency": "USD"
    },
    "email": {
        "tariff_name": "Pay as you go 10 000",
        "finished_time": "2019-04-25 08:03:02",
        "emails_left": 9914,
        "maximum_subscribers": 10000,
        "current_subscribers": 0
    },
    "smtp": {
        "tariff_name": "SMTP Free",
        "end_date": "2018-11-21 15:05:39",
        "auto_renew": 1
    },
    "push": {
        "tariff_name": "White Label",
        "end_date": "2018-11-30",
        "auto_renew": 1
    }
}

Webhooks

For more information about webhooks, how to connect them in your personal SendPulse account, and examples of the received webhooks format for events, check out the article How to connect webhooks in an email service.

You can also create, edit and receive information about webhooks through the following API methods:

Get a list of webhooks

To get a list of webhooks, send a GET request to:

https://api.sendpulse.com/v2/email-service/webhook

If request is successful, you will receive a response:

{
    "success": true,
    "data": [
        {
            "id": 162242,
            "user_id": 7043663,
            "url": "https://site.com/callback",
            "action": "unsubscribe"
        },
        {
            "id": 162241,
            "user_id": 7043663,
            "url": "https://site.com/callback",
            "action": "open"
        }
    ]
}

Get a webhook by ID

To get a webhook by ID, send a GET request to:

https://api.sendpulse.com/v2/email-service/webhook/{id}

Request parameters:

Parameter Type Description  
id int Webhook ID required

If request is successful, you will receive a response:

{
    "success": true,
    "data": {
        "id": 162242,
        "user_id": 7043663,
        "url": "https://site.com/callback",
        "action": "unsubscribe"
    }
}

Create a webhook

To create a webhook, send a POST request to:

https://api.sendpulse.com/v2/email-service/webhook/

Request parameters:

Parameter Type Description  
actions string/array Tracked events, for example, ["open","unsubscribe"] required
url string URL to the handler, for example, https://site.com/callback required

Possible values for actions:

Action Description
new_emails Adding a new email address
delete Email address deleted from the mailing list
unsubscribe User unsubscribed
task_status_update  Campaign status changed
open Campaign was opened
delivered Delivered
redirect Following link
spam User marked as spam
hard_bounces Received Hard Bounce 
soft_bounces Received Soft Bounce

The data is sent with the x-www-form-urlencoded type. 

Request example:

{
    "url":"https://site.com/callback",
    "actions":["delivered"]
}

If request is successful, you will receive a response:

{
    "success": true,
    "data": [
        {
            "user_id": 7043663,
            "url": "https://site.com/callback",
            "id": 162241,
            "action": "open"
        },
        {
            "user_id": 7043663,
            "url": "https://site.com/callback",
            "id": 162242,
            "action": "unsubscribe"
        }
    ]
}

Delete a webhook

To delete a webhook, send a DELETE request to:

https://api.sendpulse.com/v2/email-service/webhook/{id}

Request parameter:

Parameter Type Description  
id int Webhook ID required

If request is successful, you will receive a response:

{
    "success": true,
    "data": [
        true
    ]
}

Update a webhook

To update a webhook, send a PUT request to:

https://api.sendpulse.com/v2/email-service/webhook/{id}

The data is sent with the x-www-form-urlencoded type.

Request parameters:

Parameter Type Description  
id int Webhook ID required
url string URL to the handler, for example, https://site.com/callback required

If request is successful, you will receive a response:

{
    "success": true,
    "data": [
        true
    ]
}