What is one-click unsubscribe? The practical difference from List-Unsubscribe header

What is one-click unsubscribe? The RFC 8058 POST flow behind mailbox unsubscribe buttons

It is not merely a footer link that opens a preference page, and it is not a background POST that receivers should fire without user consent.

Why RFC 8058 uses POST instead of a normal link click

Security scanners and anti-spam systems may fetch links in email automatically. If merely GETting an unsubscribe URL always removed the subscriber, automated link scanning could unsubscribe people accidentally.

RFC 8058 gives mailbox providers a distinct POST action that represents an intentional one-click unsubscribe flow. The receiver must not perform that POST without user consent. This is the important separation:

• GET can remain the human-facing page flow
• the RFC 8058 POST is the machine-action unsubscribe request

The same URL can support both methods, but the behaviors should be designed deliberately.

The URL must identify what to unsubscribe

The POST body contains the fixed one-click signal, not the recipient's email address or a list identifier. RFC 8058 therefore requires the URL itself to contain enough information to identify the recipient and list/subscription. A common design is an opaque signed token:

https://example.com/u/eyJ...signature

The server validates the token and maps it to the exact suppression action. RFC 8058 recommends an opaque or otherwise hard-to-forge component to reduce abuse.

The token should grant only the authority needed for the unsubscribe. It should not become a bearer credential for viewing profile data, account access, or other sensitive operations.

The POST must not depend on browser state

RFC 8058 says the one-click POST must not include cookies, HTTP authorization, or other contextual information. That means the endpoint must work from the message-carried URL alone. Bad design:

POST /unsubscribe→ 302 /login→ user signs in→ selects list→ presses Confirm

Good one-click design:

POST /u/opaque-token→ validate token→ mark exact subscription suppressed→ 2xx response

RFC 8058 also says the sender must not return an HTTPS redirect for the one-click POST.

DKIM is part of the protocol, not an optional best practice

RFC 8058 requires at least one valid DKIM signature, and that signature must cover the List-Unsubscribe and List-Unsubscribe-Post header fields. That requirement prevents treating arbitrary unsigned unsubscribe instructions as trustworthy one-click metadata. Implementation checklist:

1. send a valid DKIM-signed message
2. include List-Unsubscribe with an HTTPS URI
3. include List-Unsubscribe-Post: List-Unsubscribe=One-Click
4. include both headers in the DKIM h= signed-header list
5. make the HTTPS endpoint accept the RFC 8058 POST
6. complete the unsubscribe without interactive confirmation
7. persist the suppression and make sending systems honor it

Gmail's current one-click requirement

Google's current sender requirements make one-click unsubscribe an operational requirement for qualifying bulk marketing/subscribed messages sent to personal Gmail accounts. Google says promotional messages must support one-click unsubscribe and also include a visible unsubscribe link in the message body.

Google's FAQ specifies RFC 8058 List-Unsubscribe headers for one-click and says a body link or a mailto: header alone does not satisfy the one-click requirement. Google's subscription guidance says unsubscribe requests should be honored within 48 hours.

This is a provider rule layered on top of the protocol. The RFC explains how the one-click mechanism works; Gmail determines which senders/messages it requires it from.

Yahoo's current position has a wording nuance

Yahoo's current sender documentation requires easy unsubscribe for bulk subscribed/marketing mail and supports the List-Unsubscribe ecosystem. Its Best Practices page describes RFC 8058 POST support as highly recommended, while Yahoo's FAQ says a functioning List-Unsubscribe header is required and that it should preferably implement RFC 8058.

Because provider wording and enforcement can change, a sender building for both Gmail and Yahoo should implement the full RFC 8058 path rather than deliberately targeting a weaker interpretation.

One-click is not the same as “unsubscribe from everything”

The protocol tells the sender how to receive an unsubscribe action. It does not dictate your entire preference taxonomy. The URL can identify a specific subscription/list. A recipient might be unsubscribing from:

• weekly promotions
• product alerts
• a newsletter
• a particular brand/store stream

Your product model determines the scope, subject to applicable law and provider expectations. The critical point is that the one-click request must have an unambiguous, immediate effect for the subscription represented by that message.

One-click and the visible footer should converge on the same state

A mailbox native button, footer link, preference center, support request, or API suppression can all be different inputs to the same subscription state. If they update different databases, race conditions follow:

Gmail one-click → suppression table AFooter unsubscribe → customer profile BCampaign sender → reads list C

The recipient then “unsubscribes” but still receives mail. A better architecture turns every channel into one durable source of truth or a reliably synchronized suppression model.

Idempotency matters

One-click endpoints should be safe to call more than once. If the recipient is already unsubscribed, a repeat request should normally preserve that state rather than fail in a way that tempts the receiver or operations team to retry unpredictably. Conceptually:

ACTIVE --unsubscribe--> UNSUBSCRIBEDUNSUBSCRIBED --unsubscribe--> UNSUBSCRIBED

That is easier to operate than treating “already unsubscribed” as an exceptional error.

Test the actual wire behavior

