nanoPost

The WordPress Email Authority

WordPress one-click unsubscribe: where the List-Unsubscribe header comes from

Last reviewed/updated:

A newsletter send just got rejected, and the reason points at one specific piece of the outgoing message: the one-click Unsubscribe button Gmail shows next to the sender’s name. The arrival path varies (a Gmail bounce quoting a compliance error, a warning email from the sending provider, a red row in Google Postmaster), but the fix chain is the same in each case.

The chain starts with the WordPress plugin that generated the send. WordPress core does not add the one-click unsubscribe headers on its own. Nothing in wp_mail() emits them, and no admin setting turns them on globally. The newsletter or CRM plugin doing the send adds them, or does not, and the receiving mail server checks them on the way in against a published standard.

What the receiving server is looking for

Two headers have to appear together in every marketing or newsletter message from a bulk sender:

  • List-Unsubscribe: <https://example.com/unsubscribe/token>, the unsubscribe URL defined in RFC 2369. Gmail and Yahoo ignore the value if the URL starts with http:// rather than https://.
  • List-Unsubscribe-Post: List-Unsubscribe=One-Click, the newer piece defined in RFC 8058. This tells the mail client that a POST to the URL above will unsubscribe the recipient without a browser step.

When Gmail displays the Unsubscribe affordance and the reader clicks it, Gmail sends an HTTP POST to the URL in List-Unsubscribe with the body List-Unsubscribe=One-Click. The endpoint on the WordPress side has to answer that POST and remove the subscriber, without a confirmation redirect and without asking for any further input. Google requires the request be honoured within two days (source); the Gmail sender guidelines page covers the header requirement itself.

The requirement is scoped to marketing and subscribed messages; transactional messages (order confirmations, password resets, receipts) fall outside it. Gmail applies the rule to senders above 5,000 messages per day to personal Gmail addresses; Yahoo aligns with the same requirement but does not publish a numeric threshold. Sites below the Gmail threshold still see the same deferrals in practice, because most bulk-sending infrastructure enforces the header check regardless of volume.

Where the header comes from in a WordPress stack

Four arrival paths cover the WordPress newsletter stack.

Dedicated newsletter and CRM plugins that document adding the header automatically. Three plugins state in their own current documentation that they emit the required headers on bulk sends with no per-message configuration.

  • MailPoet documents that it generates one-click unsubscribe links per subscriber and adds them to any outgoing email that includes the Footer block, which is present by default in the plugin’s templates. A customised template with the Footer block removed will not carry the one-click link, so if a custom template is in use, put the Footer block back before assuming the header is present.
  • FluentCRM’s blog post on the List-Unsubscribe header, last updated August 2025, states that the plugin already implements the one-click unsubscribe header and that no user configuration is required. An optional compliance toggle at Dashboard, Settings, Compliance also enables one-click behaviour on the footer link.
  • Groundhogg’s help article on the header says it has added List-Unsubscribe, List-Unsubscribe-Post: List-Unsubscribe=One-Click, and List-Id to bulk sends since 2019, with transactional email excluded by design. The “Automatically handle unsubscribe notifications” setting at Groundhogg, Settings, Email, Unsubscribe needs the paid Advanced Features add-on, but the RFC 8058 POST path works without it.

Sends routed through an ESP integration. Newsletter Glue and any plugin configured to hand off to Mailchimp, MailerLite, Campaign Monitor, ActiveCampaign, or another ESP put the ESP on the hook for the headers, and every major ESP adds them by default. Newsletter Glue’s own documentation does not make an explicit RFC 8058 claim for its built-in sending engine, so for an install using that engine rather than an ESP, verify a real outbound message with the validator before assuming the headers are present.

Custom wp_mail() broadcasts. A newsletter loop written directly against wp_mail() will not carry these headers unless the code adds them. The $headers array passed to wp_mail() has to include both lines explicitly, the URL has to be HTTPS, and the endpoint that answers it has to accept a POST with body List-Unsubscribe=One-Click and unsubscribe the token without a confirmation page. A GET to the same URL can still show a human-readable confirmation page; only the POST path has to be silent.

Older newsletter plugins that pre-date the 2024 requirement. A plugin that has not shipped an update touching the header since Gmail’s February 2024 change is a strong candidate for the deferral. Confirm with the validator; if no plugin update is available, move the newsletter to one of the dedicated plugins above or hand the send off to an ESP.

How to test

Send a message from the WordPress install to any mailbox you control, open it, use the mail client’s “Show original” or “View source” option, and paste the raw headers into the List-Unsubscribe Validator. It reports whether both required headers are present, whether the URL is HTTPS, and whether the value of List-Unsubscribe-Post matches the RFC 8058 literal string.

A pass on the static check means the headers arrived formatted correctly. It does not confirm that the endpoint on the WordPress side actually processes the POST. For that, run the List-Unsubscribe Live Tester, which issues the actual POST that Gmail would issue and reports the response. A working endpoint returns a 2xx status and removes the token; a confirmation page, a redirect, or a 4xx counts as a failure under Gmail’s rules, even if a human clicking the link in a browser sees something reasonable.

What breaks it

Three failure modes account for most of the deferrals in this category:

  • HTTP instead of HTTPS. The URL in List-Unsubscribe has to start with https://. Sites still serving mixed content, or plugins that generate the URL from a stored option that predates the site’s TLS migration, sometimes ship an http:// URL. Gmail and Yahoo ignore it.
  • Only one of the two headers present. List-Unsubscribe on its own is the pre-2018 pattern. Without List-Unsubscribe-Post, Gmail does not treat the message as one-click compliant.
  • The endpoint returns a confirmation page. A POST that responds with a 200 and a “click here to confirm your unsubscribe” HTML page counts as a failure; the POST itself has to unsubscribe the recipient.

One adjacent gotcha, often flagged next to a real header failure: a plugin that emits the header on transactional mail too. That is not a receiver-side compliance failure, but it can trigger review at the ESP, since transactional flows are not supposed to carry the one-click affordance. Scope the header emission to newsletter and marketing sends only.

When the validator confirms both headers on a real message and the live tester returns a 2xx, the site has cleared the one-click unsubscribe requirement. Authentication (SPF, DKIM, DMARC) is a separate bulk-sender requirement, checked elsewhere.

Related coverage

Changelog

  • 2026-09-03 – Published. Plugin claims verified against MailPoet KB #423, FluentCRM blog (updated 2025-08-14), Groundhogg help #890, and Newsletter Glue docs (no explicit RFC 8058 claim in current documentation) at publication date.