[Yandex Cloud documentation](../../index.md) > [Yandex Cloud Postbox](../index.md) > [Concepts](index.md) > Email event notifications

# Email event notifications

To get email event notifications, [create a configuration](../operations/create-configuration.md) and [associate it with your address](../operations/bind-configuration.md).

## Notification types {#types}

### Notification of email acceptance by the service {#send}

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

Notification example:

```json
{
    "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 rendering error notification {#rendering-failure}

It appears if Yandex Cloud Postbox accepted the email for processing, but there was an error rendering the template.

Notification example:

```json
{
    "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"
        },
        "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 not_var{{name}} is missing"
    },
    "eventId": "vgAyRUls8591ybPKeH-Ov:0"
}
```

### Email delivered notification {#delivery}

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

Notification example:

```json
{
    "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 {#bounce}

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:

```json
{
    "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 {#open}

Comes when the recipient opens the email.

Notification example:

```json
{
    "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 {#click}

Comes when the recipient clicks a link in the email.

Notification example:

```json
{
    "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 {#delayed-delivery}

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:

```json
{
    "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 {#subscription}

Comes when the recipient uses the `one-click unsubscribe` mechanism added by Yandex Cloud Postbox into the email.

Notification example:

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

### Email complaint notification {#complaint}

Comes when the recipient complains about an incoming email, and the Internet Service Provider (ISP) forwards the complaint to Yandex Cloud Postbox.

Notification example:

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

## Notification format {#format}

The notification is written to the Yandex Data Streams [data stream](../../data-streams/concepts/glossary.md#stream-concepts) in JSON format. The list and sequence of fields may differ from those described below.

### Main object {#main-object}

Name | Type | Description
--- | --- | ---
`eventType` | String | [Notification type](#types). The possible values are `Bounce`, `Click`, `Complaint`, `Delivery`, `DeliveryDelay`, `Open`, `Rendering Failure`, `Send`, and `Subscription`.
`mail` | [Mail](#mail-object) object | Object containing general information about the sent email.
`bounce` | [Bounce](#bounce-object) object | Object containing information that the email has not been delivered. Required if the `eventType` is `Bounce`; otherwise, not present.
`delivery` | [Delivery](#delivery-object) object | Object containing information about the email being delivered to an individual recipient. Required if the `eventType` is `Delivery`; otherwise, not present.
`complaint` | [Complaint](#complaint-object) object | Object containing information about the recipient's complaint about an email. Required if the `eventType` is `Complaint`; otherwise, not present.
`subscription` | [Subscription](#subscription-object) object | Object containing information that the recipient has unsubscribed from the mailing list. Required if the `eventType` is `Subscription`; otherwise, not present.
`deliveryDelay` | [DeliveryDelay](#delivery-delay-object) object | Object containing information about the email delivery delay. Required if the `eventType` is `DeliveryDelay`; otherwise, not present.
`open` | [Open](#open-object) object | Object containing information that the email has been opened. Required if the `eventType` is `Open`; otherwise, not present.
`click` | [Click](#click-object) object | Object containing information about following a clickable link in the email. Required if the `eventType` is `Click`; otherwise, not present.
`failure` | [Failure](#failure-object) object | Object containing information about the email rendering error. Required if the `eventType` is `Rendering Failure`; otherwise, not present.
`eventId` | String | Unique ID of the event.

### Mail object {#mail-object}

Name | Type | Description
--- | --- | ---
`timestamp` | String | Date in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) (`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](#common-headers-object) object | Object containing the main headers of the email.
`tags` | Object | Object containing tags added to the email.

### CommonHeaders object {#common-headers-object}

Name | 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 {#send-object}

Empty object.

### Bounce object {#bounce-object}

Name | Type | Description
--- | --- | ---
`bounceType` | String | Error type. The possible values are:<ul><li>`Permenent`: Email not delivered.</li></ul>
`bounceSubType` | String | Error subtype. The possible values are:<ul><li>`Undetermined`: Unknown error.</li><li>`Suppressed`: Email not delivered because the recipient is on the stop list.</li></ul>
`bouncedRecipients` | Array of [BounceRecipient](#bounce-recipent-object) objects | Array containing information about the email recipient and the related delivery error, if any.
`timestamp` | String | Date in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) (`2006-01-02T15:04:05Z07:00`) format. Time the error was received from the recipient's email client.

### BounceRecipient object {#bounce-recipent-object}

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

### Click object {#click-object}

Name | Type | Description
--- | --- | ---
`ipAddress` | String | IP address of the recipient’s device used to open the link.
`timestamp` | String | Date in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) (`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.

### Complaint object {#complaint-object}

Name | Type | Description
--- | --- | ---
`complainedRecipients` | [ComplainedRecipient](#complained-recipient-object) object array | Array containing information about the recipients who might have filed the complaint.
`timestamp` | String | Date in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) (`2006-01-02T15:04:05Z07:00`) format. Time the ISP sent the complaint to Yandex Cloud Postbox.
`complaintFeedbackType` | String | This is an optional field. Complaint type from the ISP's report. The possible values are:<ul><li>`abuse`: Unsolicited mail or other misuse.</li><li>`auth-failure`: Email authentication error.</li><li>`fraud`: Phishing or fraud.</li><li>`not-spam`: Recipient does not think the email is spam (used to correct a false positive).</li><li>`other`: Complaint not falling under any other types.</li><li>`virus`: Virus detected in the email.</li></ul>
`arrivalDate` | String | This is an optional field. Date in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) (`2006-01-02T15:04:05Z07:00`) format. Time the original email arrived at the recipient’s server.
`userAgent` | String | This is an optional field. The `User-Agent` field value from the complaint report, i.e., the name and version of the system that generated the report.

### ComplainedRecipient object {#complained-recipient-object}

Name | Type | Description
--- | --- | ---
`emailAddress` | String | Email address of the recipient who might have filed the complaint.

### Delivery object {#delivery-object}

Name | Type | Description
--- | --- | ---
`timestamp` | String | Date in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) (`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 {#delivery-delay-object}

Name | Type | Description
--- | --- | ---
`delayType` | String | Delay type. The possible value is `General`.
`delayedRecipients` | [DelayedRecipient](#delayed-recipient-object) object array | Array containing information about the email recipient and the related delivery delay.
`timestamp` | String | Date in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) (`2006-01-02T15:04:05Z07:00`) format. Delivery delay timestamp.

### DelayedRecipient object {#delayed-recipient-object}

Name | Type | Description
--- | --- | ---
`emailAddress` | String | Recipient's email address.

### Failure object {#failure-object}

Name | Type | Description
--- | --- | ---
`errorMessage` | String | Rendering error description.
`templateName` | String | This is an optional field. The name of the template that threw an error when rendered, if sent in the notification.

### Subscription object {#subscription-object}

Name | Type | Description
--- | --- | ---
`contactList` | String | Name of the contact list associated with the email.
`timestamp` | String | Date in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) (`2006-01-02T15:04:05Z07:00`) format. Recipient unsubscribe timestamp.
`source` | String | Unsubscribe source. The possible value is `UnsubscribeHeader`.

### Open object {#open-object}

Name | Type | Description
--- | --- | ---
`ipAddress` | String | IP address of the recipient’s device used to open the email.
`timestamp` | String | Date in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) (`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 {#system-tags}

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

Common tags:

Name | Description
--- | ---
`ses:configuration-set` | ID of the [configuration](glossary.md#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](#delivery):

Name | 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 {#qos}

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](glossary.md#configuration) that has multiple [subscriptions](glossary.md#subscription.md) added to it, a separate notification will come for each assignment.

## Use case {#example}

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.