One-click unsubscribe: headers, endpoint behavior, and the last-mile check

A newsletter can have a visible unsubscribe action in its body and a mailbox-driven one-click action in its headers. They serve related needs but are not the same interaction. Gmail’s current bulk-sender guidance calls for one-click support for marketing and subscribed messages alongside a visible body link. Keep that provider requirement separate from your own decision about which lists and topics the choice affects.

In our example, the newsletter footer explains that opting out stops the weekly edition. A preference page can also offer fewer messages, but it should not make a straightforward opt-out depend on choosing a reason or signing into an account. Name the outcome before the person acts. If you offer an all-marketing choice, preserve its broader meaning across imports and other campaign flows instead of treating it as an unrelated checkbox.

Reference: Google: Email sender guidelines

RFC 8058 defines the HTTPS unsubscribe URI and the List-Unsubscribe-Post signal. It also requires a valid DKIM signature covering both relevant headers. A preview of the email body cannot prove those requirements are satisfied. The provider may add headers, change their order, or choose which ones it signs after your editor has finished rendering the content.

Use a controlled recipient and inspect the delivered source. Check that the HTTPS destination is the intended production endpoint, that the post signal is present once, and that the signer covers the unsubscribe fields. Save a redacted result with the provider configuration and message revision. Do not publish a real recipient token in a bug report. The example below is illustrative wire syntax, not a copy-ready endpoint or a production secret.

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

Reference: IETF: RFC 8058

The one-click request must be able to identify the recipient and list without a browser login or extra contextual credentials. Use a hard-to-forge opaque reference and validate its intended scope. Do not turn the endpoint into a generic instruction processor that accepts arbitrary subscription changes. Handle the expected operation directly rather than redirecting the request into an interactive preference screen.

Keep GET requests non-mutating so a link fetch does not quietly alter the subscription. Treat the documented one-click POST as its own bounded operation. Constrain input size, reject malformed operations, and make repeat requests safe. A correct response should mean the durable preference write completed, not merely that a worker was started. If the write fails, preserve a retryable failure instead of presenting an attractive success screen that does not match the record.

Our newsletter job selected recipients in the morning. Someone opts out before the afternoon batch reaches the provider. The old selection is now insufficient evidence of eligibility. Keep the message purpose, list scope, and current subscription state available at dispatch, and stop the pending marketing job when the relevant choice has changed. A campaign’s original audience count should not override a later reader decision.

Define the race boundary honestly. A message already accepted by the provider may still arrive; an unsubscribe cannot recall it. Record whether a job was only prepared, reserved for dispatch, or already accepted. Use a consistent suppression decision for campaigns and automations so one flow does not compensate for another’s cancellation by sending its own follow-up. Re-importing the same address should not erase the preference history that explained why it was excluded.

Run a controlled test against an isolated list with a known message revision. Fetch the unsubscribe URL without changing anything, then submit the expected one-click operation. Inspect the durable record and try the request again. Repetition should not create confusing preference events or an error that falsely implies the original request failed. Check that the next eligible marketing job is excluded for the intended reason.

Test malformed tokens, unsupported input, an unavailable datastore, and a queued message selected before the opt-out. Exercise the body link separately because its UI and confirmation behavior may differ from the header endpoint. Capture evidence without retaining the capability token. A reviewer should see the operation, its bounded result, and the dispatch decision, rather than a screenshot of a mailbox button being mistaken for proof of a complete system.

• GET does not change subscription state.
• The expected POST persists the intended opt-out without login.
• Repeated requests preserve the same decision.
• Queued marketing work checks current eligibility.
• Delivered headers and DKIM coverage match the reviewed revision.

Choose a Moosewave newsletter template for the message, then review the transport separately. The template supplies readable content and a visible body action; your sending stack supplies the delivered headers, signing behavior, and preference endpoint. Record who owns each piece. An agent can prepare a checklist or inspect a redacted example, but it should not silently replace an approved unsubscribe destination while improving the wording.

When the provider, domain, preference service, or message purpose changes, repeat the relevant checks. Keep a compact release note stating which path was tested, which records changed, and what remained unverified. This makes the next audit easier and prevents a new design from inheriting an unrelated old pass. A useful unsubscribe experience is not a decorative footer feature. It is a dependable way for a person’s decision to become the system’s next decision.

• Google: Email sender guidelines. Current Gmail sender requirements; other providers may have different requirements.
• IETF: RFC 8058. The one-click header and HTTPS POST protocol. The newsletter workflow and test plan are our applied recommendations.

Sources checked 13 October 2026. Product behavior and documentation can change, so the linked primary source takes precedence if it differs from this article.