When a Gmail user opens your email, they sometimes see an “Unsubscribe” link right next to your sender name before they even scroll. That link is not generated by your ESP’s email template. It comes from a technical header embedded in the email itself.
That header is the List-Unsubscribe header. And since February 2024, Google and Yahoo have required it for all bulk senders. Two years later, a significant number of email programmes still have it configured incorrectly.
What the List-Unsubscribe Header Does
The List-Unsubscribe header is a technical instruction in your email’s headers not visible in the email body, but read by email clients and inbox providers.
When correctly configured, it tells Gmail to display a one-click “Unsubscribe” option next to your sender name in the inbox. Users can click it without opening the email. Gmail handles the unsubscribe process on their behalf.
This matters for two reasons. First, it gives disengaged subscribers an easy way to leave your list without opening the email. Second, it directly reduces your spam complaint rate. When unsubscribing is easier than reporting spam, most people choose to unsubscribe.
Why Spam Reports Are More Damaging Than Unsubscribes
A spam report tells Gmail: “This sender’s email is unwanted.” Gmail records this against your domain reputation. Enough spam reports push your domain from High reputation to Medium, then to Low.
An unsubscribe tells Gmail nothing negative about your domain. The person simply leaves your list. Your reputation is unaffected.
When disengaged subscribers report spam instead of unsubscribing because unsubscribing requires too many steps, every one of those reports damages your reputation. The List-Unsubscribe header converts potential spam reports into clean unsubscribes. This is why it has a measurable positive effect on deliverability for programmes that implement it correctly.
The Difference Between List-Unsubscribe and List-Unsubscribe-Post
This is the most commonly confused aspect of this topic. There are two different headers involved, and both are required for full compliance.
List-Unsubscribe is the original header. It has existed for years, and most ESPs have been adding it to sends for a long time. It contains either a mailto: link or an https: link that the email client can use to process the unsubscribe.
List-Unsubscribe-Post is the newer requirement introduced with RFC 8058. This header tells the email client that the URL in the List-Unsubscribe header can handle a POST request,t meaning Gmail can process the unsubscribe on the user’s behalf with a single click, without requiring the user to visit any external page.
This is what makes it “one-click.” Without the List-Unsubscribe-Post header, the older behavior applies: the user clicks the unsubscribe link, visits an external page, and may need to take additional steps to confirm.
Both headers are required. Having only the List-Unsubscribe header without the Post variant means the in-Gmail one-click unsubscribe button does not appear. This is the most common implementation gap.
Why This Header Directly Protects Your Sender Reputation
The connection between the List-Unsubscribe header and sender reputation operates through one mechanism: spam complaint rate.
Consider what happens when a subscriber who has not engaged with your emails in six months receives another campaign. They have three choices:
Option 1: They open the email and scroll to the bottom. Then, they find the unsubscribe link, click it, confirm on an external page, and wait for the request to process.
Option 2: They click “Report Spam” in Gmail. As a result, the request takes one click, and the option is always visible.
Option 3: They see the “Unsubscribe” link next to your sender name. After that, they click it and are done in one step without even opening the email.
Without the List-Unsubscribe-Post header, Option 3 does not exist. Many disengaged users choose Option 2. Each of those choices is a spam report against your domain.
With the header correctly implemented, Option 3 is available. A meaningful percentage of people who would have reported spam instead choose the frictionless unsubscribe. Your spam complaint rate decreases. Your domain reputation improves.
Research from major ESPs consistently shows that programmes implementing one-click unsubscribe see spam complaint rate reductions of 15 to 35%.
What Google and Yahoo Actually Require
In February 2024, Google and Yahoo updated their bulk sender requirements. For anyone sending more than 5,000 emails per day to Gmail addresses, these requirements apply:
First, you must have SPF or DKIM authentication (both preferred). Second, you must have a DMARC record. Third, your spam rate must stay below 0.10% in Postmaster Tools. Fourth, you must implement one-click unsubscribe via the List-Unsubscribe and List-Unsubscribe-Post headers.
The unsubscribe requirement also mandates that you process unsubscribe requests within 2 business days. The header alone is not enough. When a user clicks the unsubscribe link either via the header or the body link, the suppression must happen within 48 business hours.
If you are sending to Yahoo addresses, the same requirements apply. Yahoo’s enforcement is similar to Gmail’s, though the Postmaster-level visibility is less detailed.
How to Check if Your Header Is Configured Correctly
This check takes two minutes.
Send a test email from your normal campaign workflow to a personal Gmail address you control.
Open the email in Gmail. Look next to your sender name at the top of the email. If you see a small “Unsubscribe” link not in the email body, but in the header row next to the sender name, then the one-click header is working.
For a technical verification, click the three dots in the top-right corner of the email and select “Show original.” In the raw header view, search for “List-Unsubscribe.” You should see two entries:
- `List-Unsubscribe: <https://yourunsubscribeurl.com/…>`
- `List-Unsubscribe-Post: List-Unsubscribe=One-Click`
If you see only the first line and not the second, the Post header is missing. The in-Gmail button will not appear.
If you see neither line, your List-Unsubscribe header is not configured at all. This is a critical gap.
Implementation by Major ESP
Most major ESPs now support one-click unsubscribe. However, the default configuration varies, and some require manual activation.
Klaviyo
Klaviyo adds both List-Unsubscribe headers automatically to email sends by default. Verify by sending a test email and checking the headers using the method above. If the Post header is missing, check your account’s email settings under “Compliance.”
Mailchimp
Mailchimp adds the List-Unsubscribe header automatically. The List-Unsubscribe-Post header was added as part of Mailchimp’s 2024 compliance updates. For accounts on older plan structures, check Mailchimp’s documentation to confirm the Post header is active for your account.
HubSpot
HubSpot adds both headers automatically to marketing email sends. Confirm by viewing the original headers of a test send.
SendGrid
SendGrid supports the headers through its subscription tracking settings. Enable subscription tracking in your SendGrid account settings. Confirm the unsubscribe URL is configured to handle POST requests via SendGrid’s hosted unsubscribe page or a custom webhook endpoint.
Custom Infrastructure
If you send email through custom infrastructure or a less common ESP, you must add these headers manually. The List-Unsubscribe header should contain an HTTPS URL pointing to your unsubscribe endpoint. The List-Unsubscribe-Post header must contain exactly `List-Unsubscribe=One-Click`. Your endpoint must accept POST requests and process the unsubscribe without requiring additional user action.
Common Mistakes and How to Fix Them
Mistake 1: Having List-Unsubscribe but not List-Unsubscribe-Post.
This is the most common gap. The List-Unsubscribe header enables click-through unsubscribes via the old method. Without the Post variant, the Gmail interface one-click button does not appear. Fix: enable the POST header in your ESP’s settings or add it manually if using custom infrastructure.
Mistake 2: The POST header URL requires login or confirmation.
When Gmail sends a POST request to your unsubscribe URL, the request must process the unsubscribe immediately without requiring the user to log in, enter their email address, or click a confirmation button. If your unsubscribe endpoint requires any of these additional steps, it is not one-click compliant. Fix: update your unsubscribe endpoint to process POST requests immediately and return a 200 response.
Mistake 3: Processing delays beyond 2 business days.
Sending the unsubscribe signal to a manual review queue that processes weekly is not compliant. Fix: automate the suppression process so that a POST request to your unsubscribe endpoint immediately updates the contact’s status in your ESP and CRM.
Mistake 4: Not syncing unsubscribes back to the CRM.
The header processes the unsubscribe in your ESP. If your CRM is not updated, the contact re-enters the active send list on the next CRM export. Fix: ensure your ESP-to-CRM unsubscribe sync is automated and running within 24 hours.
Mistake 5: Applying the header to transactional email.
The List-Unsubscribe header is for commercial and marketing email. Transactional emails order confirmations, password resets, billing alerts should not include it. Adding it to transactional email risks the unsubscribe being applied to essential communications the recipient needs.
Key Takeaways
- The List-Unsubscribe header enables Gmail to show a one-click “Unsubscribe” option next to your sender name. The List-Unsubscribe-Post header is what makes it truly one-click. Both are required.
- Google and Yahoo have required one-click unsubscribe for bulk senders since February 2024. Not having it puts you out of compliance with their sender requirements.
- The business case for this header is a direct reduction in spam complaint rate. Disengaged users who cannot easily unsubscribe choose “Report Spam” instead. Every spam report damages domain reputation.
- Check your implementation by sending a test email to Gmail and viewing the original headers. Look for both List-Unsubscribe and List-Unsubscribe-Post.
- Most major ESPs (Klaviyo, HubSpot) add both headers automatically. Others (SendGrid) require specific configuration. Custom infrastructure requires manual header addition.
- Unsubscribe requests must be processed within 2 business days. Automating the suppression process; manual review queues do not meet this requirement.
Frequently Asked Questions
Possibly, but that can be positive. It gives disengaged subscribers an easy way to leave, reducing future spam complaints and improving list quality.
It can. For high-volume commercial cold email, adding the header is good practice, even if your sequencing tool does not add it automatically.
The header enables the email client’s unsubscribe option, while the body link provides a visible unsubscribe option inside the email. Ideally, use both.
A link can be used with the older List-Unsubscribe method. However, one-click unsubscribe requires an HTTPS endpoint that can process the request.
Not necessarily. Requirements depend on the type and volume of email you send. For bulk marketing email, however, implementing List-Unsubscribe and one-click unsubscribe is a strong deliverability practice.
Conclusion
The List-Unsubscribe header is small technical infrastructure with outsized impact on sender reputation. Programmes that implement it correctly see measurable reductions in spam complaint rates. Those reductions translate directly into improved domain reputation and inbox placement.
The implementation check takes two minutes. The fix, if needed, takes a few hours at most. Given that Google and Yahoo now require it and the compliance risk of not having it is real, there is no good reason to delay.
Check your headers this week. Fix any gaps before your next campaign. Then monitor your complaint rate in Postmaster Tools over the following two to four weeks to see the effect.
