Уведомления об операциях с письмами

Статья создана

Yandex Cloud

Улучшена

ilya

Обновлена 12 августа 2026 г.

Открыть в Markdown

Типы уведомлений
Формат уведомлений
Системные теги
Уровень качества обслуживания (QoS)
Пример работы

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

Типы уведомлений

Уведомление о приеме письма сервисом

Приходит, когда 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"
        },
        "headers": [
            { "name": "From", "value": "User <user@example.com>" },
            { "name": "To", "value": "Recipient Name <recipient@example.com>" },
            { "name": "Subject", "value": "Message sent using Yandex Cloud Postbox" },
            { "name": "Date", "value": "Thu, 27 Jun 2024 14:05:45 +0000" },
            { "name": "Content-Type", "value": "text/plain; charset=UTF-8" },
            { "name": "X-Campaign-Id", "value": "summer-sale-2024" }
        ],
        "tags": {
            "ses:configuration-set": [
                "kXVCt2Vd4dvm3MDvpc5Ml"
            ],
            "ses:from-domain": [
                "example.com"
            ],
            "ses:source-ip": [
               "123.123.123.123"
            ],
            "key1": [
                "value1"
            ],
            "key2": [
                "value2"
            ]
        }
    },
    "send": {  },
    "eventId": "vgAyRUls8591ybPKeH-Ov:0"
}

Уведомление об ошибке рендеринга письма

Приходит, когда Yandex Cloud Postbox принял письмо в обработку, но позже при рендеринге шаблона возникла ошибка.

Пример уведомления:

{
    "eventType": "Rendering Failure",
    "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"
        },
        "headers": [
            { "name": "From", "value": "User <user@example.com>" },
            { "name": "To", "value": "Recipient Name <recipient@example.com>" },
            { "name": "Subject", "value": "Message sent using Yandex Cloud Postbox" },
            { "name": "Date", "value": "Thu, 27 Jun 2024 14:05:45 +0000" },
            { "name": "Content-Type", "value": "text/plain; charset=UTF-8" },
            { "name": "X-Campaign-Id", "value": "summer-sale-2024" }
        ],
        "tags": {
            "ses:configuration-set": [
                "kXVCt2Vd4dvm3MDvpc5Ml"
            ],
            "ses:from-domain": [
                "example.com"
            ],
            "ses:source-ip": [
               "123.123.123.123"
            ],
            "key1": [
                "value1"
            ],
            "key2": [
                "value2"
            ]
        }
    },
    "failure": {
        "errorMessage": "template variable {{name}} is missing"
    },
    "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"
        },
        "headers": [
            { "name": "From", "value": "User <user@example.com>" },
            { "name": "To", "value": "Recipient Name <recipient@example.com>" },
            { "name": "Subject", "value": "Message sent using Yandex Cloud Postbox" },
            { "name": "Date", "value": "Thu, 27 Jun 2024 14:05:45 +0000" },
            { "name": "Content-Type", "value": "text/plain; charset=UTF-8" },
            { "name": "X-Campaign-Id", "value": "summer-sale-2024" }
        ],
        "tags": {
            "ses:configuration-set": [
               "kXVCt2Vd4dvm3MDvpc5Ml"
            ],
            "ses:from-domain": [
                "example.com"
            ],
            "ses:source-ip": [
                "123.123.123.123"
            ],
            "ses:outgoing-tls-cipher": [
                "AES_128_GCM_SHA256"
            ],
            "ses:outgoing-tls-version": [
                "TLSv1.3"
            ],
            "ses:outgoing-ip": [
                "51.250.56.125"
            ],
            "key1": [
                "value1"
            ],
            "key2": [
                "value2"
            ]
        }
    },
    "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"
        },
        "headers": [
            { "name": "From", "value": "User <user@example.com>" },
            { "name": "To", "value": "Recipient Name <recipient@example.com>" },
            { "name": "Subject", "value": "Message sent using Yandex Cloud Postbox" },
            { "name": "Date", "value": "Thu, 27 Jun 2024 14:05:45 +0000" },
            { "name": "Content-Type", "value": "text/plain; charset=UTF-8" },
            { "name": "X-Campaign-Id", "value": "summer-sale-2024" }
        ],
        "tags": {
            "ses:configuration-set": [
                "kXVCt2Vd4dvm3MDvpc5Ml"
            ],
            "ses:from-domain": [
                "example.com"
            ],
            "ses:source-ip": [
                "123.123.123.123"
            ],
            "key1": [
                "value1"
            ],
            "key2": [
                "value2"
            ]
        }
    },
    "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",
        "dialAttempts": [
            {
                "mxHost": "mx.example.com.",
                "ip": "192.0.2.1",
                "reason": "Smtp",
                "error": "read response error: 554 5.7.1 Message rejected under suspicion of SPAM",
                "negotiatedTls": "TLSv1.3"
            }
        ]
    },
    "eventId": "jdMtnVniDeHqlQX8ygwEX:0"
}

