Отправить письмо

Для того, чтобы отправить письмо, необходимо отправить POST запрос по ссылке

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

Параметры запроса:

email сериализованный объект с данными письма

Параметры массива письма:

html html версия письма, закодированная в base64
text текстовая версия письма
template id идентификатор нужного шаблона загруженного в сервис. Получить идентификаторы шаблона можно при помощи метода, описанного тут (можно использовать параметры ответа real_id или id)
variables включает названия и значения переменных  вида  {"название переменной": "значение переменной"
subject тема письма
from массив с именем и адресом отправителя
to массив получателей
attachments массив, в котором ключ - это имя файла, а значение - содержание файла
attachments_binary массив, в котором ключ - это имя файла, а значение - содержание файла,  закодированная в base64

 

Пример с отправкой своего шаблона:

{
  "email": {
    "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"
    }
  }
}

Пример  отправки письма по шаблону добавленный в сервис c кастомными переменными:

{
  "email": {
    "subject": "Test",
    "template": {
      "id": 123456,
      "variables": {
        "name": "Владислав",
        "code": "123456"
      }
    },
    "from": {
      "name": "Mike",
      "email": "mike.johnson@domain.com"
    },
    "to": [
      {
        "email": "recipient1@example.com",
        "name": "Владислав"
      }
    ]
  }
}

В данном примере вместо параметров «html» и «text» используется параметр «template»

В случае успеха сервер вернет JSON строку с result = true

 

Получить список писем

Для получения списка всех отправленных писем, нужно сделать GET запрос по ссылке

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

Параметры запроса (необязательные):

limit количество записей
offset смещение для выборки
from начальная дата для выборки
to максимальная дата для выборки
sender отправитель
recipient получатель
country если "off", то страна не будет указана в ответе

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

   {
        "id": "cd66a0dcdcef5bdec76316e87a2407e4", //используется в других методах апи для получения более детальной информации об этом определенном письме
        "message_id": 1375180903, //используется в получаемых webhooks
        "sender": "tech@yourdream.com",
        "total_size": 1175,
        "sender_ip": "173.212.198.158",
        "smtp_answer_code": 250,
        "smtp_answer_code_explain": "Delivered",
        "smtp_answer_subcode": "",
        "smtp_answer_data": "anna-maria@gmail.com   H=gmail-smtp-in.l.google.com [64.233.165.27] X=TLSv1.2:ECDHE-RSA-CHACHA20-POLY1305:256 CV=yes K C=\"250 2.0.0 OK s129-v6si13409556lja.72 - gsmtp\"",
        "used_ip": "78.41.200.153",
        "recipient": "anna-maria@gmail.com",
        "subject": "Template test",
        "send_date": "2018-10-10 12:54:45",
        "tracking": {
            "click": 1,
            "open": 1,
            "link": [
                {
                    "url": "wikia.com",
                    "browser": "Firefox 64.0",
                    "os": "Linux",
                    "screen_resolution": "1920x1080",
                    "ip": "77.222.152.150",
                    "action_date": "2018-12-12 11:54:55"
                }
            ],
            "client_info": [
                {
                    "browser": "Firefox 11.0viaggpht.comGoog",
                    "os": "Windows",
                    "ip": "66.102.9.17",
                    "action_date": "2018-12-12 11:54:54"
                }
            ]
        }
    }
 

Получить общее количество отправленных писем

Нужно сделать GET запрос по ссылке

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

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

{
    "total": 25408
}
 

Получить информацию по конкретному письму

Для получения информации по конкретному письму, нужно сделать GET запрос по ссылке

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

Параметры запроса:

email массив с данными емейла

Параметры массива emails:

id идентификатор письма

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

{
  "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": "Ukraine",
	"action_date": "2013-09-30 11:27:49"
      }
    ]
  }
} 
 

Получить список баунсов за сутки

Для получения списка банусов, нужно сделать GET запрос по ссылке

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

Параметры запроса:

date дата, на которую нужно получить список баунсов. Формат даты YYYY-MM-DD
limit количество записей, которое нужно взять
offset смещение

Пример: https://api.sendpulse.com/smtp/bounces/day?limit=10&offset=20 - получит 10 записей начиная с 20

Баунсы получаются только за сутки, начиная с текущего момента. Например сегодня - 2016-04-28 14:34:00, следовательно записи будут получены за период с 2016-04-27 14:34:00 по 2016-04-28 14:34:00

Пример ответа баунсов на определенный день:

