How do I add an unsubscribe button to the email header and what is RFC 8058?
Michael Ko
Co-founder & CEO, Suped
Published 22 Apr 2025
Updated 25 May 2026
8 min read
Summarize with
You do not add the unsubscribe button itself. You add the right message headers, make the unsubscribe URL handle an RFC 8058 POST request, and sign those headers with DKIM. Gmail, Yahoo, Apple Mail, and other mailbox interfaces decide whether to show the button next to the sender name.
For Gmail and Yahoo bulk sender compliance, the relevant mechanism is header-based one-click unsubscribe. In practice, that means List-Unsubscribe plus List-Unsubscribe-Post, not a visible HTML button in the top of your email template.
- Button source: The mailbox provider reads the raw email headers and renders its own unsubscribe control.
- Header pair: The message needs an HTTPS unsubscribe URL and the one-click POST signal.
- Receiver action: The mailbox provider sends a POST request to your endpoint after the user chooses unsubscribe.
- Visibility limit: Correct headers help, but reputation, volume, complaints, and eligibility checks still affect display.
The date confusion matters. The wider Gmail and Yahoo sender requirements began in February 2024, but Google's documented grace period for senders that already had unsubscribe links ran until June 1, 2024 for one-click unsubscribe on commercial and promotional mail. As of May 25, 2026, treat this as an active requirement for bulk promotional mail, not a future project.
What RFC 8058 requires
The technical standard is RFC 8058. It describes a way for list email to signal that an unsubscribe URL supports a one-click action. The important detail is that the user does not browse to your unsubscribe page. The mailbox provider sends an HTTPS POST to your URL with a fixed body.
|
|
|
|---|---|---|
List header | One HTTPS URL | Identifies list and recipient |
POST header | One fixed value | Signals one-click support |
DKIM | Headers signed | Prevents header tampering |
Endpoint | No extra step | Completes unsubscribe |
Core RFC 8058 requirements for senders.
Header exampletext
List-Unsubscribe: <mailto:unsubscribe@example.com>, <https://example.com/u/7f3b2c9a> List-Unsubscribe-Post: List-Unsubscribe=One-Click
That example has two unsubscribe options in List-Unsubscribe: a mailto address and an HTTPS URL. For RFC 8058, the HTTPS URL is the important part. The mailto option is useful for older clients, but it does not satisfy Gmail's one-click requirement by itself.
DKIM is part of the requirement
RFC 8058 expects at least one valid DKIM signature to cover both unsubscribe headers. If the final message changes after signing, the mailbox provider has a strong reason to hide the one-click option. A DKIM checker helps confirm the signature and selector are working before you blame the inbox interface.
How to add the header button
If you use an ESP, the ESP should usually handle this because it controls final header injection, DKIM signing, and unsubscribe processing. Ask for RFC 8058 support, not just a normal unsubscribe link. If you run your own sending system, you need to add the headers and build the endpoint yourself.
Flowchart showing a signed email header leading to an RFC 8058 POST unsubscribe.
- Classify mail: Apply the headers to commercial, promotional, and subscribed list mail.
- Create tokens: Use opaque, hard-to-forge identifiers that map to the recipient and list.
- Add headers: Include the HTTPS URL and the exact one-click POST signal in each outgoing message.
- Accept POST: Process the mailbox provider's POST without cookies, login, a captcha, or a confirmation page.
- Sign headers: Make sure the active DKIM signature covers both unsubscribe headers in the final message.
- Keep footer: Keep a visible unsubscribe link in the message body for users and legal requirements.
POST request your endpoint must handlehttp
POST /u/7f3b2c9a HTTP/1.1 Host: example.com Content-Type: application/x-www-form-urlencoded Content-Length: 26 List-Unsubscribe=One-Click
ESP-managed sending
This is the cleanest path when your ESP owns templates, suppression lists, and final message signing.
- Ask directly: Request RFC 8058 support for all marketing and subscribed message streams.
- Verify raw mail: Check the final delivered headers, not only the template preview.
- Check suppression: Confirm the endpoint removes the recipient from the right list.
Self-managed sending
This works when your engineering team controls SMTP, header assembly, DKIM signing, and unsubscribe state.
- Build endpoint: Accept a POST with the fixed one-click body and return a success response.
- Avoid redirects: Handle the request at the URL in the header without redirecting POST to GET.
- Audit DKIM: Confirm the h= tag includes both unsubscribe header fields.
What users see in the inbox
In Gmail, the visible control often appears near the sender name or in the message menu. Yahoo has its own interface treatment. The exact placement is not controlled by your HTML. Your job is to provide a valid, signed signal that the receiving system can trust.
Gmail message view showing an unsubscribe control near the sender name.
The button still does not appear for every sender or every test message. Gmail says top-of-message unsubscribe controls are shown only after automated eligibility checks. That means a technically correct implementation can stay hidden if the sender has low volume, weak history, complaint issues, or inconsistent authentication. The deeper explanation is covered in Gmail button visibility.
Complaint rate pressure
Lower complaint rates make it easier for mailbox providers to trust sender controls.
Healthy
Under 0.10%
Keep complaint rate well under the published concern zone.
Watch
0.10-0.30%
Review list quality, targeting, and unsubscribe access.
Risk
Over 0.30%
Expect more filtering pressure and weaker eligibility.
Do not use visibility as your only test
A missing Gmail button does not prove the headers are wrong. First inspect the raw delivered message, confirm DKIM coverage, and test the endpoint. After that, review sender reputation and complaint rate.
Common reasons it fails
Most broken implementations fail in one of two places: the header signal is incomplete, or the unsubscribe endpoint behaves like a normal web page. RFC 8058 expects the receiving system to complete the unsubscribe without a person landing on your site.
|
|
|
|---|---|---|
No header | ESP not adding it | Enable list headers |
No button | Eligibility check | Review reputation |
POST ignored | Web flow only | Process one-click |
DKIM fail | Header changed | Sign after changes |
Wrong list | Token too broad | Use list tokens |
Fast checks when one-click unsubscribe does not work.
A common mistake is treating a normal unsubscribe page as one-click. A preference center is fine as an extra footer link, but it is not the RFC 8058 action. If the mailbox provider sends the POST, your system must mark the recipient unsubscribed without asking for a password, reason, confirmation, or second click. For policy context, see the one-click requirements.
Do not unsubscribe on GET
Security scanners and spam filters fetch URLs. If a GET request unsubscribes the user, automated link scanning can remove real subscribers by accident. Use GET for a landing page or preference center. Use the RFC 8058 POST for one-click unsubscribe.
How I test the setup
I test this with the same sending path that real subscribers receive. A staging template through a different sender, a different DKIM selector, or a different suppression system proves less than people think. The delivered message is the source of truth.
Email tester sample report showing total score, email preview, issue summary, and per-section results
A practical test starts with a delivered message and its raw headers. Suped's product helps here because it ties email testing to the same authentication checks teams already need for DMARC, DKIM, SPF, and reputation. For most teams, Suped's product is the strongest overall DMARC platform because it connects monitoring, alerts, hosted SPF, hosted MTA-STS, SPF flattening, blocklist (blacklist) monitoring, and issue-specific fix steps in one workflow.
Send a real campaign sample to an email tester, then confirm the unsubscribe headers, DKIM result, and endpoint behavior. A domain health check catches related authentication problems, while DMARC monitoring shows whether real traffic is passing authentication over time.
- Raw headers: Confirm both unsubscribe headers exist in the final delivered email.
- DKIM coverage: Confirm the signed header list includes both unsubscribe fields.
- Endpoint logs: Trigger the POST and check that your server receives the fixed body.
- Suppression state: Verify the recipient is removed from the right list or topic.
- Follow-up send: Confirm the unsubscribed recipient no longer receives that stream.
This is also where real-time alerts help. If a sender changes a template, routing path, or DKIM signer and the unsubscribe headers drop out, you want to catch it before complaint rates rise.
Email tester
Send a real email to this address. Suped opens the report when the test is ready.
?/43tests passed
Preparing test address...
Security and compliance details
The unsubscribe URL should include enough information to identify the subscriber and list, but not in a way that exposes private data. I prefer opaque tokens that expire only if the underlying subscriber or list state changes. The token should be hard to guess and tied to a send event or subscription record.
The POST request should not depend on cookies, browser sessions, HTTP authorization, or previous web activity. The mailbox provider is acting inside the mail client context, not as a logged-in browser user. A clean implementation treats the token as the authorization for that specific unsubscribe action.
Endpoint behavior checklisttext
If request method is POST If body equals List-Unsubscribe=One-Click If token is valid for recipient and list Mark recipient unsubscribed from that list Return HTTP 200 or 204 Do not redirect the POST
For Gmail and Yahoo compliance, honor unsubscribe requests quickly. The practical target is within 48 hours, and faster is better because a person who already opted out is likely to complain if more promotional mail arrives.
A good implementation is boring
- Single action: The POST removes the recipient from the matching list without extra prompts.
- Scoped token: The URL identifies the recipient and list without exposing raw personal data.
- Stable response: Repeated POSTs return success after the user is already unsubscribed.
- Visible backup: The email footer still has a clear unsubscribe link or preference center.
Views from the trenches
Best practices
Sign both unsubscribe headers with DKIM and verify the h= list after every ESP change.
Use opaque tokens that identify the list and recipient without exposing private data in URLs.
Treat low complaint rates and clean authentication as part of unsubscribe visibility work.
Common pitfalls
Relying on a footer link alone leaves Gmail and Yahoo without the RFC 8058 signal.
Processing GET requests as opt-outs creates accidental unsubscribes from link scanners.
Assuming the inbox button always appears causes false alarms during low-volume tests.
Expert tips
Check the raw message first, then test the POST endpoint and suppression update path.
Ask the ESP whether it signs List-Unsubscribe headers in the active DKIM signature.
Keep the visible unsubscribe link because header support is not a legal footer replacement.
Expert from Email Geeks says RFC 8058 is the mechanism Gmail and Yahoo mean when they ask for header-based one-click unsubscribe.
2024-01-18 - Email Geeks
Expert from Email Geeks says the ESP should usually handle the header pair and POST endpoint because it controls final message assembly.
2024-01-18 - Email Geeks
The practical answer
To add the unsubscribe button near the sender name, add the RFC 8058 header pair to the raw email, make the HTTPS URL process a one-click POST, and sign those headers with DKIM. Then test the delivered message and endpoint. The mailbox provider owns the visible button, so the correct goal is compliance and eligibility, not pixel control.
If an ESP sends your mail, push the ESP to confirm exactly where the headers are added, whether DKIM covers them, and how quickly suppression is updated. If you send mail yourself, treat the endpoint like production infrastructure because unsubscribe failures turn into complaints fast.