Уведомление о том, что письмо открыто

Приходит, когда получатель открыл письмо.

Пример уведомления:

{
    "eventType": "Open",
    "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"
        },
        "headers": [
            { "name": "From", "value": "User <user@example.com>" },
            { "name": "To", "value": "Recipient Name <recipient@example.com>" },
            { "name": "Subject", "value": "Message sent using Yandex Cloud Postbox" },
            { "name": "Date", "value": "Thu, 27 Jun 2024 14:05:45 +0000" },
            { "name": "Content-Type", "value": "text/plain; charset=UTF-8" },
            { "name": "X-Campaign-Id", "value": "summer-sale-2024" }
        ],
        "tags": {
            "ses:configuration-set": [
                "kXVCt2Vd4dvm3MDvpc5Ml"
            ],
            "ses:from-domain": [
                "example.com"
            ],
            "ses:source-ip": [
                "123.123.123.123"
            ],
            "key1": [
                "value1"
            ],
            "key2": [
                "value2"
            ]
        }
    },
    "open": {
        "ipAddress": "192.0.2.1",
        "timestamp": "2024-04-25T18:08:04.933666+03:00",
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_3 like Mac OS X) AppleWebKit/603.3.8 (KHTML, like Gecko) Mobile/14G60"
    },
    "eventId": "jdMtnVniDeHqlQX8ygwEX:0"
}

Уведомление о том, что получатель перешел по ссылке в письме

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

Пример уведомления:

{
    "eventType": "Click",
    "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"
        },
        "headers": [
            { "name": "From", "value": "User <user@example.com>" },
            { "name": "To", "value": "Recipient Name <recipient@example.com>" },
            { "name": "Subject", "value": "Message sent using Yandex Cloud Postbox" },
            { "name": "Date", "value": "Thu, 27 Jun 2024 14:05:45 +0000" },
            { "name": "Content-Type", "value": "text/plain; charset=UTF-8" },
            { "name": "X-Campaign-Id", "value": "summer-sale-2024" }
        ],
        "tags": {
            "ses:configuration-set": [
                "kXVCt2Vd4dvm3MDvpc5Ml"
            ],
            "ses:from-domain": [
                "example.com"
            ],
            "ses:source-ip": [
                "123.123.123.123"
            ],
            "key1": [
                "value1"
            ],
            "key2": [
                "value2"
            ]
        }
    },
    "click": {
        "ipAddress": "192.0.2.1",
        "timestamp": "2024-04-25T18:08:04.933666+03:00",
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_3 like Mac OS X) AppleWebKit/603.3.8 (KHTML, like Gecko) Mobile/14G60",
        "url": "https://example.com/some-link",
        "linkTags": {
            "key1": [
                "value1"
            ],
            "key2": [
                "value2"
            ]
        }
    },
    "eventId": "jdMtnVniDeHqlQX8ygwEX:0"
}

Уведомление о том, что доставка письма задерживается

После того как Yandex Cloud Postbox успешно принял письмо, обычно оно отправляется немедленно. Однако иногда может возникнуть небольшая задержка доставки. В таком случае приходит данное уведомление.

Уведомление приходит только один раз — после первой неудачной попытки доставки. Если доставить письмо так и не удалось, придет уведомление о том, что письмо не доставлено.

Пример уведомления:

