One-click unsubscribe: meet Gmail and Yahoo rules

By Alex Calder · Reviewed 15 September 2026

A hand turning a key in a silver deadbolt on a white door.

Separate the header, automated action and body link

RFC 2369 defines List-Unsubscribe as a message-header field that can advertise one or more unsubscribe methods. RFC 8058 adds a one-click HTTPS POST convention using a companion List-Unsubscribe-Post field. A visible footer link remains content a person can find and use.

The receiver may turn RFC 8058 headers into an unsubscribe control in its interface. It sends a POST to the HTTPS URI without asking the person to visit a preference page. The body link is ordinarily opened in a browser and may present choices or confirmation. Build both against one authoritative suppression service while preserving their different interactions.

One-click does not authenticate a campaign, prove consent or guarantee inbox placement. It reduces friction for stopping subscribed or marketing mail and must not be simulated by a decorative link.

Construct the two RFC 8058 fields correctly

The message needs a List-Unsubscribe field containing an HTTPS URI and a List-Unsubscribe-Post field whose value is List-Unsubscribe=One-Click, as specified by RFC 8058. The one-click URI should carry an opaque, recipient-specific token with only the scope needed to process the request.

DKIM must cover the relevant headers for the RFC mechanism. Sign after final header construction and check that an intermediary or platform has not removed, reordered or replaced fields. Do not paste an address directly into a query string or expose account data in logs and referrers.

RFC 2369 also allows methods such as mailto in List-Unsubscribe. That historical capability does not mean every receiver’s current one-click policy accepts mailto. Match provider wording rather than treating all advertised methods as equivalent.

Make the POST endpoint narrow and idempotent

RFC 8058 describes an HTTPS POST carrying List-Unsubscribe=One-Click. The endpoint should accept repeated valid requests safely, apply the intended marketing suppression and return an appropriate success response without login, cookies, JavaScript or a confirmation journey RFC 8058 details.

Do not unsubscribe on an ordinary GET to the one-click URI. Security scanners and link checkers may follow GET links. Keep GET harmless or route it to a suitable information page, while requiring the defined POST body for the automated action. Validate method, token, expiry policy and list scope before changing state.

Separate browser preference functionality from the machine endpoint. A preference centre can ask a human for choices, but the automated request must not depend on rendering it.

Design tokens for privacy and abuse resistance

Use high-entropy opaque tokens, bind them to the intended recipient and subscription scope, protect signing or lookup secrets, and avoid sequential identifiers. Decide how key rotation and message age affect old requests. A token should not reveal the email address, campaign history or internal customer number.

Log a minimal request identifier, outcome, scope and time. Avoid storing complete URLs where tokens would spread into analytics, reverse-proxy logs and support exports. Restrict endpoint dashboards because unsubscribe events reveal relationships and communication preferences.

Forged requests and forwarded messages are failure cases. The token should prevent guessing, and the suppression effect should be limited to the represented recipient and stream. Do not require a recipient to remain subscribed because a request looks inconvenient; investigate abuse without restoring marketing automatically.

Keep Gmail and Yahoo requirements distinct

Google’s sender guidelines require one-click unsubscribe for bulk marketing and subscribed messages sent to personal Gmail accounts, alongside a clearly visible message-body link. Google specifies the RFC 8058 HTTPS approach. Its bulk scope and other authentication conditions remain separate from implementation of the endpoint.

Yahoo’s sender guidance requires a functioning List-Unsubscribe mechanism and visible body link for bulk marketing and subscribed mail, says the RFC 8058 POST method is highly recommended, accepts mailto, and states that requests should be honoured within two days. Do not rewrite those details as identical to Google.

Classify transactional mail carefully and keep promotional material out of necessary account messages where possible. Recheck provider pages before a large launch because published requirements can change.

For the legal side of an opt-out request, see PECR and UK GDPR for business email and durable suppression records.

For the UK legal questions that sit behind an unsubscribe request, use the PECR and UK GDPR email guide alongside the technical implementation.

Connect every request to the same exclusion outcome

Map the endpoint, body-link application, email-based requests, CRM, campaign platform, sales automation and agency files. Set one suppression authority or a deterministic reconciliation rule. A successful HTTP response is not success if tomorrow’s import reactivates the address.

