One-click unsubscribe headers must be covered by DKIM: the RFC 8058 detail easy to omit

What the standard or provider is actually evaluating

RFC 8058 requires a List-Unsubscribe header containing an HTTPS URI and a List-Unsubscribe-Post header with List-Unsubscribe=One-Click, and it requires a valid DKIM signature that covers at least those two headers.

RFC 8058 one-click unsubscribe is a specific machine-actionable mechanism, not a synonym for putting an unsubscribe link in the HTML body. The message carries a `List-Unsubscribe` header with an HTTPS URI and a `List-Unsubscribe-Post: List-Unsubscribe=One-Click` header that tells a supporting mailbox provider how to issue the POST. The DKIM signature used for this mechanism must cover the relevant list-unsubscribe headers so an intermediary cannot silently replace the endpoint. When auditing a message, inspect raw headers and the DKIM `h=` list; a pretty footer link does not prove the one-click path is correctly signed.

The shortcut that breaks the diagnosis

Seeing the headers in a message proves only that they were inserted. If a gateway adds them after DKIM signing, or the signer omits them from the h= list, a receiver cannot rely on the signed message to protect those instructions.

A frequent implementation mistake is to add the two headers after DKIM signing. The recipient sees the fields, but they are outside the authenticated header set, defeating a core protection in the specification. Another mistake is to point the HTTPS URI at a page that requires a login, cookie prompt, or confirmation click. One-click is designed for an automated POST that can directly request removal. Keep a normal human-facing preference link if useful, but do not confuse that browser flow with the RFC 8058 endpoint that mailbox providers can invoke without rendering the message.

Build a control case before editing production

Open the raw message, find the DKIM-Signature that passes, and inspect its h= field for both unsubscribe header names. Then verify that the HTTPS URI is reachable without needing an interactive confirmation flow.

Test the finished message, not the template. Send through the same signing and gateway path used in production, view raw source, and verify both unsubscribe headers survived unchanged. Check DKIM-Signature to confirm those header field names are included in the signed set, then POST the exact body defined by RFC 8058 to the HTTPS URI in a safe test environment. Confirm the endpoint accepts the request without a browser session and that the recipient identity encoded by the URL is sufficient to update suppression. Finally, send another message only after intentionally re-subscribing the test identity so the production suppression behavior is not bypassed.

Fix the state that the evidence names

Insert unsubscribe headers before the final DKIM signing boundary and configure the signer to include them. Preserve the signature after downstream relays by avoiding later header rewriting.

Treat the endpoint as part of deliverability infrastructure. It should be HTTPS, reliably available, safe to call more than once, and connected to the same suppression source used by every outbound mailbox. Log request time, recipient token or internal identity, campaign/domain context, result, and suppression write. Do not make the endpoint depend on the sender mailbox that happened to send the message; unsubscribing should survive mailbox rotation. After any signing or gateway change, re-run the header/DKIM test because a harmless-looking footer or relay update can reorder or modify headers and break a mechanism that previously worked.

An operator-sized scenario

A message can contain a valid aligned DKIM signature over From, Subject and Date while leaving List-Unsubscribe unsigned. DKIM passes, but the one-click-specific integrity requirement is still missing.

The endpoint token should identify the unsubscribe action without exposing a raw email address or allowing arbitrary changes. A signed or opaque token can map back to the recipient and intended suppression scope on the server. Keep the HTTPS URI stable long enough for delivered mail to remain actionable; rotating domains or routes should not make yesterday’s unsubscribe header dead. When the send path has multiple DKIM signatures, verify that at least the qualifying signature covers the one-click headers as required, and do not assume a signature added by a downstream gateway automatically covers fields inserted later. Include this check in message fixtures for every provider path. The operational standard is simple: a receiver can authenticate the headers, POST the defined request, and the same global suppression state that send workers consult changes promptly.

Fields that make the decision auditable

Save one raw received message per sending platform with the unsubscribe headers, DKIM h= coverage, signing domain, endpoint host, and the response from a controlled one-click test.

Do not turn this edge case into a universal rule

This is a transport and message-format guide, not individualized legal advice. Receiver requirements and consent obligations can be broader than the mechanics of RFC 8058.

Field checklist

• Capture the raw evidence for List-Unsubscribe-Post DKIM signed headers RFC 8058 before editing DNS, queue state, or mailbox metadata.
• Confirm the cited mechanism using oneclick-rfc, gmail-faq rather than a generic deliverability score.
• Keep a known-good control case so the failing layer can be compared without changing several variables at once.
• Apply the narrow repair described for One-click unsubscribe headers must be covered by DKIM: the RFC 8058 detail easy to omit and preserve a rollback or retry path.
• Repeat the original failing test after the change; do not substitute a different checker as proof of recovery.
• Store timestamp, affected identity, raw result, action taken, and the post-change result in the operator log.