API почтового сервиса Selectel

API почтового сервиса Selectel — это программный интерфейс для получения статистики и статусов рассылок, отправленных с помощью почтового сервиса Selectel.

API почтового сервиса Selectel позволяет:

  • смотреть статистику рассылок — общий отчет по рассылке, а также отдельные данные по недоставленным письмам и жалобам на спам;
  • получать статусы рассылок на webhook и по API.

Авторизация

Чтобы начать работу с API почтового сервиса, подключите сервис, а затем создайте тикет для включения методов API для вашего аккаунта.

В качестве ключа API используйте пароль от SMTP, который вы получили в тикете при подключении сервиса.

Способ передачи ключа зависит от URL, в котором содержится метод:

Ограничения

Количество запросов к 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)

{
    "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. Чтобы удалить адрес из стоп-листа, используйте API-метод
fbl Получатель отметил письмо как спам. Email-адрес добавляется в ваш локальный стоп-лист, следующая отправка на адрес вернет ошибку 550 bounced check filter. Чтобы удалить адрес из стоп-листа, используйте API-метод
unsubscribe Получатель нажал Отписаться в письме. Email-адрес добавляется в ваш локальный стоп-лист, следующая отправка на адрес вернет ошибку 550 bounced check filter. Чтобы удалить адрес из стоп-листа, используйте API-метод

Пример запроса

В ответ ожидаем статус 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. Чтобы удалить адрес из стоп-листа, используйте API-метод
not_found Письмо с таким ID не найдено
fbl Получатель отметил письмо как спам. Email-адрес добавляется в ваш локальный стоп-лист, следующая отправка на адрес вернет ошибку 550 bounced check filter. Чтобы удалить адрес из стоп-листа, используйте API-метод
unsubscribe Получатель нажал Отписаться в письме. Email-адрес добавляется в ваш локальный стоп-лист, следующая отправка на адрес вернет ошибку 550 bounced check filter. Чтобы удалить адрес из стоп-листа, используйте API-метод

Удалить email-адрес из стоп-листа

POST https://smtp.mail.selcloud.ru/api/v2/stop-list/remove

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

Параметр Описание Тип Обязательный
mail_from Email-адрес отправителя string
email Email-адрес, который нужно удалить из стоп-листа string

Пример запроса

https://smtp.mail.selcloud.ru/api/v2/stop-list/remove?mail_from=info@domain.com&email=example@mail.com

Параметры ответа .json

Параметр Описание Тип Обязательный
status Статус API — ok или error string
message Причина ошибки при статусе error string