Email Deliverability · Email Marketing · Email Authentication · Unsubscribe

List-Unsubscribe Header Deliverability Setup Checklist

· InboxPlacement.io Team

InboxPlacement.io List-Unsubscribe banner showing RFC 8058 headers, DKIM coverage, and the unsubscribe-to-suppression flow

Use this checklist to implement and verify List-Unsubscribe handling for marketing mail. It separates RFC 8058 POST-based one-click unsubscribe from provider-specific alternatives, identifies what evidence to collect, and defines validation and monitoring steps. A correctly configured unsubscribe flow does not guarantee inbox placement.

Who this checklist is for and the outcome it supports

  • Who: deliverability engineers, email ops, ESP integrators, and technical owners responsible for marketing or bulk email streams.
  • Outcome supported: produce a documented, provider-aligned List-Unsubscribe header implementation with evidence you can present to mailbox providers and use in validation gates before wide sending.
  • What this will not prove: implementing the List-Unsubscribe header and correct authentication does not prove inbox placement by itself. Authentication, receiver disposition, delivery, and inbox placement are separate signals that must each be observed and interpreted.

Prerequisites and evidence to collect

Collect the following artifacts before you change templates or send at scale. Treat each collected item as the observed evidence used in validation gates.

Checklist of required artifacts (collect these):

  • Published SPF record for the sending domain(s).
  • DKIM records for signing the domain(s).
  • Published DMARC record for the domain(s) (do not weaken an existing enforcement policy; see policy note below).
  • Message category, approximate daily volume, and destination providers, so you can determine which provider requirements apply.
  • Operational List-Unsubscribe header value(s) in the message source (POST/URI or mailto: methods).
  • Working List-Unsubscribe endpoint(s) or mailto: target(s) that honor requests.
  • Message examples (raw source) showing the List-Unsubscribe header and the Authentication-Results header as received by a mailbox provider (illustrative examples are acceptable if you cannot provide provider headers yet).
  • Logs showing unsubscribe events processed and timestamped (to confirm timeliness).
  • Sender reputation and complaint-loop access where available (e.g., Postmaster tools, Complaint Feedback Loop).

Evidence to collect and what it shows (observed evidence vs what it cannot prove):

  • SPF/DKIM/DMARC DNS records (observed evidence): show published configuration but cannot by themselves prove receiver acceptance or inbox placement.
  • Raw received message source (observed evidence): shows the headers the receiver evaluated. The Authentication-Results header records authentication results; it does not by itself show inbox placement or future reputation.
  • Unsubscribe processing records (observed evidence): request-received and suppression-completed timestamps can show processing time. They do not prove mailbox-provider routing decisions. Keep only the data needed for operational verification and apply your retention and privacy controls.

Note on DMARC: If you publish DMARC, keep the policy you intend to operate. Never advise weakening an enforced DMARC policy for expediency. Any emergency change requires explicit owner authorization, a limited scope, a strict time window, and rollback criteria. Keep the published DMARC policy (what you publish) distinct from the DMARC result reported by receivers; Authentication-Results records the receiver evaluation, and receiver disposition, delivery, and inbox placement are separate signals to collect and interpret.

Step-by-step implementation checklist