{
    "eventType": "DeliveryDelay",
    "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"
        },
        "headers": [
            { "name": "From", "value": "User <user@example.com>" },
            { "name": "To", "value": "Recipient Name <recipient@example.com>" },
            { "name": "Subject", "value": "Message sent using Yandex Cloud Postbox" },
            { "name": "Date", "value": "Thu, 27 Jun 2024 14:05:45 +0000" },
            { "name": "Content-Type", "value": "text/plain; charset=UTF-8" },
            { "name": "X-Campaign-Id", "value": "summer-sale-2024" }
        ],
        "tags": {
            "ses:configuration-set": [
                "kXVCt2Vd4dvm3MDvpc5Ml"
            ],
            "ses:from-domain": [
                "example.com"
            ],
            "ses:source-ip": [
                "123.123.123.123"
            ],
            "key1": [
                "value1"
            ],
            "key2": [
                "value2"
            ]
        }
    },
    "deliveryDelay": {
        "delayType": "General",
        "delayedRecipients": [
            {
                "emailAddress": "recipient@example.com",
                "status": "4.4.1",
                "diagnosticCode": "421 4.4.1 Connection timed out"
            }
        ],
        "reportingMTA": "mx.example.com",
        "timestamp": "2024-04-25T18:10:04.973666+03:00"
    },
    "eventId": "jdMtnVniDeHqlQX8ygwEX:0"
}

Уведомление о том, что получатель отписался от рассылки

Приходит, когда получатель отписался от рассылки через механизм «отказ от подписки в один клик» (one-click unsubscribe), добавленный Yandex Cloud Postbox в письмо.

Пример уведомления:

{
    "eventType": "Subscription",
    "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"
        },
        "headers": [
            { "name": "From", "value": "User <user@example.com>" },
            { "name": "To", "value": "Recipient Name <recipient@example.com>" },
            { "name": "Subject", "value": "Message sent using Yandex Cloud Postbox" },
            { "name": "Date", "value": "Thu, 27 Jun 2024 14:05:45 +0000" },
            { "name": "Content-Type", "value": "text/plain; charset=UTF-8" },
            { "name": "X-Campaign-Id", "value": "summer-sale-2024" }
        ],
        "tags": {
            "ses:configuration-set": [
                "kXVCt2Vd4dvm3MDvpc5Ml"
            ],
            "ses:from-domain": [
                "example.com"
            ],
            "ses:source-ip": [
                "123.123.123.123"
            ],
            "key1": [
                "value1"
            ],
            "key2": [
                "value2"
            ]
        }
    },
    "subscription": {
        "contactList": "my-list",
        "timestamp": "2024-04-25T18:08:04.973666+03:00",
        "source": "UnsubscribeHeader"
    },
    "eventId": "jdMtnVniDeHqlQX8ygwEX:0"
}

Уведомление о жалобе на письмо

Приходит, когда получатель пожаловался на полученное письмо, а интернет-провайдер (ISP) отправил эту жалобу в Yandex Cloud Postbox.

Пример уведомления:

{
    "eventType": "Complaint",
    "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"
        },
        "headers": [
            { "name": "From", "value": "User <user@example.com>" },
            { "name": "To", "value": "Recipient Name <recipient@example.com>" },
            { "name": "Subject", "value": "Message sent using Yandex Cloud Postbox" },
            { "name": "Date", "value": "Thu, 27 Jun 2024 14:05:45 +0000" },
            { "name": "Content-Type", "value": "text/plain; charset=UTF-8" },
            { "name": "X-Campaign-Id", "value": "summer-sale-2024" }
        ],
        "tags": {
            "ses:configuration-set": [
                "kXVCt2Vd4dvm3MDvpc5Ml"
            ],
            "ses:from-domain": [
                "example.com"
            ],
            "ses:source-ip": [
                "123.123.123.123"
            ],
            "key1": [
                "value1"
            ],
            "key2": [
                "value2"
            ]
        }
    },
    "complaint": {
        "complainedRecipients": [
            {
                "emailAddress": "recipient@example.com"
            }
        ],
        "complaintFeedbackType": "abuse",
        "arrivalDate": "2024-04-25T18:05:04.84108+03:00",
        "timestamp": "2024-04-25T18:10:04.973666+03:00",
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_3 like Mac OS X) AppleWebKit/603.3.8 (KHTML, like Gecko) Mobile/14G60"
    },
    "eventId": "jdMtnVniDeHqlQX8ygwEX:0"
}

Формат уведомлений

