Уведомления о доставке писем
Чтобы получать уведомления о доставке писем, необходимо создать конфигурацию и привязать ее к адресу.
Типы уведомлений
Уведомление о приеме письма сервисом
Приходит, когда Yandex Cloud Postbox принял письмо в обработку.
Пример уведомления:
{
"eventType": "Send",
"mail": {
"timestamp": "2024-04-25T18:05:04.84108+03:00",
"messageId": "vgAyRUls8591ybPKeH-Ov",
"identityId": "nWh0ZpVEgnKO1bghxydXn",
"commonHeaders": {
"from":[ "User <user@example.com>" ],
"date":"Thu, 27 Jun 2024 14:05:45 +0000",
"to":[ "Recipient Name <recipient@example.com>" ],
"messageId":"vgAyRUls8591ybPKeH-Ov",
"subject":"Message sent using Yandex Cloud Postbox"
}
},
"send": { },
"eventId": "vgAyRUls8591ybPKeH-Ov:0"
}
Уведомление о доставке письма
Приходит, когда получателю отправили письмо и его почтовый клиент подтвердил прием письма.
Пример уведомления:
{
"eventType": "Delivery",
"mail": {
"timestamp": "2024-04-25T18:05:04.84108+03:00",
"messageId": "vgAyRUls8591ybPKeH-Ov",
"identityId": "nWh0ZpVEgnKO1bghxydXn",
"commonHeaders": {
"from":[ "User <user@example.com>" ],
"date":"Thu, 27 Jun 2024 14:05:45 +0000",
"to":[ "Recipient Name <recipient@example.com>" ],
"messageId":"vgAyRUls8591ybPKeH-Ov",
"subject":"Message sent using Yandex Cloud Postbox"
}
},
"bounce": null,
"delivery": {
"timestamp": "2024-04-25T18:05:14.84107+03:00",
"processingTimeMillis": 9999,
"recipients": [
"abc@example.com"
]
},
"eventId": "ce3uqnS9pzQBMsnaAbrT_:0"
}
Уведомление о том, что письмо не доставлено
Приходит, когда почтовый клиент получателя на попытку доставки отвечает ошибкой, которую Yandex Cloud Postbox считает не требующей повторной попытки доставки, или адрес получателя находится в стоп-листе.
Пример уведомления:
{
"eventType": "Bounce",
"mail": {
"timestamp": "2024-04-25T18:08:04.933666+03:00",
"messageId": "QA_JPkU2fkpIWdkxAOASH",
"identityId": "ZtYk0rrjN87m-Ovxjte1G",
"commonHeaders": {
"from":[ "User <user@example.com>" ],
"date":"Thu, 27 Jun 2024 14:05:45 +0000",
"to":[ "Recipient Name <recipient@example.com>" ],
"messageId":"QA_JPkU2fkpIWdkxAOASH",
"subject":"Message sent using Yandex Cloud Postbox"
}
},
"bounce": {
"bounceType": "Permanent",
"bounceSubType": "Undetermined",
"bouncedRecipients": [
{
"emailAddress": "abc@example.com",
"action": "failed",
"status": "5.7.1",
"diagnosticCode": "Other"
}
],
"timestamp": "2024-04-25T18:08:04.973666+03:00",
},
"delivery": null,
"eventId": "jdMtnVniDeHqlQX8ygwEX:0"
}
Формат уведомлений
Уведомление записывается в поток данных Yandex Data Streams в формате JSON. Последовательность и набор полей могут отличаться от описанных ниже.
Основной объект
Название | Тип | Описание |
---|---|---|
notificationType |
Строка | Тип уведомления. Возможные значения: Bounce , Delivery , Send . |
mail |
Объект Mail | Объект, который содержит общую информацию об отправленном письме. |
bounce |
Объект Bounce | Объект, который содержит информацию о том, что письмо не доставлено. Обязателен, если notificationType — Bounce , иначе отсутствует. |
delivery |
Объект Delivery | Объект, который содержит информацию о доставке письма отдельному получателю. Обязателен, если notificationType — Delivery , иначе отсутствует. |
eventId |
Строка | Уникальный идентификатор события. |
Объект Mail
Название | Тип | Описание |
---|---|---|
timestamp |
Строка | Дата в формате RFC 33392006-01-02T15:04:05Z07:00 ). Время, когда письмо было принято Yandex Cloud Postbox. |
messageId |
Строка | Уникальный идентификатор письма. У одного письма может быть несколько получателей. Выдается Yandex Cloud Postbox при приеме письма в обработку. |
identityId |
Строка | Идентификатор адреса Yandex Cloud Postbox, который используется при отправке письма. |
commonHeaders |
Объект CommonHeaders | Объект, который содержит основные заголовки письма. |
Объект CommonHeaders
Название | Тип | Описание |
---|---|---|
from |
Массив строк | Содержимое заголовка From , разбитое по адресам. |
to |
Массив строк | Содержимое заголовка To , разбитое по адресам. |
subject |
Строка | Содержимое заголовка Subject . |
date |
Строка | Содержимое заголовка Date . |
messageId |
Строка | Уникальный идентификатор письма. Выдается Yandex Cloud Postbox при приеме письма. |
Объект Send
Пустой объект.
Объект Bounce
Название | Тип | Описание |
---|---|---|
bounceType |
Строка | Тип ошибки. Возможные значения:
|
bounceSubType |
Строка | Подтип ошибки. Возможные значения:
|
bouncedRecipients |
Массив объектов BounceRecipient | Массив, который содержит информацию о получателе письма и связанной с ним ошибке доставки, если она была. |
timestamp |
Строка | Дата в формате RFC 33392006-01-02T15:04:05Z07:00 ). Время, когда получена ошибка от почтового клиента получателя. |
Объект BounceRecipent
Название | Тип | Описание |
---|---|---|
emailAddress |
Строка | Электронный адрес получателя. |
action |
Строка | Необязательное поле. Результат отправки. Возможные значения: failed . |
status |
Строка | Необязательное поле. SMTP-код ответа. |
diagnosticCode |
Строка | Необязательное поле. Расширенный текст ошибки. Может содержать текст ошибки от почтового клиента получателя. |
Объект Delivery
Название | Тип | Описание |
---|---|---|
timestamp |
Строка | Дата в формате RFC 33392006-01-02T15:04:05Z07:00 ). Время, когда Yandex Cloud Postbox отправил письмо и получил успешный ответ от почтового клиента получателя. |
processingTimeMillis |
Целое число | Время, которое потребовалось на обработку письма в миллисекундах. |
recipients |
Массив строк | Адреса получателей. |
Уровень качества обслуживания (QoS)
При доставке уведомлений сервис поддерживает уровень качества обслуживания QoS 1: At least once
, поэтому возможна повторная отправка уведомлений. У одинаковых уведомлений совпадает eventId
.
Если к адресу привязана конфигурация, в которую добавлены несколько подписок, по каждому назначению будет приходить отдельное уведомление.
Пример работы
Вы отправили письмо двум получателям — user1@example.com
и user2@other.example.com
. Yandex Cloud Postbox отправил письмо обоим получателям отдельно.
Почтовый клиент получателя user1@example.com
принял письмо. Почтовый клиент получателя user2@other.example.com
после первой попытки отправить письмо вернул ошибку, а после второй — не принял письмо и ответил, что данный пользователь не найден.
В таком случае вы получите три уведомления:
- уведомление о том, что Yandex Cloud Postbox принял письмо в обработку;
- уведомление о доставке письма получателю
user1@example.com
; - уведомление о том, что письмо не доставлено получателю
user2@other.example.com
, с информацией об ошибке. Уведомление придет после второй попытки отправить письмо.
Так как почтовый клиент ответил, что получатель user2@other.example.com
не найден, его адрес временно попадет в стоп-лист. Прежде чем пытаться отправлять письмо на такой адрес повторно, необходимо подождать некоторое время, иначе придет уведомление о том, что письмо не доставлено, потому что получатель находится в стоп-листе.