How the List-Unsubscribe header works

You may be here because you heard that GMail is now enforcing best practices for bulk senders, including adding the List-Unsubscribe header to your emails.

Since Groundhogg always follows best practices, we have included this header since 2019! There's nothing you need to do.

What is the List-Unsubscribe header?

The List-Unsubscribe header is used to identify that the email is from an email list and provide the recipient with an alternate method to unsubscribe from future emails via the inbox.

In most cases, recipients will see an option to unsubscribe above the email content in their email client of choice. Below is an example from Gmail.

Is the List-Unsubscribe Header required?

As of February 2024, the List-Unsubscribe is required by Gmail for bulk senders. It has been a best practice since before, and including it helps with deliverability.

It is not required for transactional emails and is not included in transactional emails sent by Groundhogg.

How does the List-Unsubscribe header work?

The List-Unsubscriber header provides an alternate way for recipients to unsubscribe from your emails besides the unsubscribe link by adding 3 headers to your outgoing emails.

List-Unsubscribe: <https://www.example.come/wp-json/gh/v4/unsubscribe/abcd1234/a1b2c3d4e5>, <mailto:unsubscribe@example.com?subject=Unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Id: www.example.com

Gmail is currently the only inbox that supports One-Click unsubscribe, meaning that all users need to do is click the Unsubscribe button and confirm.

When the recipient confirms, a POST request is sent to the Groundhogg API, and the contact is unsubscribed automatically. If you have a Groundhogg subscription, you can enable the Automatic email unsubscribe feature to handle email notifications.

Other inboxes will send you an email notification indicating the recipient wishes to unsubscribe, in which case you may have to manually unsubscribe that recipient from your list when you receive the email.

Currently, only some inboxes support unsubscribing from the List-Unsubscribe header. 

Some inboxes may not show the list-unsubscribe feature even if the required headers are included until you've built up sufficient sender reputation.

Handling unsubscribe email notifications

By default, Groundhogg can't parse unsubscribe notifications sent by inboxes. You will have to manually process them.

You can change where these notifications are sent by going to Groundhogg > Settings > Email > Unsubscribe and changing the Unsubscribe Notification Email Address.

Automatically handling unsubscribe email notifications

If you have a paid Groundhogg subscription, you can use the Automatic email unsubscribe feature to handle unsubscribe notifications from inboxes.

To enable this feature you must have the Advanced Features addon activated.

Go to Groundhogg > Settings > Email > Unsubscribe and enable the option called "Automatically handle unsubscribe notifications" which will be available to you after you've added your license key and activated Advanced Features.

When this feature is activated email notifications will no longer be sent to your inbox, but they will be sent to a special pseudo inbox (hosted by Groundhogg) that will then send a POST request to your site similar to the way the One-Click unsubscribe link works in Gmail.

Here's how it works...

1) Unsubscribe notifications will be sent to a pseudo inbox at the hostname @unsubscribe-me.com instead of your email address. So your List-Unsubscribe header will look like the following...

List-Unsubscribe: <https://example.com/wp-json/gh/v4/unsubscribe/abcd/1234>, <mailto:unsubscribe=example.com=abcd/1234@unsubscribe-me.com?subject=Unsubscribe>

unsubscribe-me.com is a domain we own and is solely used for automatically handling inbox unsubscribe notifications.

The username of the pseudo inbox contains all the information needed to facilitate unsubscribing the recipient. 

unsubscribe=<yoursite.com>=<unique-event-id>/<unique-token>@unsubscribe-me.com

2) When an email is received in the pseudo inbox, our service will send a POST request to your site which is identified within the username of the special inbox, with the event ID and token, and unsubscribe the recipient automatically.

3) The notification and results of any requests will be deleted immediately after the POST request is sent to your site.

Abuse considerations

It would be incredibly difficult to fake the unique token required to unsubscribe a recipient. Equivalent to guessing a complex password. It's highly unlikely that unsavory individuals would be able to abuse the system by sending "fake" requests to the unsubscribe endpoint.

The token also expires after 7 days, and tokens are generated uniquely for each email sent to the recipient.

The only legitimate way to receive a token is to receive an email, and the token must match the event ID associated with the email sent, making spoofing tokens next to impossible.

Privacy considerations

Groundhogg does not retain any information about your recipients or subscribers. After sending the request to unsubscribe the recipient from your list, all information regarding that request and the initial unsubscribe notification is deleted.

We host the pseudo inbox and service which facilitates the POST requests on servers located in Germany.