Уведомление записывается в поток данных Yandex Data Streams в формате JSON. Последовательность и набор полей могут отличаться от описанных ниже.

Основной объект

Название	Тип	Описание
`eventType`	Строка	Тип уведомления. Возможные значения: `Bounce`, `Click`, `Complaint`, `Delivery`, `DeliveryDelay`, `Open`, `Rendering Failure`, `Send`, `Subscription`.
`mail`	Объект Mail	Объект, который содержит общую информацию об отправленном письме.
`send`	Объект Send	Пустой объект. Обязателен, если `eventType` — `Send`, иначе отсутствует.
`bounce`	Объект Bounce	Объект, который содержит информацию о том, что письмо не доставлено. Обязателен, если `eventType` — `Bounce`, иначе отсутствует.
`delivery`	Объект Delivery	Объект, который содержит информацию о доставке письма отдельному получателю. Обязателен, если `eventType` — `Delivery`, иначе отсутствует.
`complaint`	Объект Complaint	Объект, который содержит информацию о жалобе получателя на письмо. Обязателен, если `eventType` — `Complaint`, иначе отсутствует.
`subscription`	Объект Subscription	Объект, который содержит информацию о том, что получатель отписался от рассылки. Обязателен, если `eventType` — `Subscription`, иначе отсутствует.
`deliveryDelay`	Объект DeliveryDelay	Объект, который содержит информацию о задержке доставки письма. Обязателен, если `eventType` — `DeliveryDelay`, иначе отсутствует.
`open`	Объект Open	Объект, который содержит информацию о том, что письмо было открыто. Обязателен, если `eventType` — `Open`, иначе отсутствует.
`click`	Объект Click	Объект, который содержит информацию о переходе по ссылке в письме. Обязателен, если `eventType` — `Click`, иначе отсутствует.
`failure`	Объект Failure	Объект, который содержит информацию об ошибке рендеринга письма. Обязателен, если `eventType` — `Rendering Failure`, иначе отсутствует.
`eventId`	Строка	Уникальный идентификатор события.

Объект Mail

Название	Тип	Описание
`timestamp`	Строка	Дата в формате RFC 3339 (`2006-01-02T15:04:05Z07:00`). Время, когда письмо было принято Yandex Cloud Postbox.
`messageId`	Строка	Уникальный идентификатор письма. У одного письма может быть несколько получателей. Выдается Yandex Cloud Postbox при приеме письма в обработку.
`identityId`	Строка	Идентификатор адреса Yandex Cloud Postbox, который используется при отправке письма.
`commonHeaders`	Объект CommonHeaders	Объект, который содержит основные заголовки письма.
`headers`	Массив объектов Header	Полный список заголовков письма в том виде, в котором они поступили в Yandex Cloud Postbox (до того как сервис добавил собственные служебные заголовки). Включает пользовательские заголовки, добавленные отправителем, например `X-Campaign-Id`. Поле отсутствует, если заголовки письма не сохранены.
`headersTruncated`	Логический	Поле присутствует, только если его значение — `true`. Если значение `true`, список `headers` неполный: его обрезали с конца, потому что суммарный размер заголовков превысил 10 КиБ.
`tags`	Объект	Объект, который содержит теги, добавленные к письму. Значение каждого тега — массив строк. Пользовательские теги всегда содержат только один элемент.

Примечание

В headers попадают заголовки письма в том виде, в котором их передал отправитель, включая пользовательские заголовки (например, X-Campaign-Id). Заголовки, которые Yandex Cloud Postbox добавляет или изменяет при обработке письма (например, List-Unsubscribe, List-Unsubscribe-Post, DKIM-Signature), в headers не попадают. Порядок заголовков сохраняется.

Примечание

headers содержит исходные заголовки письма, а commonHeaders — итоговые, полученные после обработки письма сервисом. Поэтому commonHeaders.messageId — это идентификатор, выданный Yandex Cloud Postbox, а в headers может находиться собственный заголовок Message-Id отправителя.

Значения заголовков передаются в уведомлении без изменений — в том виде, в каком они содержались в письме. Если заголовок закодирован в соответствии с RFC 2047 (например, тема письма или отображаемое имя отправителя на кириллице), в уведомление попадет закодированное значение. Раскодировать его нужно на стороне получателя уведомления. Это касается всех элементов headers, а также полей commonHeaders.from, commonHeaders.to и commonHeaders.subject.

