Custom Unsubscribe Links: staying compliant with list-unsubscribe-post (RFC 8058) requirements

Updated

Offering an unsubscribe option to give subscribers the ability to opt out of your marketing messages is not only standard best practice, it’s now a requirement in Google and Yahoo’s Bulk Sender 2024 Requirements. If you are using a custom unsubscribe solution, you’ll need to successfully implement RFC 8058 List-unsubscribe-post before June 1st, 2024.

How it works

Google and Yahoo have added new requirements, allowing recipients to unsubscribe from your marketing messages with a single click. If you use our default unsubscribe functionality, you don’t need to do anything. But if you use a custom unsubscribe solution, you need to follow the instructions on this page to implement the new requirements before June 1st, 2024.

The new requirement is RFC 8058 List-unsubscribe-post. It defines true one-click unsubscribe through an HTTPS URI POST that triggers an unsubscribe within 48 hours.

This requires technical development work

This guide is intended for technical users and developers. You’ll need to do some development work to implement RFC 8058. If your organization does not have development resources available to implement RFC 8058 before the June 1st, 2024 deadline, we strongly recommend switching to Customer.io’s default unsubscribe functionality.

Implement RFC 8058 for custom unsubscribes

Because your custom unsubscribe system is unique to your organization, and the consumption and processing of the required HTTPS POST exists within your own system, our Technical Support and Deliverability teams are unable to advise in detail. But we are happy to provide the following general guidance:

Step 1: Configure your system to receive the POST when recipients click “Unsubscribe”

The core idea behind RFC 8058 is to create a header that defines the provider-surfaced link within Gmail and Yahoo email clients. Note that even if you implement RFC 8058, the link may not always appear. Google and Yahoo will surface the link at their discretion.

what an RFC 8058 unsubscribe looks like rendered in an email your audience receives
what an RFC 8058 unsubscribe looks like rendered in an email your audience receives

Per the RFC 8058 documentation, your List-Unsubscribe-Post header:

  • Should contain a unique HTTPS URI POST.
  • Should point to an endpoint that is configured to receive the POST and process the unsubscribe for the recipient (within 48 hours).
  • The message must also have a valid DKIM signature that covers at least the List-Unsubscribe and List-Unsubscribe-Post headers.

For example, this email header:

List-Unsubscribe:
    <mailto:listrequest@example.com?subject=unsubscribe>,
    <https://example.com/unsubscribe.html?opaque=123456789>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Should result in this POST request:

Resulting POST request

   POST /unsubscribe.html?opaque=123456789 HTTP/1.1
   Host: example.com
   Content-Type: application/x-www-form-urlencoded
   Content-Length: 26
   List-Unsubscribe=One-Click

Step 2: Update the headers for every email in your workspace

You can add custom headers in our email editors, which you’ll now need to do. Learn more about adding custom headers in Customer.io.

what an RFC 8058 unsubscribe looks like in your custom headers
what an RFC 8058 unsubscribe looks like in your custom headers

FAQ

I use Customer.io’s built-in unsubscribe functionality, do I need to do anything?

Nope! We’ve already implemented RFC 8058 automatically for you, well before the deadline. You only need to follow the instructions on this page if your organization is using a custom unsubscribe solution.

What is “RFC ####”?

An RFC (Request for Comments) is a document that lets individuals and organizations propose standards, discuss protocols, and share information related to the development and operation of the internet. They come from the Internet Engineering Task Force (IETF) and the Internet Society (ISOC). RFCs cover a wide range of topics related to networking, communication, and the internet in general. Each RFC is assigned a unique number.

What are the different types of unsubscribes?

RFC 2369 (the previous industry standard)

  • Defines the use of URLs in email headers to convey core mail list commands, including subscribing and unsubscribing
  • Defines the “List-*” family of headers, such as “List-Unsubscribe”, “List-Subscribe”, etc

RFC 8058 (the new requirement)

  • Defines true one-click unsubscribe through an HTTPS URI POST that triggers an unsubscribe within 48 hours
  • Provides options for both email-based and web-based unsubscribe methods
Copied to clipboard!
  Contents
Is this page helpful?