Unsubscribe mechanism

Yandex Cloud Postbox supports the one-click unsubscribe mechanism implemented under RFC 8058. For the mechanism to work correctly, the recipient’s email client must support it.

What is the unsubscribe mechanismWhat is the unsubscribe mechanism

The unsubscribe mechanism is a standardized method that enables email recipients to easily unsubscribe from newsletters. Without such a mechanism, users often mark unwanted emails as spam, which has a negative impact on the sender’s reputation and email deliverability.

One-click unsubscribe solves that problem by giving the recipients a quick way to unsubscribe from a newsletter right in the email client interface, without additional confirmations or the need to go to web pages and fill out forms.

How to add the unsubscribe mechanism to an emailHow to add the unsubscribe mechanism to an email

To activate the unsubscribe mechanism, provide the ListManagementOptions parameter when sending the email. The ListManagementOptions parameter contains the following attributes:

• ContactListName: Name of the contact list associated with the email. Required attribute.
• TopicName: Name of the subject within the list of contacts for the user to unsubscribe from. This is an optional attribute.

aws sesv2 send-email \
  --from-email-address mail@example.com \
  --destination file://destination.json \
  --content file://message.json \
  --list-management-options ContactListName=my-list, TopicName=newsletter \
  --endpoint-url https://postbox.cloud.yandex.net

X-SES-LIST-MANAGEMENT-OPTIONS: contactListName=my-list

X-SES-LIST-MANAGEMENT-OPTIONS: contactListName=my-list; topicName=newsletter

How the unsubscribe mechanism worksHow the unsubscribe mechanism works

Adding headersAdding headers

When you specify the ListManagementOptions parameter, Yandex Cloud Postbox automatically adds two headers to the email:

• List-Unsubscribe: Contains an HTTPS unsubscribe link.
• List-Unsubscribe-Post: List-Unsubscribe=One-Click: Indicates that unsubscribe is done in one click.

Examples of added headers:

List-Unsubscribe: <https://postbox.yandexcloud.net/tracking/v1/unsubscribe?token=...>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Preserving the existing headersPreserving the existing headers

Yandex Cloud Postbox does not overwrite the List-Unsubscribe header if it is already in the email and does not add the List-Unsubscribe-Post header.

Unsubscribe processingUnsubscribe processing

When a user clicks Unsubscribe in the email client, Yandex Cloud Postbox:

1. Processes the unsubscribe request.
2. Sends a notification if the user is subscribed to notifications.
3. Writes the event information to the execution log.