Объект CommonHeaders

Название	Тип	Описание
`from`	Массив строк	Содержимое заголовка `From`, разбитое по адресам. Пустое значение, если заголовка в письме не было. Если разобрать значение по адресам не удалось, массив содержит один элемент — исходную строку заголовка целиком.
`to`	Массив строк	Содержимое заголовка `To`, разбитое по адресам. Пустое значение, если заголовка в письме не было. Если разобрать значение по адресам не удалось, массив содержит один элемент — исходную строку заголовка целиком.
`subject`	Строка	Содержимое заголовка `Subject`. Пустая строка, если заголовка в письме не было.
`date`	Строка	Содержимое заголовка `Date`. Пустая строка, если заголовка в письме не было.
`messageId`	Строка	Уникальный идентификатор письма. Выдается Yandex Cloud Postbox при приеме письма.
`originalMessageId`	Строка	Значение заголовка `Original-Message-ID`, если отправитель передал его в письме. Иначе — пустая строка.

Объект Header

Название	Тип	Описание
`name`	Строка	Имя заголовка письма.
`value`	Строка	Значение заголовка письма.

Объект Send

Пустой объект.

Объект Bounce

Название	Тип	Описание
`bounceType`	Строка	Тип ошибки. Возможные значения: `Permanent` — письмо не доставлено.
`bounceSubType`	Строка	Подтип ошибки. Возможные значения: `Undetermined` — причина ошибки не определена; `Suppressed` — письмо не доставлено, потому что получатель находится в глобальном стоп-листе Yandex Cloud Postbox; `OnAccountSuppressionList` — письмо не доставлено, потому что получатель находится в стоп-листе пользователя Yandex Cloud Postbox; `InsufficientTLS` — не удалось установить TLS-соединение нужного уровня с сервером получателя; `StartTlsNotOffered` — сервер получателя не поддерживает команду `STARTTLS`; `TlsCertificateUntrusted` — сертификат сервера получателя не является доверенным; `TlsVersionTooLow` — версия TLS, которую поддерживает сервер получателя, ниже допустимой.
`bouncedRecipients`	Массив объектов BounceRecipient	Массив, который содержит информацию о получателе письма и связанной с ним ошибке доставки, если она была.
`dialAttempts`	Массив объектов DialAttempt	Необязательное поле. Список попыток подключения к почтовым серверам получателя с описанием ошибки по каждой попытке. Отсутствует, если подключение не выполнялось, — например, когда адрес получателя находится в стоп-листе.
`timestamp`	Строка	Дата в формате RFC 3339 (`2006-01-02T15:04:05Z07:00`). Время, когда получена ошибка от почтового клиента получателя.

Объект BounceRecipent

Название	Тип	Описание
`emailAddress`	Строка	Электронный адрес получателя.
`action`	Строка	Необязательное поле. Результат отправки. Возможные значения: `failed`.
`status`	Строка	Необязательное поле. SMTP-код ответа.
`diagnosticCode`	Строка	Необязательное поле. Расширенный текст ошибки. Для ошибки, полученной от сервера получателя, содержит текст ответа этого сервера. В остальных случаях принимает одно из фиксированных значений: `Host or MX not found`, `Too many attempts`, `Spam detected`, `Insufficient TLS`, `STARTTLS not offered by recipient MX`, `TLS certificate not trusted`, `TLS version too low`, `Blocked by Global Suppression List`, `Blocked by Account Suppression List`, `Other`, `Unknown`.

Объект DialAttempt

Название	Тип	Описание
`mxHost`	Строка	Имя почтового сервера получателя (MX-хоста), к которому выполнялось подключение. Передается в виде полного доменного имени (FQDN) и может содержать точку в конце.
`ip`	Строка	IP-адрес, к которому выполнялось подключение.
`reason`	Строка	Код причины ошибки. Возможные значения: `Smtp`, `HostOrMXNotFound`, `Spam`, `TooManyAttempts`, `InsufficientTLS`, `StartTlsNotOffered`, `TlsCertUntrusted`, `TlsVersionTooLow`, `Other`.
`error`	Строка	Текст ошибки для этой попытки подключения. Содержимое поля не имеет фиксированного формата и может меняться, поэтому опираться на него при программной обработке не следует — для этого предназначено поле `reason`.
`negotiatedTls`	Строка	Необязательное поле. Версия TLS, согласованная с сервером получателя, например `TLSv1.2`. Отсутствует, если TLS-соединение не было установлено.