Use this ordered checklist. Mark each item Completed/Blocked and attach the evidence named in the Prerequisites section.

  1. Prepare authentication

    • Implement SPF and DKIM for the sending domains if not already present.
    • Publish a DMARC record for the domain(s). For bulk senders, Yahoo’s guidance expects a DMARC policy at least published (p=none recommended initially) to allow monitoring (see Yahoo sources below).
    • Evidence to attach: DNS record exports or copy/paste of the published TXT records.

  2. Choose List-Unsubscribe method(s)

    • For RFC 8058 one-click, use an HTTPS URI in List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click. The request is an HTTP POST; a confirmation page or login must not be required to complete that one-click action.
    • RFC 8058 also requires a valid DKIM signature covering both unsubscribe headers. Use an opaque, hard-to-forge URI token and validate it server-side; do not rely on cookies or authorization context for the request.
    • Yahoo says mailto: is acceptable as an unsubscribe method, but it is not the RFC 8058 POST-based one-click flow required by Gmail for applicable bulk-sender marketing mail. Check the destination provider’s rules.
    • Evidence to attach: representative raw message source showing both headers and the DKIM signature, plus the endpoint’s observed POST handling.

  3. Implement server-side unsubscribe endpoints

    • Process a valid RFC 8058 POST without a login, confirmation step, or dependence on a browser session; update marketing suppression promptly.
    • Record request receipt, processing completion, and outcome so you can verify timeliness. Avoid collecting unnecessary request data, and define access and retention controls.
    • Evidence to attach: endpoint behavior documentation and a redacted test record showing request and suppression timestamps.

  4. Add header to outgoing messages

    • Add correctly formatted List-Unsubscribe and List-Unsubscribe-Post headers for RFC 8058 one-click. If you also include a mailto: option, confirm each provider’s supported method.
    • Ensure the DKIM signature covers both unsubscribe headers and verify the final received message, not only the ESP template.
    • Evidence to attach: redacted raw message source showing the headers and relevant DKIM signature fields.

  5. Honor unsubscribes promptly

    • Meet the applicable provider window: Yahoo says within 2 days; Google says applicable bulk senders must honor requests within 48 hours.
    • Evidence to attach: redacted records showing request receipt and suppression completion.

  6. Test in staging

    • Send test messages to internal seed addresses and to mailbox providers’ test accounts.
    • Capture the received raw source including the Authentication-Results header (label as observed evidence).

  7. Incremental roll-out

    • Start limited volume sends while monitoring authentication and complaints before scaling to full traffic (illustrative gating strategy).

  8. Document and communicate

    • Keep a runbook with DNS configs, header examples, endpoint behavior, and validation gates.

Illustrative Spam Test showing missing List-Unsubscribe and List-Unsubscribe-Post headers.

Demo example. Missing unsubscribe headers. Synthetic results for feature explanation; not a live test or customer outcome.

Mailbox-provider or protocol-specific requirements

Observed facts from provider guidance; verify the current rules for the recipient category you serve:

  • Yahoo: Bulk senders must use SPF and DKIM, publish a valid DMARC policy of at least p=none and pass DMARC, align the From: domain with SPF or DKIM, provide a functioning List-Unsubscribe method and a visible body link, and honor requests within 2 days. Yahoo highly recommends the RFC 8058 POST method and says mailto: is acceptable. Yahoo’s FAQ says one-click unsubscribe applies to promotional/marketing messages, not transactional mail. Yahoo describes bulk sender volume as significant but does not publish a numeric threshold.
  • Gmail personal accounts: Senders delivering more than 5,000 messages per day to Gmail accounts must use SPF and DKIM, publish DMARC (a p=none policy is allowed), and align the From: domain with SPF or DKIM for direct mail. Marketing and subscribed messages must support RFC 8058 one-click unsubscribe and include a visible body link; requests must be honored within 48 hours. Google’s FAQ says enforcement on non-compliant traffic began ramping up in November 2025. These requirements are for personal Gmail accounts, not Google Workspace inbound mail.

Practical provider notes (summary, not exhaustive):

  • Use both SPF and DKIM where possible; ensure the From: header domain aligns for DMARC alignment when required.
  • Use RFC 8058 POST-based one-click unsubscribe where required. Treat mailto: as a provider-specific alternative, not as equivalent to the RFC 8058 POST flow.
  • Keep unsubscribe handling timely; maintain logs proving processing.

Common mistakes and how to avoid them

For each observed problem, list likely causes and safe actions.

Mistake: Header present but POST does not immediately suppress the address

  • Likely cause: endpoint requires a browser session or confirmation, or the suppression system is delayed.
  • Safe actions: send a controlled test request to the documented endpoint; verify the response and suppression record; remove login, cookie, or confirmation dependencies from the RFC 8058 path; retest.

Mistake: Authentication passes in internal checks but Authentication-Results shows failures at receiver

  • Likely cause: misaligned From: domain vs DKIM/SPF signing domains or intermediate forwarding that breaks signatures.
  • Safe actions: confirm DKIM selector and signature on messages as received; verify SPF includes all sending IPs; check for forwarding paths and adopt ARC if necessary (illustrative).

