What are the Gmail sender requirements for one-click unsubscribe, and where should the links be placed?
Matthew Whittaker
Co-founder & CTO, Suped
Published 30 Jun 2025
Updated 18 Aug 2025
7 min read
Understanding the nuances of Gmail's one-click unsubscribe requirements can feel complex, especially with the recent updates. I often see questions about whether a single unsubscribe mechanism is enough, or if both header-based and in-body links are necessary. The key is to distinguish between the different types of unsubscribe functionalities and their purposes.
Effective early 2024, Gmail (and Yahoo) introduced stricter guidelines for bulk senders, defined as those sending 5,000 or more messages per day to Gmail recipients. These changes aim to enhance user experience and reduce unwanted emails. A core part of these requirements is the implementation of a true one-click unsubscribe option. This doesn't replace the traditional unsubscribe link you place in the email body, but rather complements it.
The two types of unsubscribe links
The distinction between header-based one-click unsubscribe and a body link is crucial. The header-based mechanism is largely invisible to the recipient unless their mail client (like Gmail's web interface or mobile app) chooses to render an unsubscribe button at the top of the email. This functionality is enabled by specific email headers, primarily the List-Unsubscribe header, as defined by RFC 8058.
Conversely, the unsubscribe link in the email body is the traditional method we are all familiar with. This link is typically placed in the footer and leads recipients to a preference center or a confirmation page. While it might still be called one-click unsubscribe by some, the new Gmail and Yahoo requirements specify a truly single-action unsubscribe initiated directly by the mail client.
Both methods serve the same ultimate goal, allowing recipients to opt out, but they function differently and are both required for bulk senders. Adhering to both ensures compliance with the latest standards and improves recipient experience, which in turn benefits your email deliverability.
One-click (header-based)
Location: Implemented in the email headers, invisible to the user until rendered by the mail client.
Mechanism: Uses List-Unsubscribe and List-Unsubscribe-Post headers, typically triggering an HTTP POST request.
User experience: A single click on a button (often next to the sender name) instantly unsubscribes the user without needing to visit a page.
Manual: Requires the user to click a link, typically navigate to a page.
Visible: The link is clearly visible within the email content.
Legal compliance: Required by regulations like CAN-SPAM for all commercial emails.
Implementing the List-Unsubscribe header
To implement the header-based one-click unsubscribe, you need to include two specific headers in your outgoing marketing and subscribed emails: List-Unsubscribe and List-Unsubscribe-Post. The List-Unsubscribe header should contain at least one URL, preferably an HTTPS URL, that can process an unsubscribe request directly via a GET request. The List-Unsubscribe-Post header should be set to List-Unsubscribe=One-Click.
When a recipient clicks the unsubscribe button presented by the email client (like Gmail), the client will automatically trigger an HTTP POST request to the URL specified in your List-Unsubscribe header. This request should immediately unsubscribe the user without requiring any further clicks or confirmation pages. It's essential that your system processes these requests within two days to remain compliant and avoid deliverability issues.
Most reputable Email Service Providers (ESPs) have already implemented this functionality to ensure their clients remain compliant. If you use an ESP, it's highly probable that your emails are already configured with the correct List-Unsubscribe headers. You can verify this by checking your email headers or consulting your ESP's documentation.
While the header-based one-click unsubscribe is crucial for compliance with new requirements, you should still include a clearly visible unsubscribe link within the body of your emails. This is a longstanding best practice and a requirement under various anti-spam laws, such as CAN-SPAM in the United States. The most common and recommended placement for this link is in the email footer.
This in-body link typically directs recipients to a preference center or a dedicated unsubscribe landing page. On this page, users should have a straightforward option to unsubscribe from all communications or manage their subscription preferences. It doesn't necessarily need to be a single-click action from the page itself, unlike the header-based method. The key is that the process is clear and intuitive.
Having both the header-based and in-body unsubscribe options caters to different user behaviors and ensures maximum accessibility for recipients wanting to opt out. Some users might prefer the prominent button displayed by their mail client, while others will instinctively look for a link in the footer. Providing both pathways helps maintain a positive subscriber experience and prevents recipients from marking your emails as spam due to difficulty unsubscribing. You can find more details on optimal unsubscribe link placement.
Why compliance matters
Compliance with Gmail's (and Yahoo's) one-click unsubscribe requirements is not merely a technicality, it's fundamental to maintaining good email deliverability and sender reputation. Failure to adhere can lead to significant consequences, including your emails being routed to the spam folder, or even being blocked entirely by major mailbox providers. This impacts your ability to reach your audience and can severely damage your brand's communication efforts.
When recipients find it difficult to unsubscribe, they are more likely to mark your emails as spam. High spam complaint rates signal to mailbox providers that your emails are unwanted, leading to lower sender scores and potential inclusion on blocklists (or blacklists). Being listed on a prominent blacklist (or blocklist) can result in widespread delivery issues across multiple providers, not just Gmail and Yahoo.
Proactive management of unsubscribe options and adherence to these requirements are critical components of a healthy email program. Regularly monitoring your deliverability metrics and ensuring your unsubscribe processes are functioning correctly will help you avoid deliverability pitfalls and maintain a positive relationship with mailbox providers and your subscribers. For more on this, consider learning about how email providers distinguish different email types.
Requirement
Details
Impact of non-compliance
List-Unsubscribe Header (RFC 8058)
Include List-Unsubscribe and List-Unsubscribe-Post in all marketing/subscribed emails. Must support single POST request.
Clear and easy-to-find link in email body, usually in the footer.
Legal non-compliance (e.g., CAN-SPAM fines). User frustration.
Views from the trenches
Best practices
Ensure your ESP automatically adds the List-Unsubscribe headers to bulk marketing emails.
Test your unsubscribe process regularly by sending a test email to a Gmail account and verifying the one-click option.
Monitor your spam complaint rates in Google Postmaster Tools to identify potential issues.
Common pitfalls
Only relying on an in-body link, neglecting the mandatory header-based one-click unsubscribe.
Sending emails without proper SPF, DKIM, and DMARC authentication, which is also required.
Not processing unsubscribe requests within the strict two-day window.
Expert tips
Regularly check your domain's health and blacklists (or blocklists) using monitoring tools.
Educate your marketing team on these new requirements to ensure all campaigns are compliant.
Implement a feedback loop service to receive spam complaints directly from mailbox providers.
Expert view
Expert from Email Geeks says the one-click functionality is primarily a header-based feature, which allows the mailbox provider to display an unsubscribe button that links to a backend call they will make.
2024-01-30 - Email Geeks
Expert view
Expert from Email Geeks says there should be an in-body link, typically in the footer, leading to a subscription center, and separately, invisible support in the email headers for the one-click unsubscribe using RFC 8058.
2024-01-30 - Email Geeks
Ensuring ongoing compliance
Navigating Gmail's sender requirements, particularly for one-click unsubscribe, involves understanding both the technical implementation of email headers and the user experience of in-body links. Both are essential for bulk senders to ensure emails reach the inbox rather than the spam folder. Implementing the List-Unsubscribe and List-Unsubscribe-Post headers correctly enables the true one-click functionality that Gmail and Yahoo now mandate, leading to instant unsubscriptions without further steps.
Alongside this, maintaining a visible and easy-to-use unsubscribe link in the email body, typically in the footer, remains a critical best practice and legal requirement. By satisfying both the header-based and in-body unsubscribe requirements, you not only comply with the latest industry standards but also foster trust with your subscribers, improve email deliverability, and protect your sender reputation from being blocklisted (or blacklisted).
Gmail), the client will automatically trigger an HTTP POST request to the URL specified in your List-Unsubscribe header. This request should immediately unsubscribe the user without requiring any further clicks or confirmation pages. It's essential that your system processes these requests within two days to remain compliant and avoid deliverability issues.