Объект Click

Название	Тип	Описание
`ipAddress`	Строка	IP-адрес устройства получателя, с которого перешли по ссылке.
`timestamp`	Строка	Дата в формате RFC 3339 (`2006-01-02T15:04:05Z07:00`). Время, когда получатель перешел по ссылке.
`userAgent`	Строка	Идентификационная строка (`User-Agent`) устройства или почтового клиента, с которого перешли по ссылке.
`url`	Строка	Оригинальный URL, по которому перешел получатель.
`linkTags`	Объект	Объект, который содержит теги, добавленные к ссылке.

Объект Complaint

Название	Тип	Описание
`complainedRecipients`	Массив объектов ComplainedRecipient	Массив, который содержит информацию о получателях, которые могли подать жалобу.
`timestamp`	Строка	Дата в формате RFC 3339 (`2006-01-02T15:04:05Z07:00`). Время, когда интернет-провайдер отправил жалобу в Yandex Cloud Postbox.
`complaintFeedbackType`	Строка	Необязательное поле. Тип жалобы из отчета интернет-провайдера. Возможные значения: `abuse` — нежелательная почта или иное злоупотребление; `auth-failure` — ошибка аутентификации письма; `fraud` — фишинг или мошенничество; `not-spam` — получатель не считает письмо спамом (используется для исправления ложного срабатывания); `other` — жалоба, не соответствующая остальным типам; `virus` — в письме обнаружен вирус.
`arrivalDate`	Строка	Необязательное поле. Дата в формате RFC 3339 (`2006-01-02T15:04:05Z07:00`). Время, когда оригинальное письмо поступило на сервер получателя.
`userAgent`	Строка	Необязательное поле. Значение поля `User-Agent` из отчета о жалобе — имя и версия системы, которая сгенерировала отчет.

Объект ComplainedRecipient

Название	Тип	Описание
`emailAddress`	Строка	Электронный адрес получателя, который мог подать жалобу.

Объект Delivery

Название	Тип	Описание
`timestamp`	Строка	Дата в формате RFC 3339 (`2006-01-02T15:04:05Z07:00`). Время, когда Yandex Cloud Postbox отправил письмо и получил успешный ответ от почтового клиента получателя.
`processingTimeMillis`	Целое число	Время, которое потребовалось на обработку письма в миллисекундах.
`recipients`	Массив строк	Адреса получателей.

Объект DeliveryDelay

Название	Тип	Описание
`delayType`	Строка	Тип задержки. Возможные значения: `General`.
`delayedRecipients`	Массив объектов DelayedRecipient	Массив, который содержит информацию о получателе письма и связанной с ним задержке доставки.
`reportingMTA`	Строка	Имя почтового сервера получателя, который сообщил о задержке доставки. Может быть пустой строкой, если сервер определить не удалось.
`timestamp`	Строка	Дата в формате RFC 3339 (`2006-01-02T15:04:05Z07:00`). Время, когда случилась задержка доставки.

Объект DelayedRecipient

Название	Тип	Описание
`emailAddress`	Строка	Электронный адрес получателя.
`status`	Строка	SMTP-код ответа сервера получателя. Может быть пустой строкой.
`diagnosticCode`	Строка	Необязательное поле. Расширенный текст ошибки. Может содержать текст ответа сервера получателя.

Объект Failure

Название	Тип	Описание
`errorMessage`	Строка	Описание ошибки рендеринга.
`templateName`	Строка	Необязательное поле. Имя шаблона, при рендеринге которого возникла ошибка, если оно передается в уведомлении.

Объект Subscription

Название	Тип	Описание
`contactList`	Строка	Имя списка контактов, с которым связано письмо.
`timestamp`	Строка	Дата в формате RFC 3339 (`2006-01-02T15:04:05Z07:00`). Время, когда получатель отписался от рассылки.
`source`	Строка	Источник отписки. Возможные значения: `UnsubscribeHeader`.

