How do I add an unsubscribe button to the email header and what is RFC 8058?

Summary

Implementing an unsubscribe button in the email header, governed by RFC 8058, is essential for email deliverability, CAN-SPAM compliance, and maintaining a good sender reputation. Most ESPs handle this functionality. The List-Unsubscribe header, included in the email headers with both mailto: and HTTP/HTTPS URLs, allows recipients to unsubscribe directly from their email client. Google and Yahoo now mandate one-click unsubscribe functionality and will penalize emails that don't make unsubscribing easy. Gmail only shows the unsubscribe button for 'good' senders based on their sending history. Unsubscribe requests should be processed promptly, and both mailto and URL options in the header must function correctly.

Key findings

  • RFC 8058 Definition: RFC 8058 defines the standards for one-click unsubscribe functionality using the List-Unsubscribe header.
  • ESP Handling: ESPs generally handle the implementation of unsubscribe functionality.
  • List-Unsubscribe Header: The List-Unsubscribe header allows recipients to unsubscribe directly from their email client.
  • Mandatory One-Click Unsubscribe: Yahoo and Google now mandate one-click unsubscribe functionality.
  • Sender Reputation Impact: Gmail displays the unsubscribe button based on the sender's reputation (volume, complaints, domain history).

Key considerations

  • Header Implementation: Include both mailto: and HTTP/HTTPS URLs in the List-Unsubscribe header for maximum compatibility.
  • Timely Processing: Unsubscribe requests should be processed promptly to maintain a good sender reputation and comply with regulations.
  • Functionality Testing: Ensure both mailto and URL unsubscribe options function correctly.
  • Compliance: Adhere to CAN-SPAM and other regulations when implementing unsubscribe options.
  • Deliverability: Implement one-click unsubscribe to improve email deliverability and avoid penalties from major providers.

What email marketers say
10Marketer opinions

Adding an unsubscribe button to the email header, as governed by RFC 8058, is crucial for email deliverability and compliance with regulations like CAN-SPAM. ESPs often handle this functionality, and including a List-Unsubscribe header enables recipients to unsubscribe directly from their email client. Best practices include providing both mailto: and HTTP/HTTPS options in the header for maximum compatibility and ensuring unsubscribe requests are processed promptly. Major email providers are now prioritizing one-click unsubscribe, so it is essential to implement this.

Key opinions

  • RFC 8058: RFC 8058 defines the standards for one-click unsubscribe functionality.
  • List-Unsubscribe Header: Adding a List-Unsubscribe header allows recipients to unsubscribe directly from their email client.
  • ESP Handling: Most ESPs should handle the implementation of single unsubscribe options.
  • CAN-SPAM Compliance: Adding an unsubscribe link in the header is crucial for CAN-SPAM compliance and maintaining a healthy sender reputation.
  • One-Click Unsubscribe: Major email providers prioritize one-click unsubscribe.

Key considerations

  • Header Implementation: The List-Unsubscribe header should include both mailto: and HTTP/HTTPS URLs for maximum compatibility.
  • Prompt Processing: Ensure unsubscribe requests are processed promptly to maintain a good sender reputation.
  • Compliance: Be mindful of compliance with regulations like CAN-SPAM when implementing unsubscribe options.
  • Sender Reputation: Providing a clear and easy unsubscribe process is essential for maintaining a good sender reputation.
  • Email Deliverability: Making it easy to unsubscribe is better since the big providers want to see it, and will start to penalize emails that don't make it easy for the recipient to unsubscribe.
Marketer view

Email marketer from Campaign Monitor shares that adding a List-Unsubscribe header allows recipients to unsubscribe directly from their email client (like Gmail or Outlook) without opening the email. He also says it increases deliverability and reduces spam complaints.

February 2022 - Campaign Monitor
Marketer view

Email marketer from Email on Acid recommends including both a mailto: and an HTTP/HTTPS URL in your List-Unsubscribe header for maximum compatibility. The mailto: option allows for one-click unsubscribe, while the HTTP/HTTPS provides a fallback for email clients that don't support mailto.

September 2021 - Email on Acid
Marketer view

Marketer from Email Geeks confirms that the unsubscribe button on the email header refers to RFC 8058.

April 2024 - Email Geeks
Marketer view

Email marketer from Sendinblue shares that adding an unsubscribe link in the email header is crucial for CAN-SPAM compliance and maintaining a healthy sender reputation. It also enhances user experience by providing an easy way to opt-out.

September 2023 - Sendinblue
Marketer view

Email marketer from Gmass shares that it's better to always use one-click unsubscribe since the big providers want to see it, and will start to penalize emails that don't make it easy for the recipient to unsubscribe.

September 2022 - Gmass
Marketer view

