Skip to content

One-click Unsubscribe

Info

This feature is an optional subscription for Pro plan.

Target users of this "List-Unsubscribe" feature

The "One-click Unsubscribe" option is primarly intended for customers who are using the following types of email delivery environments.

  • The primary purpose of sending emails is for marketing or promotion, and it is necessary to provide a "one-click unsubscribe" method to email recipients.
  • Operating an e-mail distribution environment that does not allow you to add a "List-Unsubscribe" email header to the delivered emails.
  • Want to simplify the development and implementation of a system that handles unsubscribe requests via "one-click unsubscription".

Why need to add "One-click Unsubscribe" feature?

The Gmail's "Email sender guidelines", updated by Google at October 2023, have added a new requirement to bulk email senders. It is "one-click unsubscribe" that let email recipients an easy way to unsubscribe from marketing or promotional emails.

This "One-click Unsubscribe" does not mean placing an unsubscribe link in the body of the email. It refers to the inclusion of a "List-Unsubscribe header" as defined in RFC8058 in the mail header. The guidelines also state that this requirement does not apply to transactional emails such as notification emails.

This feature is an option for PRO pran of Customers Mail Cloud. If you contract this, you can make Customers Mail Cloud add "List-Unsubscribe" email header when you send emails via Customers Mail Cloud and store the list of receipients that want to unsubscribe these emails.

Definition of List-Unsubscribe Header in RFC8058

Google requires email senders to provide one-click unsubscription functionality as defined in RFC8058 as an easy way for Gmail users to unsubscribe from incoming email subscriptions.

  • Placing one List-Unsubscribe header field and one List-Unsubscribe-Post header field in the message
  • Include one HTTPS URI in the List-Unsubscribe header field; other non-HTTP / S URIs such as MAILTO: are also allowed.
  • The List-Unsubscribe-Post header field must contain a single key/value pair "List-Unsubscribe = One-Click"
  • The message must be signed with a valid DomainKeys Identified Mail (DKIM) signature covering at least the List-Unsubscribe and List-Unsubscribe-Post headers

The bulk email senders must respond to the requirement above by adding a List-Unsubscribe header to the mail header of the delivered mail. When an email containing the List-Unsubscribe header is received by Gmail, the email recipient will see an "unsubscribe" link when viewing the Gmail mailbox, from where they can unsubscribe from the email with a single click.

When an e-mail recipient clicks on this link to unsubscribe, a POST request with the unsubscribe information is sent to the HTTPS URI specified in the List-Unsubscribe header. Based on this information, the email sender should remove the recipient from the email distribution list.

Note that the process of excluding unsubscribers from the email distribution list must be implemented in the system that receives the POST request.

Even if an email is delivered with a List-Unsubscribe header, the "unsubscribe" link may not always be displayed when the email is opened in Gmail. This is believed to be due to Gmail's control over whether or not the unsubscribe link is displayed based on the reliability of the domain sending the email and the delivery status of the email.

But if the List-Unsubscribe header is properly included in the email, the sender's guideline requirements are still met.

When you click on the unsubscribe link, a dialog box will appear asking you to confirm that you are sure you want to unsubscribe.

img_list_id

A dialog box will appear asking "Do you want to stop getting similar messages from *** ?". The part "***" can display the contents of the "List-Id" header based on the RFC2919 specification. If this is not set, the name displayed in the From header of the delivered e-mail will be displayed.

To customize this "***" part, a "List-Id" header must be added to the delivery email. For more information on this header, see the RFC 2919 specification. Also, if you wish to use this header in your unsubscribe filter settings, please see this example configuration.


Overview

By using the "One-click Unsubscribe" feature, you will be able to "send out emails with a List-unsubsciribe header added" and "list email recipients who have clicked on the unsubscribe link" on the Customers Mail Cloud. More details are below:

1. Sending out emails adding a List-Unsubscribe header

Apply the "Unsubscribe Filter" to emails delivered from Customers Mail Cloud. When the filter criteria are met, a List-Unsubscribe header is added to the email and the email is delivered.

Warning

As a prerequisite, the email headers defined in the "Unsubscribe Filter" condition must be included in emails delivered from the Customers Mail Cloud.

Emails delivered from Customers Mail Cloud with the List-Unsubscribe header will display an "Unsubscribe" link that can be operated by the email recipient with one-click.

When an email recipient clicks on the unsubscribe link to unsubscribe from an email, Customers Mail Cloud will collect and list this unsubscribed user information. This list can be used in the following sections.

3. Aggregate number of emails that are not delivered due to unsubscription

The number of emails not delivered due to unsubscription will be counted in error log and error graph in the "Delivery Reports" section.

4. Download the unsubscribe list via API

Email recipients who click on the unsubscribe link are collected into an "unsubscribe list" on the Customers Mail Cloud. This list can be retrieved in a CSV file via the API.

You can see here for the specification of this API.

Warning

Customers Mail Cloud will not re-send emails to recipients on the "Unsubscribe List".

However, the status of unsubscribe must be managed on the distribution list of the email delivery system that relays the emails to Customers Mail Cloud.

5. Cancel unsubscribed status to resume subscription via API

When an email recipient who has clicked on the unsubscribe link wishes to resubscribe, you must re-enable email delivery from the Customers Mail Cloud. In this case, this email recipient needs to be removed from the "unsubscribe list" via the API.

You can see here for the specification of this API.

Things to prepare in advance

To use this feature, the following points should be considered and prepared in advance.

1. How to include an email header in the sending emails that is used as a condition for the "Unsubscribe Filter"

Customers Mail Cloud does not have any distribution list to use for email delivery.

Therefore, an identifier email header must be added to each delivered email so that the "Unsubscribe Filter" set up in Customers Mail Cloud can determine whether or not to apply the unsubscribe link.

Examples of email header settings can be found in the "Examples of Filter Settings" section of "Adding an Unsubscribe Filter".

Note

If you want to manage unsubscribe status for each email distribution list, you will need to specify a unique email header value for each distribution list.

2. Consideration of how to remove email recipients who wish to unsubscribe from the distribution lists

Customers Mail Cloud does not have any distribution list to use for email delivery.

Therefore, the distribution lists that the email distribution system has need to be maintained based on the "unsubscribe list" on the Customers Mail Cloud.

This maintenance method and its integration with an email delivery system using the "Unsubscribe Download API" must be considered by the email sender.