SMTP Service API

  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 array with email data

Email array parameters:

html HTML version of the email, encoded in base64
text Text version of the email
template
id ID of the template uploaded in the service. Use this method to get the template ID.
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 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

 

Example of the email address array structure used to send a custom template:

{
   "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"
      }
   ],
    "attachments": {
      "text.txt": "this is simple txt file"
   }
}

Example of the email address array structure used to send a system template:

{
   "subject": "Test",
   "template": {
      "id": 5924441,
      "variables": {
         "ec_es_email_sender_company": "ec es email sender company value",
         "ec_es_email_sender_address": "ec es email sender address value",
         "current_year": "2018 curr year"
      }
   },
   "from": {
      "name": "Mike",
      "email": "mike.johnson@domain.com"
   },
   "to": [
      {
         "email": "recipient1@example.com",
         "name": "Recipient1 name"
      }
   ]
}

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

 

 

Retrieving a list of emails

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
country when "off", country will not be specified

 

A sample response:

 

{
  "id": "123123",
  "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 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": "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

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

 

Deleting 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

 

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

 

[
  "@gmail.com"
]
 

 Retrieving a list of unsubscribed

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

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

 

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

WebHooks is a mechanism used to receive 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.

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

  • Delivered
  • Not delivered
  • Opened
  • Click through
  • Marked 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 event count reaches 100.

The main data format for a request:

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

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

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

Open

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

Click on a link

[
  {
    "event": "clicked",
    "timestamp": 1490964928,
    "message_id": 1145317311,
    "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": 1145317311,
    "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);
?>