Email marketer from Mailjet explains one-click unsubscribe allows recipients to unsubscribe directly from the email header, and that RFC 8058 defines standards for this functionality.

April 2023 - Mailjet
Marketer view

Email marketer from Litmus explains that providing a clear and easy unsubscribe process, including visible unsubscribe links and honoring unsubscribe requests promptly, is essential for maintaining a good sender reputation and complying with regulations.

December 2024 - Litmus
Marketer view

Email marketer from Stackoverflow explains the List-Unsubscribe header is added in the headers like: 'List-Unsubscribe: <mailto:list@example.com?subject=unsubscribe>, <http://example.com/unsubscribe.html>'. This allows mail clients to provide an unsubscribe button.

October 2024 - Stackoverflow
Marketer view

Email marketer from Reddit shares that one way to implement one-click unsubscribe is using a mailto link in the List-Unsubscribe header, pointing to an address that automatically processes unsubscribe requests. This is useful, but ensure you properly process the requests.

July 2024 - Reddit
Marketer view

Marketer from Email Geeks shares that your ESP should handle the single unsubscribe option in the header.

October 2024 - Email Geeks

What the experts say
3Expert opinions

Implementing an unsubscribe button in the email header involves technical considerations and adherence to industry best practices. Gmail displays the unsubscribe option only for 'good' senders. It's crucial to implement both mailto and URL options for the List-Unsubscribe header. Finally, new requirements from Yahoo and Google mandate one-click unsubscribe functionality for successful email delivery.

Key opinions

  • Sender Reputation: Gmail only shows the unsubscribe button for senders with a good reputation based on volume, complaints, and domain history.
  • Dual Options: Implementing both mailto and URL options in the List-Unsubscribe header is considered a best practice.
  • Mandatory One-Click: New Yahoo and Google requirements mandate one-click unsubscribe functionality.

Key considerations

  • Functionality Testing: Ensure both mailto and URL unsubscribe methods function correctly and promptly.
  • Reputation Monitoring: Continuously monitor your sender reputation to ensure the unsubscribe option is visible in Gmail.
  • Rule Adherence: Adhering to Yahoo and Google's new guidelines is crucial for ensuring successful email delivery.
Expert view

Expert from Word to the Wise answers the question about the new Yahoo and Google requirements by explaining that senders need to implement one-click unsubscribe functionality in their emails as mandated by the new rules. It is crucial to adhere to these guidelines to ensure successful email delivery.

June 2021 - Word to the Wise
Expert view

Expert from Spam Resource explains that implementing both mailto and URL options for the List-Unsubscribe header is a best practice. Ensure that both methods function correctly and promptly.

March 2022 - Spam Resource
Expert view

Expert from Email Geeks explains Gmail only shows this for 'good' senders, based on volume, complaints, and domain history. He advises to check and support the functionality, but don't be surprised if it doesn't always show up.

March 2021 - Email Geeks

What the documentation says
3Technical articles

RFC 8058 defines a standardized method for one-click unsubscription using the List-Unsubscribe header field and mailto: URI scheme. Google recommends including this header in emails with both mailto: and https: URLs. Microsoft mandates bulk senders support one-click unsubscribe with a List-Unsubscribe header and a visible unsubscribe link, processing requests within two days for immediate removal.

Key findings

  • RFC 8058 Standard: RFC 8058 standardizes one-click unsubscription via the List-Unsubscribe header and mailto: URI.
  • Google Recommendation: Google recommends including the List-Unsubscribe header with both mailto: and https: URLs.
  • Microsoft Mandate: Microsoft mandates one-click unsubscribe for bulk senders with a List-Unsubscribe header, a visible unsubscribe link, and two-day processing.

Key considerations

  • Dual URL Support: Implement both mailto: and https: URLs in the List-Unsubscribe header for broader compatibility.
  • Bulk Sender Requirements: Bulk senders must adhere to Microsoft's mandate for one-click unsubscribe, a visible unsubscribe link, and timely processing.
  • Processing Time: Ensure unsubscribe requests are processed within two days for immediate subscriber removal, as required by Microsoft.
Technical article

Documentation from ietf.org explains RFC 8058 defines a standardized method for one-click unsubscription from email mailing lists using the List-Unsubscribe header field with the mailto: URI scheme.

November 2022 - ietf.org
Technical article

Documentation from Microsoft explains that bulk senders must support one-click unsubscribe. Including both a visible unsubscribe link in the message body and a List-Unsubscribe header. Senders must process unsubscribe requests within two days and the one-click unsubscribe must remove the subscriber immediately.

August 2024 - Microsoft
Technical article

Documentation from Google Workspace Admin Help explains you should include a List-Unsubscribe header in your emails so that users can easily unsubscribe from your mailing list. The article also notes to specify a mailto: or https: URL, and use both for best results.

January 2025 - Google Workspace Admin Help