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 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 (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 in which the key is the name of the file, and the value is the contents of the file (optional)
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 (optional)

*Note: You can use parameter html and text for sending template directly in this request.

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

Example to send 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 to send 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

 

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": "cd66a0dcdcef5bdec76316e87a2407e4", //use in other methotd to retrieve more info about this specific letter
  "sender": "JohnDoe@test.com",
  "message_id": "1267371103", //used in webhooks
  "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": "cd66a0dcdcef5bdec76316e87a2407e4",
  "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 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

A sample response:

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

 

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

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

Пример ответа:

[  
   {  
      "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 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

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);
?>