Apply the event idempotently, cancel queued marketing where possible and propagate before the provider’s required time. Keep evidence of source, scope and completion without retaining unnecessary click or browsing data. An unsubscribe should not enrol the person in tracking.

Screen at audience build, scheduling and dispatch. Test the case where the address is deleted and re-imported, as this catches suppression systems tied only to a contact-row ID.

Keep the visible route usable by a person

Place an accurate unsubscribe label where it remains visible on mobile, plain-text and image-blocked views. Use sufficient contrast and a touch-friendly target. Do not hide it among legal text, require a password or force a sales conversation.

A preference page can offer narrower choices, but include an immediate way to stop the relevant marketing. Explain which address or subscription is affected without exposing it to someone using a forwarded message. Provide a confirmation that does not load unnecessary trackers.

Check replies too. Some recipients will write “stop” rather than use either link. Route those messages to the same suppression workflow and do not argue that they used the wrong control.

Verify from the delivered message, not a template preview

Create a controlled subscription. Use an address and list scope you can inspect end to end.
Send through production routing. Use the real platform, From domain, template and DKIM signing path.
Inspect raw headers. Confirm both fields, exact HTTPS URI, DKIM coverage and provider rendering.
Issue the defined POST. Capture status and verify one suppression event without browser interaction.
Use the body link separately. Confirm accessible rendering and the same final exclusion.
Check queues and connected systems. Prove pending marketing is cancelled and CRM state agrees.
Attempt a later send. Confirm the controlled address is excluded before dispatch.
Repeat after re-import. Ensure suppression survives normalisation and migration.

Stop on silent success, token leaks or re-contact

Common failures include a 200 response that does not suppress, GET causing unintended changes, expired links in fresh mail, platform rewriting, headers not signed with DKIM, a visible link requiring login, or one system restoring a suppressed record. Investigate the mechanism rather than resending tests repeatedly.

Stop affected marketing when valid POSTs fail, acknowledgements arrive without downstream state, tokens appear in public logs, requests affect the wrong scope, or a suppressed control address is selected again. Preserve raw headers, endpoint request ID, suppression event, queue snapshot and integration timestamps.

Escalate DKIM/header rewriting to the sending provider, token or endpoint vulnerabilities to security, and rights or retention disputes to the privacy lead. Resume only after fresh delivered-message tests pass both routes and a later scheduled-selection check excludes the address.

Specify and test the request contract

Write an endpoint contract for the sending platform, web team and privacy owner. It should name the HTTPS method, accepted content type, required form value, token validation, subscription scope, idempotent success behaviour, error classes, logging fields and maximum propagation time. Define what an ordinary GET does and confirm it never changes subscription state. Keep rate limiting able to resist abuse without rejecting legitimate bursts generated by mailbox providers.

Exercise negative cases in a test environment: missing POST field, malformed token, token for another list, repeated valid request, expired key version, unsupported method and temporary suppression-store outage. A repeat should return a safe result without recreating consent. A storage outage must not produce a misleading success response unless the request is durably queued. Alert on a queue that stops draining, and prevent retries from generating several contradictory preference events.

In production, correlate one controlled delivered message with its DKIM signature, one-click POST log, suppression event and later audience exclusion. Then forward the message to another controlled mailbox and confirm the token cannot reveal the original address or expose a preference page. Stop if proxy logs retain complete tokenised URLs, if a forwarded request changes unrelated subscriptions, or if platform support cannot explain header rewriting. Rotate exposed secrets, preserve affected event identifiers and repeat the delivered-message test after correction.

Include monitoring that measures processing latency from the mailbox provider’s POST to final audience exclusion. Alert before the promised handling limit is breached, but avoid logging addresses or complete tokens in metrics. Compare event counts across endpoint, suppression store and campaign platform so silent loss is visible. After a provider or platform release, inspect a newly delivered header because a correct application setting can still produce altered production mail. Retain the controlled evidence with the release record and repeat the test for every distinct sending domain.

Schedule a lightweight re-test after any planned change to the templating, signing, delay queue or suppression store, not only after an incident. A monthly controlled send through the real route is cheap compared with the cost of discovering a broken unsubscribe during a provider enforcement window or a complaint spike. Keep one canonical test instruction so a new owner can run the same check and compare results against earlier months.