// how to fix
Add a List-Unsubscribe header (one-click unsubscribe)
The List-Unsubscribe header lets Gmail, Yahoo and Outlook show an Unsubscribe button next to your sender name. Bulk senders must offer it in one click.
What it means
An email has hidden lines at the top, called headers. One of them, List-Unsubscribe, tells the mailbox how to unsubscribe the reader. Gmail, Yahoo, Outlook and Apple Mail then show an "Unsubscribe" button right next to your name.
"One-click" unsubscribe (defined by the standard RFC 8058) adds a second header, List-Unsubscribe-Post. With it, the mailbox can unsubscribe the person directly, without opening a web page.
Why it matters
- Gmail and Yahoo require one-click unsubscribe for bulk senders' marketing emails.
- A reader who wants to stop and finds an easy button uses it. A reader who cannot find one clicks "Report spam", which damages your reputation.
- It is not needed for transactional emails such as invoices, password resets or order confirmations.
How to check
- Send a test email: on the home page, copy your unique test address, send it a normal email from the mailbox or tool you want to check, then open the report. Open the "Raw headers" section and look for
List-UnsubscribeandList-Unsubscribe-Post.
How to fix it
With a newsletter tool
Most newsletter and marketing tools add both headers automatically. If they are missing:
- Look for an option called "one-click unsubscribe" or "List-Unsubscribe" in the tool's settings.
- Make sure your emails are sent as marketing or newsletter campaigns, not as plain one-to-one emails.
- Set up domain authentication (DKIM with your own domain): the headers must be covered by the DKIM signature to count.
With your own sending code
Add these two headers to every marketing email:
List-Unsubscribe: <https://yourdomain.com/unsubscribe?u=abc123>, <mailto:unsubscribe@yourdomain.com?subject=unsubscribe> List-Unsubscribe-Post: List-Unsubscribe=One-Click
- The
httpslink must be unique for each reader, so you know who to remove. - When the mailbox sends a POST request to that link with the body
List-Unsubscribe=One-Click, your site must unsubscribe the person immediately, with no login and no confirmation page. - The
mailtoaddress is a fallback for older mailboxes. - Sign the email with DKIM including these headers.
Good habits
- Process requests within two days at most.
- Keep a visible unsubscribe link in the email body as well.
- Never send an "Are you sure?" email after an unsubscribe.
- Remove unsubscribed people from every list and every tool, not only the one they clicked in.
Check that it is fixed
Send a new test email from the home page using your marketing tool, and check the raw headers in the report. Then send one to a Gmail address: after a few emails, Gmail should show the Unsubscribe link next to your name. Gmail does not always show it for new senders.
The standard: RFC 8058, one-click unsubscribe.
Check that it is fixed
DNS changes can take from a few minutes to a few hours. Then send a new test email or scan your domain again.
Related guides
- High SpamAssassin spam scoreSpamAssassin scores the content of your email. Above 5, it is treated as spam. Learn what raises the score and how to bring it down.
- Gmail and Yahoo bulk sender requirementsSince 2024, Gmail and Yahoo require large senders to authenticate their emails, offer one-click unsubscribe and keep spam complaints very low. Here is the checklist.
- Your emails land in Gmail's spam folderWhen Gmail sends your emails to spam, the cause is almost always authentication, reputation or content. Here is how to find which one and fix it.
- Gmail bounce "550 5.7.26": unauthenticated emailGmail refused your email because it could not confirm it comes from your domain. SPF, DKIM or DMARC is missing or failing. Here is how to fix it.
- Invalid HELO/EHLO hostnameYour server introduces itself with a name that is not valid, such as localhost or a bare IP. Spam filters distrust this. Give it a real name that matches reverse DNS.