Do not stop at seeing the headers in application code. For a test message, verify:

• the received message contains exactly the intended headers
• the DKIM signature validates and covers both headers
• the HTTPS endpoint is publicly reachable with valid TLS
• POST with List-Unsubscribe=One-Click returns a successful non-redirect response
• no cookie or login session is required
• the correct subscription becomes suppressed
• a repeat POST is safe
• the sender can no longer send the covered marketing stream to that address
• the visible unsubscribe path updates compatible state

Provider UI is a separate validation. A technically valid header does not guarantee that a mailbox will display a native unsubscribe affordance for every sender or message.

Design the endpoint as a narrow security capability

The unsubscribe URL can be forwarded, logged, scanned, or exposed to systems other than the original recipient's browser. It should therefore authorize only the smallest useful action: suppress the identified subscription. A one-click token should not double as:

• a login token
• an account-management session
• a way to read profile data
• a generic API credential
• authority to change unrelated preferences

RFC 8058 recommends opaque or hard-to-forge URL components because predictable unsubscribe URLs create an abuse surface. A signed token that identifies the subscription and can be validated without browser state is a common pattern.

The server should also avoid leaking unnecessary information in its response. A caller does not need to learn whether an address exists, which lists it belongs to, or other account details in order to complete the unsubscribe.

GET and POST should have deliberately different semantics

Many senders want the same URL to support both a human footer click and the mailbox provider's RFC 8058 action. That can work, but only if the methods are treated differently. A practical model is:

GET  /u/<token>  → show a human confirmation or preference UIPOST /u/<token>  → apply the one-click unsubscribe immediately

The POST must not depend on the GET having happened first. It must not wait for JavaScript, cookies, login, or a second confirmation. And it must not redirect to another page to finish the operation.

This design also protects against accidental GET-based unsubscriptions caused by security scanners that crawl links. A scanner can fetch the human URL without the system interpreting that GET as the RFC 8058 one-click action.

Provider UI is an outcome, not the protocol conformance test

A sender can implement RFC 8058 correctly and still not see a native unsubscribe button on every message. Mailbox providers can apply their own trust, reputation, UI, and eligibility logic. Therefore test 2 things separately:

1. protocol conformance: headers, DKIM coverage, POST behavior, token validation, and suppression
2. provider presentation: whether Gmail, Yahoo, or another mailbox chooses to expose the native control for the production stream

If the native button is absent, do not immediately “fix” the protocol by changing random headers. First verify conformance, then investigate provider-specific eligibility and reputation.

Failure handling should prefer durable state over repeated sending

An unsubscribe endpoint can fail temporarily because of a database outage, queue failure, or downstream synchronization problem. The wrong response is to return success while dropping the state change and continue mailing the recipient.

Design the write path so the request is either durably recorded or clearly fails for retry/alerting. If downstream systems are asynchronous, persist the unsubscribe first, then propagate it. The sending path should consult a state that becomes conservative quickly rather than waiting for every secondary system to catch up. A useful invariant is: > once the system has durably accepted an unsubscribe, no ordinary campaign import, segment rebuild, or automation retry can make the covered marketing stream send again.

This is an implementation principle rather than an RFC wire requirement, but it is what turns the protocol event into the recipient outcome the protocol exists to request.

Worked example

A minimal conceptual example is:

List-Unsubscribe: <https://example.com/u/opaque-token>List-Unsubscribe-Post: List-Unsubscribe=One-Click

• The message also needs a valid DKIM signature that covers both of those header fields

When the recipient chooses the mailbox provider's unsubscribe control, the receiver can send:

POST /u/opaque-token HTTP/1.1Host: example.comContent-Type: application/x-www-form-urlencoded List-Unsubscribe=One-Click

The endpoint should process that request without asking the recipient to log in, load a confirmation page, or submit another form.

A practical One-click unsubscribe rollout

One step.

1. 01
   Make processing observable without making it reversible by accidentA production endpoint needs more than a 200 response. Operators should be able to answer: - Was the token valid? - Which subscription state changed? - When was the request received? - Was the recipient already unsubscribed? - Did downstream campaign systems receive the suppression? - Did any send occur after the effective unsubscribe time? Those events belong in an audit trail. But the audit system should not create a casual “undo” path that lets an import or retry flip the recipient back to subscribed. Think of unsubscribe as an idempotent state transition with a separate, explicit resubscription path. That makes failures measurable without making the state fragile.

Common mistakes

1. Calling a footer link “one-click unsubscribe.”
2. Including List-Unsubscribe but omitting List-Unsubscribe-Post
3. Using only mailto: and claiming RFC 8058 compliance
4. Failing to DKIM-sign the unsubscribe headers
5. Returning a redirect from the POST endpoint
6. Requiring a login, cookie, confirmation page, or preference form before the unsubscribe takes effect
7. Building a predictable token that can unsubscribe arbitrary users
8. Updating one list while another campaign pipeline continues sending
9. Waiting for the longest legal deadline when a provider expects faster handling

Questions we get asked