Email delivery notifications
To get email delivery notifications, create a configuration and link it to 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": {
"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"
}
},
"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"
}
},
"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"
}
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
| Name | 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. |
eventId |
String | Unique ID of the event. |
Mail object
| Name | 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. |
CommonHeaders 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
Empty object.
Bounce object
| Name | Type | Description |
|---|---|---|
bounceType |
String | Error type. The possible values are:
|
bounceSubType |
String | Error subtype. The possible values are:
|
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
| Name | 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. |
Delivery object
| Name | 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. |
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.comwith 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.