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

Sending an Email

To send an email, submit a POST request to:

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

Request parameters:

email A serialized object with email data

Email array parameters:

html* HTML version of an email, encoded in Base64
text* Text version of the email
template* id Template ID that was uploaded in the service. Use this method to get the template ID (use either real_id or id parameter from the reply) 
variables includes variables' names and values in such a format: variables: {"name of the variable in the template": "value of the variable for this email"}
subject Email subject
from An array containing the sender’s name and email address
to An array of recipients
attachments An array where the key is the name of the file, and the value is the contents of the file (optional)
attachments_binary An array where the key is the name of the file, and the value is the contents of the file, encoded in Base64 (optional)

*Note: You can use parameter html and text to send the template directly in this request.

or you can use the parameter template and send a static template uploaded to the email service and send only values for these variables (which were added in template)

Example of sending a custom template:

{
  "email": {
    "html": "PHA+RXhhbXBsZSB0ZXh0PC9wPg==",
    "text": "Example text",
    "subject": "Example subject",
    "from": {
      "name": "Example name",
      "email": "sender@example.com"
    },
    "to": [
      {
        "name": "Recipient1 name",
        "email": "recipient1@example.com"
      }
    ]
  }
}

Example of sending a system template with custom variables:

{
  "email": {
    "subject": "Test",
    "template": {
      "id": 123456,
      "variables": {
        "name": "George",
        "code": "123456"
      }
    },
    "from": {
      "name": "Mike",
      "email": "mike.johnson@domain.com"
    },
    "to": [
      {
        "email": "recipient1@example.com",
        "name": "George"
      }
    ]
  }
}

In this example, a «template» parameter is used instead of html and text parameters.

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

A sample response:

{
    "result": true,
    "id": "pzkic9-0afezp-fc"
}
 

Retrieving a List of Emails

To retrieve a list of all sent emails, 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
country when "off", country will not be specified

A sample response:

{
  "id": "pzkic9-0afezp-fc"
  "sender": "JohnDoe@test.com",
  "message_id": "1267371103"
  "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 Total Amount of Sent Emails

Submit a GET request to:

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

A sample response:

{
    "total": 25408
}
 

Retrieving Information About a Specific Email

To retrieve information about a specific email, submit a GET request to:

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

Request parameters:

id Email ID

A sample response:

{
  "id": "pzkic9-0afezp-fc",
  "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"
      }
    ]
  }
}
 

Retrieving Information for a List of Emails

To retrieve information, submit a POST request to:

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

Request parameters:

emails array of message ID's, max 500 per request
 

Retrieving Information About Bounces for a 24-hour Period

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 the 20th

You can get information about bounces only for the last 24 hours starting from this moment. Example: today is - 2016-04-28 14:34:00, you will get infromation about bounces that occured between 2016-04-27 14:34:00 and 2016-04-28 14:34:00.

A sample response:

{
  "id": "pzkic9-0afezp-fc",
  "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": "UK",
	"action_date": "2013-09-30 11:27:40"
      }
    ],
    "client_info": [
      {
	"browser": "Thunderbird 17.0.8",
	"os": "Linux",
	"ip": "46.149.83.86",
	"country": "UK",
	"action_date": "2013-09-30 11:27:49"
      }
    ]
  }
}
 

Total Number of Bounces

Submit a GET request to:

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

A sample response:

{
    "total": 3
}
 

Unsubscribing a Recipient

To unsubscribe a recipient, submit a POST request to:

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

Request parameters:

emails A serialized email array

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

 

Removing an Email From the Unsubscribed List

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 ["badUser1@mailserver.com","badUser2@mailserver.com"]

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

 

 Retrieving a List of Unsubscribed Users

To retrieve bounces, submit a GET request to

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

Request parameters:

day The day you would like 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 the 20th

If you enter a specific day, the data will be for 1 day.

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

Sample response:

[  
   {  
      "email":"4090797@mail.ru",
      "unsubscribe_by_link":1,
      "unsubscribe_by_user":0,
      "spam_complaint":1,
      "date":"2018-11-24 19:19:01"
   },
   {  
      "email":"4lik@rambler.ru",
      "unsubscribe_by_link":1,
      "unsubscribe_by_user":0,
      "spam_complaint":1,
      "date":"2019-03-20 16:47:01"
   }
]
 

Retrieving the Sender’s IP Address

In order to retrieve a 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

To retrieve a list of allowed domains, submit a GET request to:

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

A sample response:

[
  "@sendpulse.com"
]
 

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"

 

Verification of a New Domain

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, a new domain verification code will be sent to the specified email address.

 

WebHooks

A WebHook is a mechanism used to receive notifications about certain events within your email campaign. To add a webhook please go to "Account settings" → "API".

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

LIst of events that can be selected for a webhook about an email sent via the SMTP service:

  • Delivered
  • Not delivered
  • Opened
  • Clicked on a link
  • Marked as spam
  • Unsubscribed

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

  • Data type: JSON
  • Request type: POST

The data is sent every minute or when the number of a specified event count reaches 100.

The main data format for a request:

[
  {
    "event": "event_name",
    "timestamp": 1490954061,
    "message_id": "pzkic9-0afezp-fc",
    "recipient": "john.doe@sendpulse.com",
    "sender": "doe.john@sendpulse.com",
    "subject": "hello world" 
  }
]

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

[
  {
    "event": "event_name",
    "timestamp": 1490954061,
    "message_id": "pzkic9-0afezp-fc",
    "recipient": "john.doe@sendpulse.com",
    "sender": "doe.john@sendpulse.com",
    "subject": "hello world" 
  },
  {
    "event": "event_name",
    "timestamp": 1490954062,
    "message_id": "pzkic9-0afezp-fc",
    "recipient": "john.doe@sendpulse.com",
    "sender": "doe.john@sendpulse.com",
    "subject": "hello world" 
  },
  {
    "event": "event_name",
    "timestamp": 1490954063,
    "message_id": "pzkic9-0afezp-fc",
    "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,
    "message_id": "pzkic9-0afezp-fc",
    "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,
    "message_id": "pzkic9-0afezp-fc",
    "recipient": "doe.john@sendpulse.com",
    "event": "undelivered",
    "subject": "utf8_hello_world" 
  }
]

Opened:

 [
  {
    "event": "opened",
    "timestamp": 1490962764,
    "message_id": "pzkic9-0afezp-fc",
    "recipient": "doe.john@sendpulse.com",
    "sender": "john.doe@sendpulse.com",
    "subject": "utf8_hello_world" 
  }
]

Clicked on a link:

[
  {
    "event": "clicked",
    "timestamp": 1490964928,
    "message_id": "pzkic9-0afezp-fc",
    "recipient": "doe.john@sendpulse.com",
    "sender": "john.doe@sendpulse.com",
    "subject": "utf8_hello_world" 
  }
]

Marked as spam:

[
  {
    "event": "spam_by_user",
    "timestamp": 1490964607,
    "message_id": "pzkic9-0afezp-fc",
    "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" 
  }
]

Example of a script that processes a webhook in PHP:

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