API почтового сервиса Selectel
API почтового сервиса Selectel — это программный интерфейс для получения статистики и статусов рассылок, отправленных с помощью почтового сервиса Selectel.
API почтового сервиса Selectel позволяет:
- смотреть статистику рассылок — общий отчет по рассылке, а также отдельные данные по недоставленным письмам и жалобам на спам;
- получать статусы рассылок на webhook и по API.
Авторизация
Чтобы начать работу с API почтового сервиса, подключите сервис, а затем создайте тикет для включения методов API для вашего аккаунта.
В качестве ключа API используйте пароль от SMTP, который вы получили в тикете при подключении сервиса.
Способ передачи ключа зависит от URL, в котором содержится метод:
- https://smtp.mail.selcloud.ru/api/v1/ — в GET-параметре запроса в переменной
key
; - https://smtp.mail.selcloud.ru/api/v2/ — в заголовке
Authorization: {{api_key}}
.
Ограничения
Количество запросов к SMTP — не более 10 000 в минуту. Если лимит превышен, метод будет возвращать ошибку 429.
Среднее время выполнения одного запроса — 500 мс.
Общая статистика рассылки
GET https://smtp.mail.selcloud.ru/api/v1/get_smtp_issue_stat
Параметры запроса
Параметр | Описание | Тип | Обязательный |
---|---|---|---|
key | Ключ API | string | ✓ |
date | Дата, за которую необходимо получить статистику | string (ГГГГ-ММ-ДД) | ✓ |
Пример запроса
https://smtp.mail.selcloud.ru/api/v1/get_smtp_issue_stat?key=XXX&date=2021-04-28
Пример ответа (.json)
Каждая рассылка проходит бесплатную экспресс-проверку сервисом mailvalidator.ru. Из списка получателей исключаются адреса, которые при проверке были определены как:
- несуществующие;
- не являющиеся email-адресами;
- спам-ловушки;
- дубликаты;
- ранее пожаловавшиеся на спам.
{
"status": "ok",
"message": "",
"stat": [
{
"status": "S006",
"date": "2021-04-28",
"stat": {
"total": 4711, // всего принято сообщений
"send_ok": 4707, // успешно доставлено
"send_fail": 4, // недоставлено
"stop": 4, // несуществующие email-адреса, рассылка на них не отправляется
"bad": 0, // не являются email-адресами, рассылка на них не отправляется
"trap": 0, // спам-ловушки, рассылка на них не отправляется
"fbl": 0, // отметили письмо как спам, рассылка на них не отправляется
"dup": 0, // дублирующиеся email-адреса, рассылка на них не отправляется
"gen_ok": 0 // количество писем, сгенерированных для отправки (техническая метрика)
},
"issuen": 66576
}
]
}
Недоставленные
GET https://smtp.mail.selcloud.ru/api/v1/get_stop_report
Параметры запроса
Параметр | Описание | Тип | Обязательный |
---|---|---|---|
key | Ключ API | string | ✓ |
date | Дата, за которую необходимо получить статистику | string (ГГГГ-ММ-ДД) | ✓ |
Пример запроса
https://smtp.mail.selcloud.ru/api/v1/get_stop_report?key=XXX&date=2021-04-15
Пример ответа (.xml)
<?xml version="1.0" ?>
<report>
<item>
<email><![CDATA[ email1@domain.com ]]></email> // email-адрес, на который не получилось доставить письмо
<code>550</code> // код ответа сервера
<message><![CDATA[ 552 5.2.2 Mailbox size limit exceeded ]]></message> // ответ сервера (причина, по которой письмо не было доставлено)
<x_track_id>ххххх</x_track_id> // пользовательский ID письма, равен уникальному значению заголовка X-Track-ID в рассылке
</item>
<item>
<email><![CDATA[ email2@domain.com ]]></email>
<code>550</code>
<message><![CDATA[ 550 Requested action not taken: mailbox unavailable ]]></message>
<x_track_id></x_track_id>
</item>
<item>
...
</item>
</report>
Жалобы на спам
GET https://smtp.mail.selcloud.ru/api/v1/get_fbl_report
Чтобы автоматически отписывать от рассылки пользователей, которые отметили письмо как спам, настройте прием жалоб в postmaster.mail.ru и включите пересылку жалоб на fbl@mail.selcloud.ru.
Параметры запроса
Параметр | Описание | Тип | Обязательный |
---|---|---|---|
key | Ключ API | string | ✓ |
date | Дата, за которую необходимо получить статистику | string (ГГГГ-ММ-ДД) | ✓ |
Пример запроса
https://smtp.mail.selcloud.ru/api/v1/get_stop_report?key=XXX&date=2021-04-15
Пример ответа (.xml)
<?xml version="1.0" ?>
<report>
<item>
<email><![CDATA[ email1@domain.com ]]></email> // email-адрес, с которого поступила жалоба на спам
<domain><![CDATA[ sender-domain1.com ]]></domain> // домен, с которого было отправлено письмо
<x_track_id>ххххх</x_track_id> // пользовательский ID письма, равен уникальному значению заголовка X-Track-ID в рассылке
</item>
<item>
<email><![CDATA[ email2@domain.com ]]></email>
<domain><![CDATA[ sender-domain2.com ]]></domain>
<x_track_id></x_track_id>
</item>
<item>
...
</item>
</report>
Получать статусы рассылок на webhook
Чтобы активировать отправку данных на webhook, создайте тикет, в нем укажите домен отправителя и url для получения данных.
Параметры запроса
Параметр | Описание | Тип | Обязательный |
---|---|---|---|
message_id | ID письма, возвращаемый в smtp-диалоге | string | ✓ |
x_track_id | Пользовательский ID письма, равен уникальному значению заголовка X-Track-ID в рассылке |
string | ✗ |
status | Статус письма | string | ✓ |
created_at | Время события | string | ✓ |
reason | Причина недоставки, передается только для недоставленных писем (параметр status со значением failed) | string | ✗ |
Возможные значения переменной status
Значение | Описание |
---|---|
accepted | Сервер принял письмо к отправке. Если письмо не может быть сразу доставлено, например, ящик переполнен, сервис присвоит ему статус accepted и произведет 10 попыток отправки с интервалом от нескольких часов до нескольких дней. Если письмо не будет доставлено, ему будет присвоен статус failed |
delivered | Письмо доставлено, сервер получателя вернул ответ 250 OK |
failed | Письмо не доставлено, сервер получателя вернул ответ 5XX. Email-адрес добавляется в ваш локальный стоп-лист, следующая отправка на адрес вернет ошибку 550 bounced check filter . Чтобы удалить адрес из стоп-листа, создайте тикет |
fbl | Получатель отметил письмо как спам. Email-адрес добавляется в ваш локальный стоп-лист, следующая отправка на адрес вернет ошибку 550 bounced check filter . Чтобы удалить адрес из стоп-листа, создайте тикет |
unsubscribe | Получатель нажал Отписаться в письме. Email-адрес добавляется в ваш локальный стоп-лист, следующая отправка на адрес вернет ошибку 550 bounced check filter . Чтобы удалить адрес из стоп-листа, создайте тикет |
Пример запроса
В ответ ожидаем статус 200 OK
, тело пустое.
{
"status": "ok",
"messages": [
{
"message_id": "A",
"x_track_id": "foo",
"status": "accepted",
"created_at": 1615409261
},
{
"message_id": "B",
"status": "failed",
"reason": "bad domain mx",
"created_at": 1615409261
}
]
}
Получить все статусы рассылок по API
GET https://smtp.mail.selcloud.ru/api/v2/issue/ext_status
Параметры запроса
Параметр | Описание | Тип | Обязательный |
---|---|---|---|
message_id | ID письма, возвращаемый в smtp-диалоге. Максимум 50 message_id в одном запросе |
string | ✓ |
x_track_id | Пользовательский ID письма, равен уникальному значению заголовка X-Track-ID в рассылке |
string | ✗ |
Пример запроса
https://smtp.mail.selcloud.ru/api/v2/issue/ext_status?message_id=A&x_track_id=B
Пример ответа (.json)
{
"status": "ok",
"messages": [
{
"message_id": "A",
"ext_status": [
{
"status": "accepted",
"created_at": 1615409250
},
{
"status": "delivered",
"created_at": 1615409250
},
{
"status": "failed",
"created_at": 1615409250,
"reason": "bad email"
},
{
"status": "not_found",
"created_at": 1615409250
},
{
"status": "fbl",
"created_at": 1615409255
},
{
"status": "unsubscribe",
"created_at": 1615409261
},
],
},
{
"message_id": "foo",
"x_track_id": "B",
"ext_status": [
{
"status": "delivered",
"created_at": 1615409250
}
],
}
],
}
Параметры ответа .json
Параметр | Описание | Тип | Обязательный |
---|---|---|---|
status | Статус API — success или error | string | ✓ |
error | Причина ошибки | string | ✗ |
messages | Массив писем | json-массив | ✗ |
Параметры массива messages
Параметр | Описание | Тип | Обязательный |
---|---|---|---|
message_id | ID письма, возвращаемый в smtp-диалоге | string | ✓ |
x_track_id | Пользовательский ID письма, равен уникальному значению заголовка X-Track-ID в рассылке |
string | ✗ |
ext_status | Массив статусов письма | json-массив | ✓ |
Параметры массива ext_status
Параметр | Описание | Тип | Обязательный |
---|---|---|---|
status | Статус письма | string | ✓ |
created_at | Время события (time stamp) | string | ✓ |
reason | Причина недоставки, передается только для недоставленных писем (переменная status со значением failed ) |
string | ✗ |
Возможные значения переменной status
Значение | Описание |
---|---|
accepted | Сервер принял письмо к отправке. Если письмо не может быть сразу доставлено, например, ящик переполнен, сервис присвоит ему статус accepted и произведет 10 попыток отправки с интервалом от нескольких часов до нескольких дней. Если письмо не будет доставлено, ему будет присвоен статус failed |
delivered | Письмо доставлено, сервер получателя вернул ответ 250 OK |
failed | Письмо не доставлено, сервер получателя вернул ответ 5XX. Email-адрес добавляется в ваш локальный стоп-лист, следующая отправка на адрес вернет ошибку 550 bounced check filter . Чтобы удалить адрес из стоп-листа, создайте тикет |
not_found | Письмо с таким ID не найдено |
fbl | Получатель отметил письмо как спам. Email-адрес добавляется в ваш локальный стоп-лист, следующая отправка на адрес вернет ошибку 550 bounced check filter . Чтобы удалить адрес из стоп-листа, создайте тикет |
unsubscribe | Получатель нажал Отписаться в письме. Email-адрес добавляется в ваш локальный стоп-лист, следующая отправка на адрес вернет ошибку 550 bounced check filter . Чтобы удалить адрес из стоп-листа, создайте тикет |