- Отправить письмо
- Получить список писем
- Получить общее количество отправленных писем
- Получить информацию по конкретному письму
- Получить список баунсов за сутки
- Общее количество баунсов
- Отписать получателя
- Удалить из списка отписавшихся
- Получить список отписавшихся
- Получить список IP-адресов отправителя
- Получить список разрешенных доменов
- Добавить домен
- Верификация нового домена
- WebHooks
Отправить письмо
Для того, чтобы отправить письмо, необходимо отправить POST запрос по ссылке
https://mailer-api.i.bizml.ru/smtp/emails |
Параметры запроса:
сериализованный массив с данными письма |
Параметры массива письма:
html* | html версия письма, закодированная в base64 | |
text* | текстовая версия письма | |
template* | id | идентификатор нужного шаблона загруженного в сервис. Получить ид шаблона можно при помощи метода, описанного тут (можно использовать параметры ответа real_id или id ) |
variables | включает названия и значения системных переменных вида ("название переменной": "значение переменной") | |
subject | тема письма | |
from | массив с именем и адресом отправителя | |
to | массив получателей | |
attachments |
серриализованный объект, в котором ключ - это имя файла, а значение - содержание файла (необязательный параметр) {"название":"содержимое"} |
|
attachments_binary |
серриализованный объект, в котором ключ - это имя файла, а значение - содержание файла, закодированная в base64 (необязательный параметр) |
*Примечание, чтобы отправить свой шаблон напрямую в запросе, используйте параметры html
и text
;
второй вариант отправки сообщения - использовать параметр template
для отправки статичного шаблона, загруженный ранее в сервис и передавать только значения к переменным (заданным ранее в шаблоне) через параметр variables
.
Пример с отправкой своего шаблона:
{
"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"
}
]
}
}
Пример отправки письма по шаблону добавленный в сервис 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 и id
письма.
Пример ответа:
{
"result": true,
"id": "pzkic9-0afezp-fc"
}
Получить список писем
Для получения списка всех отправленных писем, нужно сделать GET запрос по ссылке
https://mailer-api.i.bizml.ru/smtp/emails |
Параметры запроса (необязательные):
limit | количество записей |
offset | смещение для выборки |
from | начальная дата для выборки |
to | максимальная дата для выборки |
sender | отправитель |
recipient | получатель |
country | если "off", то страна не будет указана в ответе |
Пример ответа:
{
"id": "pzkic9-0afezp-fc"
"message_id": 1375180903
"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://mailer-api.i.bizml.ru/smtp/emails/total |
Пример ответа:
{
"total": 25408
}
Получить информацию по конкретному письму
Для получения информации по конкретному письму, нужно сделать GET запрос по ссылке
https://mailer-api.i.bizml.ru/smtp/emails/{id} |
Параметры запроса:
id | идентификатор письма |
Пример ответа:
{
"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": "Sendbox :: 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"
}
]
}
}
Получить информацию по списку писем
Для получения информации, нужно сделать POST запрос по ссылке
https://mailer-api.i.bizml.ru/smtp/emails/info |
Параметры запроса:
emails |
массив с идентификаторами письма, максимальное количество адресов за раз - 500 |
Получить список баунсов за сутки
Для получения списка баунсов, нужно сделать GET запрос по ссылке
https://mailer-api.i.bizml.ru/smtp/bounces/day |
Параметры запроса:
date | дата, на которую нужно получить список баунсов. Формат даты YYYY-MM-DD |
limit | количество записей, которое нужно взять |
offset | смещение |
Пример: https://mailer-api.i.bizml.ru/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://mailer-api.i.bizml.ru/smtp/bounces/day/total |
Привет ответа:
{ |
Отписать получателя
Для того, чтобы отписать подписчика от получения рассылки, нужно сделать POST запрос по ссылке
https://mailer-api.i.bizml.ru/smtp/unsubscribe |
Параметры запроса:
emails | сериализованный массив адресов |
Пример структуры массива emails
[
{
"email": "badUser1@mailserver.com",
"comment": "comment1"
},
{
"email": "badUser2@mailserver.com",
"comment": "comment2"
}
]
В случае успеха сервер вернет JSON строку с result=true
Удалить из списка отписавшихся
Для удаления подписчика, который отказался получать рассылку, из списка отписавшихся, нужно сделать DELETE запрос по ссылке
https://mailer-api.i.bizml.ru/smtp/unsubscribe |
Параметры запроса:
emails |
сериализованный массив адресов ["badUser1@mailserver.com","badUser2@mailserver.com"] |
В случае успеха сервер вернет JSON строку с result = true
Получить список отписавшихся
Для получения списка отписавшихся, нужно сделать GET запрос по ссылке
https://mailer-api.i.bizml.ru/smtp/unsubscribe |
Параметры запроса:
date | дата, на которую нужно получить список отписавшихся. Формат даты YYYY-MM-DD |
limit | количество записей, которое нужно взять |
offset | смещение |
Пример: https://mailer-api.i.bizml.ru/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://mailer-api.i.bizml.ru/smtp/ips |
Пример ответа:
[
"127.0.0.1"
]
Получить список разрешенных доменов
Чтобы получить список разрешенных доменов, необходимо отправить GET запрос по ссылке
https://mailer-api.i.bizml.ru/smtp/domains |
Пример ответа:
[
"@mail.ru"
]
Добавить домен
Для добавления домена, нужно отправить POST запрос по ссылке
https://mailer-api.i.bizml.ru/smtp/domains |
Параметры запроса:
адрес отправителя |
В случае успеха сервер вернет JSON строку с result = true
Верификация нового домена
Для того, чтобы активировать и подтвердить новый домен, необходимо отправить GET запрос по ссылкe
https://mailer-api.i.bizml.ru/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@send-box.ru",
"sender": "doe.john@send-box.ru",
"subject": "hello world"
}
]
Если событий несколько, то они будут сгруппированы в один или несколько запросов
[
{
"event": "event_name",
"timestamp": 1490954061,
"message_id": 1145317311,
"recipient": "john.doe@send-box.ru",
"sender": "doe.john@send-box.ru",
"subject": "hello world"
},
{
"event": "event_name",
"timestamp": 1490954062,
"message_id": 1145317311,
"recipient": "john.doe@send-box.ru",
"sender": "doe.john@send-box.ru",
"subject": "hello world"
},
{
"event": "event_name",
"timestamp": 1490954063,
"message_id": 1145317311,
"recipient": "john.doe@send-box.ru",
"sender": "doe.john@send-box.ru",
"subject": "utf8_hello_world"
},
]
Форматы запросов, в зависимости от события:
Доставлено
[
{
"smtp_server_response_code": "250",
"smtp_server_response_subcode": "",
"sender": "john.doe@send-box.ru",
"smtp_server_response": "custom_text_response_from_recipients_server",
"timestamp": 1490953933,
"message_id": 1145317311,
"recipient": "doe.john@send-box.ru",
"event": "delivered",
"subject": "utf8_hello_world"
}
]
Не доставлено
[
{
"smtp_server_response_code": "554",
"smtp_server_response_subcode": "5.7.1",
"sender": "john.doe@send-box.ru",
"smtp_server_response": "custom_text_response_from_recipients_server",
"timestamp": 1490956117,
"message_id": 1145317311,
"recipient": "doe.john@send-box.ru",
"event": "undelivered",
"subject": "utf8_hello_world"
}
]
Открыто
[
{
"event": "opened",
"timestamp": 1490962764,
"message_id": 1145317311,
"recipient": "doe.john@send-box.ru",
"sender": "john.doe@send-box.ru",
"subject": "utf8_hello_world"
}
]
Переход по ссылке
[
{
"event": "clicked",
"timestamp": 1490964928,
"recipient": "doe.john@send-box.ru",
"sender": "john.doe@send-box.ru",
"subject": "utf8_hello_world"
}
]
Отмечено как спам
[
{
"event": "spam_by_user",
"timestamp": 1490964607,
"message_id": 1145317311,
"recipient": "doe.john@send-box.ru",
"sender": "john.doe@send-box.ru",
"subject": "utf8_hello_world"
}
]
Отписался
[
{
"event": "unsubscribed",
"recipient": "john.doe@send-box.ru",
"sender": "doe.john@send-box.ru",
"subject": "hello world"
}
]
Пример скрипта, принимающего запрос, на языке PHP
<?php
$json_string = file_get_contents('php://input');
$data_array = json_decode($json_string, true);
?>