{
    "total": 2,
    "emails": [
        {
            "email_to": "gverb2016@yandex.ru",
            "sender": "no-reply@boomstream.com",
            "send_date": "2019-03-25 19:05:02",
            "subject": "[Boomstream] Покупка доступа к видео контенту",
            "smtp_answer_code": 550,
            "smtp_answer_subcode": "5.1.1",
            "smtp_answer_data": "gverb2016@yandex.ru   H=mx.yandex.ru [93.158.134.89] X=TLSv1.2:ECDHE-RSA-AES128-GCM-SHA256:128 CV=yes: SMTP error from remote mail server after RCPT TO:<gverb2016@yandex.ru>: 550 5.7.1 No such user!"
        },
        {
            "email_to": "1934a1a621@mailboxy.fun",
            "sender": "no-reply@boomstream.com",
            "send_date": "2019-03-25 15:58:00",
            "subject": "Your video files has been deleted",
            "smtp_answer_code": 552,
            "smtp_answer_subcode": "5.7.1",
            "smtp_answer_data": "1934a1a621@mailboxy.fun   H=mx5.mailboxy.fun [165.227.245.168] X=TLSv1.2:ECDHE-RSA-AES128-GCM-SHA256:128 CV=no: SMTP error from remote mail server after RCPT TO:<1934a1a621@mailboxy.fun>: 552 Mailbox limit exeeded for this email address"
        }
    ],
    "request_limit": 1000,
    "found": 2
}
 

Общее количество баунсов

Нужно сделать GET запрос по ссылке

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

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

{
    "total": 3
}
 

Отписать получателя

Для того, чтобы отписать подписчика от получения рассылки, нужно сделать POST запрос по ссылке

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

Параметры запроса:

emails сериализованный массив адресов

Пример структуры массива emails

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

В случае успеха сервер вернет JSON строку с result=true

 

Удалить из списка отписавшихся

Для удаления подписчика, который отказался получать рассылку, из списка отписавшихся, нужно сделать DELETE запрос по ссылке

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

Параметры запроса:

emails сериализованный массив адресов ["badUser1@mailserver.com","badUser2@mailserver.com"]

В случае успеха сервер вернет JSON строку с result = true

 

Получить список отписавшихся

Для получения списка отписавшихся, нужно сделать GET запрос по ссылке

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

Параметры запроса:

date дата, на которую нужно получить список отписавшихся. Формат даты YYYY-MM-DD
limit количество записей, которое нужно взять
offset смещение

Пример: https://api.sendpulse.com/smtp/unsubscribe?limit=10&offset=20" - получит 10 записей начиная с 20 

Если указано date, то выгрузка будет именно за 1 день
Пример вызова с датой: 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"
   }
]
 

Получить список IP-адресов отправителя

Для того, чтобы получить список IP-адресов отправителя, нужно отправить GET запрос по ссылке

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

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

[
  "127.0.0.1"
]
 

Получить список разрешенных доменов

Чтобы получить список разрешенных доменов, необходимо отправить GET запрос по ссылке

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

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

[
  "@sendpulse.com"
]
 

Добавить домен

Для добавления домена, нужно отправить POST запрос по ссылке

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

Параметры запроса:

email адрес отправителя

В случае успеха сервер вернет JSON строку с result = true

 

Верификация нового домена

Для того, чтобы активировать и подтвердить новый домен, необходимо отправить GET запрос по ссылкe

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

В случае успеха сервер вернет JSON строку с result = true

Дополнительно, на указанный почтовый ящик будет отправлено письмо с кодом для верификации нового домена.

 

WebHooks

Webhook — механизм получения уведомлений об определённых событиях.

Для включения webhook зайдите в раздел "Настройки аккаунта" -> "API" и нажмите на кнопку "Создать webhook".

Далее укажите URL, на который будут отправляться уведомления, и какие именно события нужно передавать.

Список событий, по которым срабатывает webhook в сервисе SMTP, относительно отправки письма:

  • Доставлено
  • Не доставлено
  • Открыто 
  • Переход по ссылке
  • Отмечено как спам
  • Отписался

При срабатывании webhook, мы отсылаем на указанный клиентом url данные

  • тип данных: JSON
  • тип запроса: POST

Данные отсылаются каждую минуту или же при достижении лимита в 100 событий.

Основной формат пересылаемых данных:

[
  {
    "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": 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" 
  },
]

Форматы запросов, в зависимости от события:

Доставлено

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

Не доставлено

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

Открыто

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

Переход по ссылке

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

Отмечено как спам

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

Отписался

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

Пример скрипта, принимающего запрос, на языке PHP

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