Sending an email

In order to send an email, submit a POST request to:

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

Request parameters:

email a serialized array with email data

Email array parameters:

html The HTML version of the email, encoded in base64
text The text version of the email
subject The email subject
from An array containing the sender’s name and email address
to An array of recipients
bcc An array
attachments An array in which the key is the name of the file, and the value is the contents of the file
attachments_binary An array in which the key is the name of the file, and the value is the contents of the file, encoded in base64

 

An example of an email address array structure

 

{
  "html" : "<p>Example text</p>",
  "text" : "Example text",
  "subject" : "Example subject",
  "from" : {
      "name" : "Example name",
      "email" : "sender@example.com"
  },
  "to" : [
      {
  "name" : "Recipient1 name",
  "email" : "recipient1@example.com"
      },
      {
  "name" : "Recipient2 name",
  "email" : "recipient2@example.com"
      },
  ],
  "bcc" : [
      {
  "name" : "Recipient1 name",
  "email" : "recipient1@example.com"
      },
      {
  "name" : "Recipient2 name",
  "email" : "recipient2@example.com"
      },
  ]
}

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

 

Retrieving a list of emails

In order to retrieve a list of all emails sent, submit a GET request to:

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

Request parameters (optional):

limit Number of entries
offset Sample offset
from Sample start date
to Sample max date
sender Sender
recipient Recipient

 

A sample response:

 

{
  "id": "123123",
  "sender": "JohnDoe@test.com",
  "total_size": "1128",
  "sender_ip": "127.0.0.1",
  "smtp_answer_code": "250",
  "smtp_answer_subcode": "0",
  "smtp_answer_data": "Bad recipients",
  "used_ip": "5.104.224.87",
  "recipient": null,
  "subject": "SendPulse :: Email confirmation",
  "send_date": "2013-12-17 10:33:53",
  "tracking": {
    "click": 1,
    "open": 1,
    "link": [
      {
"url": "http://some-url.com",
"browser": "Chrome 29.0.1547.57",
"os": "Linux",
"screen_resolution": "1920x1080",
"ip": "46.149.83.86",
"country": "USA",
"action_date": "2013-09-30 11:27:40"
      }
    ],
    "client_info": [
      {
"browser": "Thunderbird 17.0.8",
"os": "Linux",
"ip": "46.149.83.86",
"country": "USA",
"action_date": "2013-09-30 11:27:49"
      }
    ]
  }
}

 

Retrieving information for a specific email

In order to retrieve information for a specific email, submit a GET request to:

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

Request parameters:

id Email ID

 

A sample response:

 

{
  "id": "123123",
  "sender": "JohnDoe@test.com",
  "total_size": "1128",
  "sender_ip": "127.0.0.1",
  "smtp_answer_code": "250",
  "smtp_answer_subcode": "0",
  "smtp_answer_data": "Bad recipients",
  "used_ip": "5.104.224.87",
  "recipient": null,
  "subject": "SendPulse :: Email confirmation",
  "send_date": "2013-12-17 10:33:53",
  "tracking": {
    "click": 1,
    "open": 1,
    "link": [
      {
"url": "http://some-url.com",
"browser": "Chrome 29.0.1547.57",
"os": "Linux",
"screen_resolution": "1920x1080",
"ip": "46.149.83.86",
"country": "Ukraine",
"action_date": "2013-09-30 11:27:40"
      }
    ],
    "client_info": [
      {
"browser": "Thunderbird 17.0.8",
"os": "Linux",
"ip": "46.149.83.86",
"country": "USA",
"action_date": "2013-09-30 11:27:49"
      }
    ]
  }
}

 

Unsubscribing a recipient

In order to unsubscribe a recipient, submit a POST request to:

https://api.sendpulse.com/smtp/unsubscribe

Request parameters:

emails A serialized email array

 

An example of an email address array structure

 

[
  {
    "email": "badUser1@mailserver.com",
    "comment": "comment1"
  },
  {
    "email": "badUser2@mailserver.com",
    "comment": "comment2"
  }
]

 

 

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

 

Erasing from the unsubscribed list

In order to remove an entry from the unsubscribed list, submit a DELETE request to:

https://api.sendpulse.com/smtp/unsubscribe

Request parameters:

emails A serialized email array

 

An example of an email address array structure:

 

{
  "JohnDoe@test.com",
  "JaneDoe@test.com"
}

 

 

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

 

Retrieving the sender’s IP address

In order to retrieve the list of sender IP addresses, submit a GET request to:

https://api.sendpulse.com/smtp/ips

 

A sample response:

[
  "127.0.0.1"
]

 

Retrieving a list of allowed domains

In order to retrieve a list of the allowed domains, submit a GET request to:

https://api.sendpulse.com/smtp/domains

 

A sample response:

 

[
  "@gmail.com"
]

 

 Retrieving the list of unsubscribed

In order to retrieve bounces, submit a GET request to

https://api.sendpulse.com/smtp/unsubscribe

Request parameters:

day The day you want to get information about. Format: YYYY-MM-DD
limit Number of entries
offset Sample offset

Example: https://api.sendpulse.com/smtp/unsubscribe?limit=10&offset=20 - you will receive 10 entries starting from с 20

You you point the day, the data will be for 1 day

Example of the request with the date: smtp/unsubscribe?date=2016-03-05

 

Retrieving bounces per 24 hours

In order to retrieve bounces, submit a GET request to

https://api.sendpulse.com/smtp/bounces/day

Request parameters:

day The day you want to get information about. Format: YYYY-MM-DD
limit Number of entries
offset Sample offset

Example: https://api.sendpulse.com/smtp/bounces/day?limit=10&offset=20 - you will receive 10 entries starting from с 20

You can get bounces only for the last 24 hours starting from this moment. Example: today is - 2016-04-28 14:34:00, you will get entries from 2016-04-27 14:34:00 till 2016-04-28 14:34:00

 

Adding a domain

In order to add a domain, submit a POST request to:

https://api.sendpulse.com/smtp/domains

Request parameters:

email Sender’s email address

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

 

New domain verification

In order to activate and verify a new domain, submit a GET request to:

https://api.sendpulse.com/smtp/domains/{email}

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

Additionally, the new domain verification code will be sent to the specified email address.

 

WebHooks

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

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

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

  • Delivered
  • Not delivered
  • Open 
  • Click on a link
  • Marked as spam
  • Unsubscribed

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

  • Data type: JSON
  • Request type: POST

The data is sent every minute or when the number of events reaches 1,000 events (but these two criteria may change in future).

The main data format for a request:

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

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

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

Examples of requests for each event:

Delivered

[
  {
    "smtp_server_response_code": "250",
    "smtp_server_response_subcode": "",
    "sender": "john.doe@sendpulse.com",
    "smtp_server_response": "custom_text_response_from_recipients_server",
    "timestamp": 1490953933,
    "recipient": "doe.john@sendpulse.com",
    "event": "delivered",
    "subject": "utf8_hello_world"
  }
]

Not delivered

[
  {
    "smtp_server_response_code": "554",
    "smtp_server_response_subcode": "5.7.1",
    "sender": "john.doe@sendpulse.com",
    "smtp_server_response": "custom_text_response_from_recipients_server",
    "timestamp": 1490956117,
    "recipient": "doe.john@sendpulse.com",
    "event": "undelivered",
    "subject": "utf8_hello_world"
  }
]

Open

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

Click on a link

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

Marked as spam

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

Unsubscribed

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

An example of script that processes a webhook in PHP

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