Mistake: Unsubscribes logged but mailbox provider reports unresolved complaints

  • Likely cause: unsubscribe not honored quickly enough, or the unsubscribe method is not one-click for marketing.
  • Safe actions: ensure unsubscribe processing meets provider timeliness (Yahoo example requires honoring within 2 days); log and surface proof for investigations.

Mistake: Treating a mailto link as RFC 8058 one-click

  • Likely cause: provider requirements are assumed to be identical.
  • Safe actions: confirm the destination’s rules; implement the RFC 8058 HTTPS POST headers where required, and retain mailto: only as a supported provider-specific alternative.

Label every unverified scenario illustrative: when providing example curl commands, sample headers, or flow diagrams, mark them as illustrative and not as data from actual mailbox providers.

Validation and retest criteria

Separate the observed evidence, likely causes, safe actions, and formal retest gates.

Observed evidence (what you must collect):

  • Raw received message(s) containing the List-Unsubscribe header and the Authentication-Results header from the provider.
  • For RFC 8058 one-click, the List-Unsubscribe-Post header and DKIM signature covering both unsubscribe headers.
  • Published DNS records for SPF, DKIM, and DMARC.
  • Redacted unsubscribe processing records showing request receipt, suppression completion, and outcome.

Likely causes (if validation fails):

  • Header formatting errors, broken endpoints, DMARC alignment failures, signature stripping by intermediaries.

Safe actions (how to remediate before retest):

  • Correct header syntax and endpoint DNS.
  • Ensure DKIM signing covers the From: domain or aligned domain.
  • Add or adjust SPF records to cover sending IPs.
  • Fix unsubscribe processing to meet provider timeline.

Retest criteria (pass/fail gates — illustrative):

  • Gate 1 (Authentication): Received Authentication-Results shows SPF or DKIM passing for the domain in the From: header or aligned domain. Note: Authentication-Results presence is evidence of receiver evaluation, not a guarantee of placement.
  • Gate 2 (Header presence): For RFC 8058 one-click, received source includes the HTTPS List-Unsubscribe URI, List-Unsubscribe-Post: List-Unsubscribe=One-Click, and a DKIM signature covering both headers. A mailto: option alone does not pass this RFC 8058 gate.
  • Gate 3 (Endpoint): A controlled POST request completes without login or confirmation and results in a redacted suppression record within the applicable provider window (Yahoo: 2 days; Google bulk senders: 48 hours).
  • Gate 4 (Seed inbox transport): A small seed send shows expected delivery behavior (illustrative; placement must be observed via inbox placement testing).

What these results cannot prove:

  • Passing Authentication-Results or having List-Unsubscribe present does not prove the message will reach the inbox for all recipients or remain immune to future filtering. Treat each signal independently and combine them with inbox placement testing.

Ongoing monitoring and maintenance

  • Monitor complaint rates and provider dashboards (e.g., Postmaster Tools) where available. Google and Yahoo publish a below-0.3% spam-rate requirement for the applicable sender categories. Treat this as a provider limit, not an inbox-placement target or guarantee.
  • Continuously collect: raw Authentication-Results, unsubscribe logs, DMARC reports (rua), and complaint loop data.
  • Maintain a change log for DNS, header syntax, and unsubscribe endpoint updates.
  • Periodically seed test campaigns and run inbox placement tests after any infrastructure change (ESP, IP, domain, template).
  • Retain unsubscribe logs and proofs for a reasonable retention period to respond to provider investigations (illustrative retention timeframe should be set by your compliance policy).

FAQ

Is one-click unsubscribe required for all email?

No. Provider rules target applicable promotional or marketing messages; Yahoo explicitly excludes transactional messages from its one-click requirement, and Google’s bulk-sender requirement applies to marketing and promotional mail. Check current requirements for your provider and message category.

Is a visible unsubscribe link in the message body enough?

Not for providers that require the List-Unsubscribe header. Gmail and Yahoo bulk-sender guidance calls for both the applicable header-based method and a visible body link. A body link alone does not meet the one-click header requirement.

Does Authentication-Results: pass guarantee inbox placement?

No. Authentication-Results records the receiver’s authentication evaluation. It is an important signal but does not alone guarantee inbox placement.

Use InboxPlacement's inbox placement test to compare authentication signals and observed seed-mailbox placement after applying the recommended changes. Seed results are samples, not a guarantee for every recipient.

Sources

Related Reading