Contact UsTry it for free
© 2026 Direct Cursus Technology L.L.C.

Email event notifications

Written by
Updated at February 11, 2026

To get email event notifications, create a configuration and associate it with your address.

Notification types

Notification of email acceptance by the service

Comes when Yandex Cloud Postbox has accepted the email for processing.

Notification example:

{
    "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"
        },
        "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"
}

Email delivered notification

Comes when the email was sent and the recipient's email client has confirmed acceptance.

Notification example:

{
    "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"
        },
        "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"
            ]
        }
    },
    "bounce": null,
    "delivery": {
        "timestamp": "2024-04-25T18:05:14.84107+03:00",
        "processingTimeMillis": 9999,
        "recipients": [
            "abc@example.com"
        ]
    },
    "eventId": "ce3uqnS9pzQBMsnaAbrT_:0"
}

Email not delivered notification

Comes when the recipient's email client responds to a delivery attempt with an error which, according to Yandex Cloud Postbox, does not require another delivery attempt, or when the recipient's address is on the stop list.

Notification example:

{
    "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"
        },
        "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",
    },
    "delivery": null,
    "eventId": "jdMtnVniDeHqlQX8ygwEX:0"
}

Email open notification

You get this type of notification when the recipient opens the email.

Notification example:

{
    "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"
        },
        "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"
}

Email click notification

You get this type of notification when the recipient clicks the link in your email.

Notification example:

{
    "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"
        },
        "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"
}

Delayed email delivery notification

Once successfully accepted by Yandex Cloud Postbox, the email is normally sent it right away. However, a slight delay in delivery may sometimes occur. It is in this case that you receive this type of notification.

Notification example:

{
    "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"
        },
        "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"
            }
        ],
        "timestamp": "2024-04-25T18:10:04.973666+03:00"
    },
    "eventId": "jdMtnVniDeHqlQX8ygwEX:0"
}

Recipient unsubscribe notification

You get this type of notification when the recipient uses one-click unsubscribe that Yandex Cloud Postbox adds to emails.

Notification example:

{
    "eventType": "Unsubscribe",
    "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"
        },
        "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"
    }
}

Notification format

The notification is written to the Yandex Data Streams data stream in JSON format. The list and sequence of fields may differ from those described below.

Main object

Field Type Description
notificationType String Notification type. The possible values are Bounce, Delivery, and Send.
mail Mail object Object containing general information about the sent email.
bounce Bounce object Object containing information that the email has not been delivered. Required if the notificationType is Bounce; otherwise, not present.
delivery Delivery object Object containing information about the email being delivered to an individual recipient. Required if the notificationType is Delivery; otherwise, not present.
subscription Subscription object Object containing information that the recipient has unsubscribed from the mailing list. Required if the notificationType is Subscription; otherwise, not present.
open Open object Object containing information that the email has been opened. Required if the notificationType is Open; otherwise, not present.
eventId String Unique ID of the event.

Mail object

Field Type Description
timestamp String Date in RFC 3339 (2006-01-02T15:04:05Z07:00) format. Time the email was accepted by Yandex Cloud Postbox.
messageId String Unique ID of the email. One email can have multiple recipients. Sent by Yandex Cloud Postbox when accepting the email for processing.
identityId String ID of the Yandex Cloud Postbox address used when sending the email.
commonHeaders CommonHeaders object Object containing the main headers of the email.
tags Object Object containing tags added to the email.

CommonHeaders object

Field Type Description
from Array of strings Contents of the From header, broken down by address.
to Array of strings Contents of the To header, broken down by address.
subject String Contents of the Subject header.
date String Contents of the Date header.
messageId String Unique ID of the email. Sent by Yandex Cloud Postbox when accepting the email.

Send object

Empty object.

Bounce object

Field Type Description
bounceType String Error type. The possible values are:
  • Permenent: Email not delivered.
bounceSubType String Error subtype. The possible values are:
  • Undetermined: Unknown error.
  • Suppressed: Email not delivered because the recipient is on the stop list.