Объект Open

Название	Тип	Описание
`ipAddress`	Строка	IP-адрес устройства получателя, с которого было открыто письмо.
`timestamp`	Строка	Дата в формате RFC 3339 (`2006-01-02T15:04:05Z07:00`). Время, когда письмо было открыто.
`userAgent`	Строка	Идентификационная строка (`User-Agent`) устройства или почтового клиента, с которого было открыто письмо.

Системные теги

При отправке письма Yandex Cloud Postbox добавляет к письму следующие системные теги, которые затем включаются в уведомления.

Общие теги:

Название	Описание
`ses:configuration-set`	Идентификатор конфигурации, использованной при отправке письма.
`ses:from-domain`	Домен, с которого отправлено письмо.
`ses:source-ip`	IP-адрес сервера, с которого пользователь отправил письмо в Yandex Cloud Postbox.

Дополнительные теги, которые включаются только в уведомления о доставке:

Название	Описание
`ses:outgoing-tls-version`	Версия TLS, использованная при отправке письма на сервер получателя.
`ses:outgoing-tls-cipher`	Шифр TLS, использованный при отправке письма на сервер получателя.
`ses:outgoing-ip`	IP-адрес сервера, с которого Yandex Cloud Postbox отправил письмо на сервер получателя.

Уровень качества обслуживания (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 не найден, его адрес временно попадет в стоп-лист. Прежде чем пытаться отправлять письмо на такой адрес повторно, необходимо подождать некоторое время, иначе придет уведомление о том, что письмо не доставлено, потому что получатель находится в стоп-листе.

Уведомления об операциях с письмами

Типы уведомленийТипы уведомлений

Уведомление о приеме письма сервисомУведомление о приеме письма сервисом

Уведомление об ошибке рендеринга письмаУведомление об ошибке рендеринга письма

Уведомление о доставке письмаУведомление о доставке письма

Уведомление о том, что письмо не доставленоУведомление о том, что письмо не доставлено

Уведомление о том, что письмо открытоУведомление о том, что письмо открыто

Уведомление о том, что получатель перешел по ссылке в письмеУведомление о том, что получатель перешел по ссылке в письме

Уведомление о том, что доставка письма задерживаетсяУведомление о том, что доставка письма задерживается

Уведомление о том, что получатель отписался от рассылкиУведомление о том, что получатель отписался от рассылки

Уведомление о жалобе на письмоУведомление о жалобе на письмо

Формат уведомленийФормат уведомлений

Основной объектОсновной объект

Объект MailОбъект Mail

Объект CommonHeadersОбъект CommonHeaders

Объект HeaderОбъект Header

Объект SendОбъект Send

Объект BounceОбъект Bounce

Объект BounceRecipentОбъект BounceRecipent

Объект DialAttemptОбъект DialAttempt

Объект ClickОбъект Click

Объект ComplaintОбъект Complaint

Объект ComplainedRecipientОбъект ComplainedRecipient

Объект DeliveryОбъект Delivery

Объект DeliveryDelayОбъект DeliveryDelay

Объект DelayedRecipientОбъект DelayedRecipient

Объект FailureОбъект Failure

Объект SubscriptionОбъект Subscription

Объект OpenОбъект Open

Системные тегиСистемные теги

Уровень качества обслуживания (QoS)Уровень качества обслуживания (QoS)

Пример работыПример работы

Была ли статья полезна?

Типы уведомлений

Уведомление о приеме письма сервисом

Уведомление об ошибке рендеринга письма

Уведомление о доставке письма

Уведомление о том, что письмо не доставлено

Уведомление о том, что письмо открыто

Уведомление о том, что получатель перешел по ссылке в письме

Уведомление о том, что доставка письма задерживается

Уведомление о том, что получатель отписался от рассылки

Уведомление о жалобе на письмо

Формат уведомлений

Основной объект

Объект Mail

Объект CommonHeaders

Объект Header

Объект Send

Объект Bounce

Объект BounceRecipent

Объект DialAttempt

Объект Click

Объект Complaint

Объект ComplainedRecipient

Объект Delivery

Объект DeliveryDelay

Объект DelayedRecipient

Объект Failure

Объект Subscription

Объект Open

Системные теги

Уровень качества обслуживания (QoS)

Пример работы