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 28 May 2026
7 min read
Summarize with
The direct answer: Gmail's one-click unsubscribe requirement is header-based. For bulk senders, marketing and subscription messages need List-Unsubscribe-Post and List-Unsubscribe headers so Gmail can show its unsubscribe control near the sender details and send a POST request. You also need a clearly visible unsubscribe link in the email body. That body link can still go to a preference center, provided unsubscribe all is obvious and does not force a login, survey, or multi-step hunt. I would not replace the footer link with a hidden header-only setup because the body link is still part of the user experience and the Gmail sender rules.
Google states the bulk sender rule in its Google sender guidelines. The confusing part is the word one-click. Gmail uses it for the invisible, machine-readable header flow. Marketers often use the same phrase for a visible footer link that reaches an unsubscribe page in one click. Those are related, but they are not the same placement or implementation.
- Header: Put the RFC 8058 one-click mechanism in message headers, not in the visible email design.
- Body: Keep a visible unsubscribe link in the message body, usually in the footer.
- Preference center: It can be the destination for the body link if unsubscribe all is easy to find.
- Timing: Gmail subscription guidance expects unsubscribe requests to be honored within 48 hours.
What Gmail means by one-click unsubscribe
I treat Gmail's one-click unsubscribe as an inbox-provider API. The sender puts the right headers on the message, Gmail decides whether to expose its unsubscribe UI, and Gmail sends a POST request to the URL in the header when the recipient clicks that Gmail UI. The recipient should not land on a page, confirm a modal, answer a question, or pick through preferences for the header-based one-click path.
For a bulk sender, this applies to marketing messages and subscription messages sent to personal Gmail accounts. It sits beside the rest of Gmail's bulk sender requirements: SPF, DKIM, DMARC, low spam rates, valid forward and reverse DNS, TLS, and clean message formatting. A broader comparison with Yahoo is covered in Gmail and Yahoo rules.
Required Gmail one-click headerstext
List-Unsubscribe-Post: List-Unsubscribe=One-Click List-Unsubscribe: <https://example.com/unsubscribe/abc123>
The header endpoint has one job
When Gmail sends the unsubscribe request, your endpoint should remove that address from the relevant list without asking for anything else. The endpoint should be safe to call by Gmail, not by a human browsing a settings page.
- No extra step: Do not require confirmation, password entry, captcha, or a preference selection.
- Safe token: Use an opaque token that maps to the recipient and subscription list.
- List scoped: Remove the address from the list tied to the message, not every operational notice.
- Repeat safe: Return success even if the same unsubscribe request has already been processed.
Where each unsubscribe link belongs
There are two locations to think about. The Gmail unsubscribe button near the sender area comes from the message headers. The visible unsubscribe link belongs in the email body, normally in the footer, although it can appear higher if that makes sense for the template. You do not need to put an RFC 8058 one-click button in both locations.
Header unsubscribe
This is the Gmail requirement people usually mean when they say one-click unsubscribe.
- Placement: Message headers, invisible in the email body.
- Trigger: Gmail sends a POST request after the recipient uses Gmail's UI.
- Destination: A backend endpoint that immediately unsubscribes the recipient.
Body unsubscribe
This is the visible link recipients can click after opening the message.
- Placement: In the email body, usually in the footer.
- Trigger: The recipient clicks the visible link.
- Destination: A preference center or unsubscribe page with a clear unsubscribe all option.
|
|
|
|
|---|---|---|---|
Gmail UI | Header | Yes | POST |
Footer | Body | Yes | Preferences |
Header copy | Gmail | No | Gmail decides |
Main CTA | Body | No | Avoid |
Placement summary
Flowchart showing Gmail reading unsubscribe headers and sending a POST request.
Common implementation mistakes
The most common mistake is treating the footer preference center as the whole answer. A preference center is useful for humans, but it does not replace the header mechanism Gmail expects. The detailed header requirements matter because small formatting errors stop mailbox providers from trusting the flow.
Failures I check first
- GET only: A page that only handles browser GET requests is not the Gmail one-click flow.
- Page first: Sending Gmail's POST to a preference page adds an extra user action.
- Global removal: A list unsubscribe should not block transactional notices the user still needs.
- No audit trail: Log the request, token, list, result, and timestamp so support can verify the opt-out.
- Tracking rewrite: Link rewriting should not break the header URL or change it into a click-tracked page.
Another point that causes confusion: Gmail does not promise to display the unsubscribe button for every valid message. It uses its own UI and trust signals. If the headers are correct but the button is missing, inspect authentication, sender reputation, message category, and whether the message is actually a subscription message. I also check the raw source of the delivered message, not the ESP preview, because previews often show what the platform intended to send rather than what Gmail received.
How to implement and test it
If your ESP already manages List-Unsubscribe headers, confirm the exact behavior rather than rebuilding it. Many established sending platforms have supported this for years. The work is still worth auditing because custom templates, custom sending domains, tracking settings, and API-triggered campaigns can bypass default headers. Ask for the final header output, the unsubscribe endpoint behavior, and the suppression timing, then verify those answers against a delivered test.
Example Gmail POST requesthttp
POST /unsubscribe/abc123 HTTP/1.1 Host: example.com Content-Type: application/x-www-form-urlencoded Content-Length: 26 List-Unsubscribe=One-Click
- Generate token: Create a signed or opaque token for the recipient, list, and message stream.
- Add headers: Insert both required headers on marketing and subscribed messages.
- Keep footer link: Point the visible body link to a clear preference center or unsubscribe page.
- Record event: Store the request result, including the list removed and the time processed.
- Suppress fast: Update suppression data quickly enough to meet Gmail's 48-hour expectation.
After deployment, send a real message to a Gmail inbox and inspect the final delivered message through the email tester. Check that both headers survive ESP rewriting, link tracking, template rendering, and any mail transfer layer that touches the message.
Email tester
Send a real email to this address. Suped opens the report when the test is ready.
?/43tests passed
Preparing test address...
Testing should include at least one production-like send for each major stream: newsletter, promotional campaign, lifecycle campaign, product updates, and any recurring notification that a recipient can unsubscribe from. I also like to test a non-subscription stream, such as receipts, to confirm you are not adding marketing unsubscribe behavior to transactional mail. Keep those streams separated by From address or list identity so a Gmail unsubscribe request removes the right subscription and does not suppress account-critical messages.
Do not isolate unsubscribe from authentication
One-click unsubscribe is only one part of Gmail compliance. If SPF, DKIM, DMARC, reverse DNS, spam rate, or reputation are weak, the unsubscribe headers will not rescue delivery. Start with a broad domain health checker pass, then monitor the authenticated sources that are actually sending mail for your domain.
Suped's product is useful here because it connects DMARC monitoring, SPF, DKIM, hosted authentication records, alerts, and blocklist monitoring in one place. That matters when a Gmail compliance audit turns into a sender inventory problem. You need to know which system sent the message, which domain authenticated it, whether DMARC passed, and whether an IP or domain is on a blocklist (blacklist).
Suped DMARC dashboard showing email volume, authentication health, and source breakdown
Gmail spam-rate risk
Use complaint rate as a daily signal while testing unsubscribe and sender compliance.
Healthy
Below 0.10%
Good operating range
Warning
0.10% to 0.29%
Investigate list quality
Critical
0.30% or higher
Gmail threshold risk
Where Suped fits
For most teams, Suped is the best overall DMARC platform for the authentication and reputation work around Gmail compliance. Your ESP can handle the unsubscribe header, while Suped keeps the domain-level controls visible and actionable.
- Issue detection: Automated findings show which sources fail SPF, DKIM, or DMARC and how to fix them.
- Hosted records: Hosted DMARC, SPF flattening, hosted SPF, and hosted MTA-STS reduce DNS maintenance.
- Alerts: Real-time alerts help catch sudden authentication failures or reputation changes.
- Multi-domain work: The MSP dashboard helps agencies manage many client domains without spreadsheet drift.
Views from the trenches
Best practices
Put RFC 8058 in headers, then keep the visible footer link clear and easy to find.
Test every sending stream because templates, ESP defaults, and custom code can differ.
Use list-level identity so a Gmail request removes the correct subscription only.
Common pitfalls
Routing the header URL to a preference page breaks Gmail's no-extra-action rule.
Assuming Gmail always displays the button creates false confidence during audits.
Letting footer copy hide unsubscribe increases complaints and manual support work.
Expert tips
Log each POST request with list ID, user ID, timestamp, and result for audits too.
Keep preference centers simple, with unsubscribe all visible before optional choices.
Monitor DMARC and complaint data together because authentication and consent matter.
Marketer from Email Geeks says the one-click function is the header-based path that lets Gmail make a backend unsubscribe call after the user clicks Gmail's own control.
2024-01-30 - Email Geeks
Marketer from Email Geeks says the visible footer link can still go to a preference center, as long as unsubscribe all is obvious and does not require extra work.
2024-01-30 - Email Geeks
What I would do next
Keep both unsubscribe paths, but do not make them do the same job. The header path should be pure one-click processing for Gmail. The body link should be visible, understandable, and useful for people who want to change preferences or unsubscribe from all marketing.
- First: Confirm your ESP inserts both Gmail-required headers on subscribed messages.
- Second: Make the footer unsubscribe link visible and keep unsubscribe all easy to find.
- Third: Test a delivered message and monitor authentication, complaints, and blocklist or blacklist signals.
If those pieces are in place, the answer to the original placement question is simple: one-click belongs in the header, a visible unsubscribe link belongs in the body, and the footer link does not need to be the same RFC 8058 endpoint.