bouncedRecipients Array of BounceRecipient objects Array containing information about the email recipient and the related delivery error, if any.
timestamp String Date in RFC 3339 (2006-01-02T15:04:05Z07:00) format. Time the error was received from the recipient's email client.

BounceRecipient object

Field Type Description
emailAddress String Recipient's email address.
action String Optional field. Result of sending. The possible value is failed.
status String Optional field. SMTP response code.
diagnosticCode String Optional field. Extended error text. May contain error text from the recipient's email client.

Click object

Field Type Description
ipAddress String IP address of the recipient’s device used to open the link.
timestamp String Date in RFC 3339 (2006-01-02T15:04:05Z07:00) format. Time when the recipient clicked the link.
userAgent String Identification string (User-Agent) of the device or email the client used to open the link.
url String Original URL the recipient opened.
linkTags Object Object containing tags added to the link.

Delivery object

Field Type Description
timestamp String Date in RFC 3339 (2006-01-02T15:04:05Z07:00) format. Time when Yandex Cloud Postbox sent the email and received a successful response from the recipient's email client.
processingTimeMillis Integer Time spent to process the email in milliseconds.
recipients Array of strings Addresses of recipients.

DeliveryDelay object

Field Type Description
delayType String Delay type. The possible value is General.
delayedRecipients DelayedRecipient object array Array containing information about the email recipient and the related delivery delay.
timestamp String Date in RFC 3339 (2006-01-02T15:04:05Z07:00) format. Delivery delay timestamp.

DelayedRecipient object

Field Type Description
emailAddress String Recipient's email address.

Subscription object

Field Type Description
contactList String Name of the contact list associated with the email.
timestamp String Date in RFC 3339 (2006-01-02T15:04:05Z07:00) format. Recipient unsubscribe timestamp.
source String Unsubscribe source. The possible value is UnsubscribeHeader.

Open object

Field Type Description
ipAddress String IP address of the recipient’s device used to open the email.
timestamp String Date in RFC 3339 (2006-01-02T15:04:05Z07:00) format. Email opening timestamp.
userAgent String Identification string (User-Agent) of the device or email the client used to open the email.

System tags

When sending an email, Yandex Cloud Postbox adds the following system tags to it and then includes them in notifications.

Common tags:

Field Description
ses:configuration-set ID of the configuration used when sending the email.
ses:from-domain Domain the email was sent from.
ses:source-ip IP address of the server the email to Yandex Cloud Postbox was sent from by the user.

Additional tags included only into delivery notifications:

Field Description
ses:outgoing-tls-version TLS version used to send the email to the recipient server.
ses:outgoing-tls-cipher TLS cipher used to send the email to the recipient server.
ses:outgoing-ip IP address of the server from which the email was sent by Yandex Cloud Postbox to the recipient server.

Quality of service (QoS) level

To deliver notifications, the service supports the QoS 1: At least once quality of service level, so it is possible to resend notifications. Identical notifications have the same eventId.

If an address is linked to a configuration that has multiple subscriptions added to it, a separate notification will come for each assignment.

Use case

You sent an email to two recipients: user1@example.com and user2@other.example.com. Yandex Cloud Postbox sent it to both recipients separately.

The email client of user1@example.com accepted the email. The email client of the recipient user2@other.example.com returned an error after the first attempt to send the email and declined to accept the email after the second attempt, replying that the user was not found.

In which case you will get these three notifications:

  • Notification that Yandex Cloud Postbox accepted the email for processing.
  • Notification that the email was delivered to user1@example.com.
  • Notification that the email was not delivered to user2@other.example.com with the error info. The notification will come after the second attempt to send the email.

Since the mail client responded that the recipient user2@other.example.com was not found, the address will be temporarily put on the stop list. You should wait for some time before trying to reach the address again, otherwise you will get notified that your message was not delivered because the recipient was on the stop list.

Previous
Overview
Next
Tracking email openings