Is quoted printable text allowed in the List-Unsubscribe header?
Michael Ko
Co-founder & CEO, Suped
Published 12 May 2025
Updated 16 Aug 2025
8 min read
The List-Unsubscribe header is a critical component for email deliverability and user experience, enabling recipients to opt out of mailing lists with ease. It's often presented as a prominent one-click unsubscribe option by major inbox providers like Gmail and Outlook. However, ensuring this header is correctly formatted is paramount, as any deviation from the specifications can lead to deliverability issues and a poor user experience.
One common question that arises is whether quoted-printable text is allowed within the List-Unsubscribe header. While quoted-printable is a valid Content-Transfer-Encoding for email bodies, its use in specific headers like List-Unsubscribe is generally not compliant with email standards and can lead to unexpected behavior.
Understanding why this is the case involves diving into the relevant RFCs (Requests for Comments) that define how email headers should be structured and encoded. Misconfigurations can result in unsubscribe links that simply don't work, leading to frustrated subscribers, increased spam complaints, and a negative impact on your sender reputation. Let's explore the nuances of this header and how to ensure its proper implementation.
Understanding List-Unsubscribe and header encoding
The List-Unsubscribe header was first specified in RFC 2369, providing a standard way for email clients to offer an unsubscribe option. More recently, RFC 8058 introduced the concept of one-click unsubscribe, simplifying the process further by allowing a single action to opt out. These RFCs dictate the structure and content of various email headers, including where and how different encoding methods can be applied.
Content-Transfer-Encoding, such as quoted-printable, is primarily used for the email body to safely transmit non-ASCII characters over systems that might not support them. RFC 2047 defines how encoded-words can be used in certain header fields to carry 8-bit characters. However, the List-Unsubscribe header is expected to contain URIs (Uniform Resource Identifiers) or mailto addresses, which have their own specific encoding rules (e.g., percent-encoding for special characters in URLs).
The issue arises when a List-Unsubscribe header itself is encoded using quoted-printable, as seen in some real-world examples. This is typically an incorrect application of RFC 2047, which does not permit such encoding for the structural elements of List-Unsubscribe. The URLs or mailto links within the header should be directly parseable, not requiring an additional layer of decoding specific to Content-Transfer-Encoding.
Why quoted-printable in List-Unsubscribe is problematic
Simply put, quoted-printable text is generally not allowed in the List-Unsubscribe header itself. While RFC 2047 allows encoded words in certain header fields (like Subject or Comments, or within the phrase part of an address), it does not extend to the structural components of the List-Unsubscribe header, which are expected to be URIs or mailto links.
When an ESP (Email Service Provider) or mail stream encodes the List-Unsubscribe header using quoted-printable, it creates a malformed header. While some recipient ISPs (like Hotmail) might attempt to decode it or might simply fail, others like Apple Mail often do not. This inconsistency means your unsubscribe link might not appear as intended or function correctly for all recipients, leading to a frustrating experience and potential deliverability issues.
The primary consequence of using quoted-printable in the List-Unsubscribe header is the risk of it not working at all for some recipients. This not only impairs the user experience but can also indirectly affect your sender reputation. When recipients cannot easily unsubscribe, they are more likely to mark your emails as spam, which can lead to your domain or IP address being added to a blacklist (or blocklist).
Non-compliant quoted-printable header
If your List-Unsubscribe header looks like this, it is likely not compliant with RFC 2047 and other related RFCs for the actual URI/mailto content.
Mail client parsing: Some clients, like Apple Mail, may fail to decode the header correctly, rendering the unsubscribe option unusable.
Increased spam complaints: If unsubscribing is difficult, recipients are more likely to mark emails as spam, which negatively impacts sender reputation.
Impact on deliverability and user experience
The primary goal of the List-Unsubscribe header is to provide an easy and reliable way for recipients to opt out of mail. When this header is malformed, it undermines this purpose. Recipients might see the raw quoted-printable string instead of a clickable link, leading to confusion and frustration. This poor user experience can directly translate to higher spam complaint rates, which inbox providers heavily penalize.
Major inbox providers like Yahoo and Gmail have recently reinforced the importance of valid List-Unsubscribe headers, especially for bulk senders. They require a one-click unsubscribe option via a HTTPS POST to be present. A quoted-printable encoded header could easily fail these checks, leading to emails being directed to the spam folder or even outright rejected. This would directly impact your sender reputation and overall email deliverability.
Compliant headers
Headers that follow RFC 2369 and RFC 8058 ensure proper functioning across all email clients and ISPs.
Functional unsubscribe: The unsubscribe link (whether mailto or HTTPS URL) is reliably parsed and displayed to the user.
Improved sender reputation: Lower spam complaints and better inbox placement due to ease of opting out.
Beyond technical compliance, a non-functional unsubscribe mechanism damages trust with your audience. When people feel trapped on a mailing list, it erodes their perception of your brand. This can lead to broader issues than just immediate deliverability, affecting customer loyalty and engagement in the long term. Adhering to standards not only ensures your emails reach the inbox but also fosters a positive relationship with your subscribers.
Best practices for List-Unsubscribe headers
To avoid issues, always ensure your List-Unsubscribe header contains unencoded URIs or mailto addresses. If non-ASCII characters are part of the URI, they should be percent-encoded as per RFC 3986, not quoted-printable. Most reputable ESPs handle this correctly by default.
It's good practice to review your email headers regularly to ensure compliance. You can inspect the raw source of an email received in your inbox to see the List-Unsubscribe header directly. Look for proper formatting, ensuring the URLs or mailto links are clear and not obscured by unexpected encoding like quoted-printable. If you detect issues, especially with MIME encoding, contact your ESP to resolve them. For detailed verification, you can use an email deliverability tester.
The simplest and most reliable way to provide a List-Unsubscribe header is to include both a mailto address and an HTTPS URL. The HTTPS URL is crucial for one-click unsubscribe functionality required by modern email providers. Both should be plain text or properly URI-encoded without quoted-printable or Base64 encoding applying to the entire List-Unsubscribe field value.
Views from the trenches
Best practices
Always use plain, unencoded URLs or mailto addresses in the List-Unsubscribe header.
Include both a mailto link and an HTTPS URL for maximum compatibility and one-click support.
Verify your List-Unsubscribe header's functionality across various email clients and ISPs.
Ensure any non-ASCII characters in the URL are percent-encoded, not quoted-printable.
Common pitfalls
Encoding the entire List-Unsubscribe header value with quoted-printable or Base64.
Relying solely on mailto links, which do not support modern one-click unsubscribe requirements.
Not regularly checking unsubscribe links, leading to broken functionality and user frustration.
Ignoring error reports related to malformed headers from mail servers.
Expert tips
Prioritize RFC compliance: Adhering to RFCs 2369, 8058, and 2047 is crucial for reliable email delivery.
Test thoroughly: Use an email testing tool to validate your email headers and unsubscribe links.
Monitor feedback loops: Pay attention to feedback from ISPs, as issues with unsubscribe headers can lead to increased spam complaints.
Automate where possible: Use an ESP that automatically handles correct List-Unsubscribe header generation.
Expert view
Expert from Email Geeks says a List-Unsubscribe header with quoted-printable encoding is generally not useful and is likely a badly formed header, working only by accident at some ISPs.
2021-09-17 - Email Geeks
Expert view
Expert from Email Geeks says RFC 2047 encoded words are only allowed in specific headers like Subject, Comments, or within the phrase before an email address, not in the List-Unsubscribe value itself.
2021-09-17 - Email Geeks
Final thoughts
While quoted-printable encoding has its place in email, particularly for message bodies, it is not appropriate for the List-Unsubscribe header itself. Adhering to the specifications outlined in RFC 2369 and RFC 8058 is crucial for ensuring that your unsubscribe links function reliably across all email clients and providers.
Proper implementation of the List-Unsubscribe header not only helps you meet compliance requirements from major inbox providers but also enhances your overall email deliverability and sender reputation. By providing a seamless unsubscribe experience, you build trust with your subscribers, reduce spam complaints, and ensure your legitimate emails consistently reach the inbox.
Gmail and 
Outlook. However, ensuring this header is correctly formatted is paramount, as any deviation from the specifications can lead to deliverability issues and a poor user experience.
ISPs (like 
Hotmail) might attempt to decode it or might simply fail, others like 
Apple Mail often do not. This inconsistency means your unsubscribe link might not appear as intended or function correctly for all recipients, leading to a frustrating experience and potential deliverability issues.
Yahoo and 
