How to add a List-Unsubscribe header in your email tool

The two headers, in sixty seconds

Mailbox providers render their own unsubscribe button from two hidden headers in your message, not from the link in your footer:

List-Unsubscribe: <https://example.com/unsub?id=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

List-Unsubscribe (RFC 2369) points at an HTTPS endpoint, and List-Unsubscribe-Post (RFC 8058) signals that the endpoint accepts an automated one-click POST. Since February 2024, Google and Yahoo require both on bulk marketing mail — roughly 5,000+ messages a day — and the message's DKIM signature has to cover them. The full mechanics are in our RFC 8058 one-click unsubscribe guide and the wider Gmail & Yahoo sender requirements guide.

The good news: if you send through a mainstream marketing platform, you probably already comply. The bad news: a few popular tools ship with the headers off until you enable a setting. Jump to yours: Mailchimp · Klaviyo · Kit · MailerLite · Brevo · SendGrid · Postmark · Amazon SES · raw SMTP / self-hosted.

Platform by platform

Mailchimp

Automatic — nothing to enable. Mailchimp adds one-click unsubscribe headers to bulk email on its own; its guidance on the Gmail and Yahoo rules states that all emails sent through Mailchimp meet the unsubscribe requirement automatically. Don't be confused by Mailchimp's two-click confirmation page: that applies only to the unsubscribe link in the email body, not to the header-driven one-click flow, which stays a single click.

Confirm it: send a real campaign to your own Gmail address and inspect the headers (steps below).

Klaviyo

Automatic — nothing to enable. Klaviyo's help center is explicit: it automatically adds the one-click unsubscribe code to the header of every email you send, and there is no action required to meet the Gmail and Yahoo requirement. Your only job is to keep a visible unsubscribe link in the body, which Klaviyo's templates include by default.

Confirm it: send a live campaign or flow email to yourself and check for both headers.

Kit (formerly ConvertKit)

No setting exists — verify with a test send. Kit requires an unsubscribe link in every email it sends and its help center covers Gmail's one-click unsubscribe, but Kit's own documentation does not spell out that it sets the headers, and there is no toggle in the app either way. Independent deliverability write-ups report that Kit handles the headers for you — so treat it as "probably automatic, but verify": send yourself a live broadcast and look for both header lines. If they are missing, contact Kit support rather than trying to work around it.

MailerLite

Automatic — nothing to enable. MailerLite emails include the list-unsubscribe header by default, one-click mechanism included, with no configuration needed. One trap: MailerLite's test emails do not carry the header, so a preview send will look broken when it isn't. Send a real campaign to your own address before concluding anything.

Brevo

Automatic — nothing to enable. Brevo's help center says the list-unsubscribe header is added to your emails automatically, and if a campaign is missing a visible unsubscribe link, Brevo appends a footer with one rather than let the send go out bare. If you also route transactional mail through Brevo, confirm the List-Unsubscribe-Post line on that stream with a test message rather than assuming it matches campaigns.

SendGrid

Not automatic — enable subscription tracking. A bare API or SMTP send through SendGrid ships without the headers. The supported fix is Subscription Tracking: in the dashboard go to Settings → Tracking → Subscription Tracking and turn it on. With it enabled, SendGrid automatically inserts a List-Unsubscribe header carrying both a mailto: and an HTTPS URL, plus List-Unsubscribe-Post: List-Unsubscribe=One-Click, into your emails.

Prefer to keep suppression in your own system? SendGrid's docs also support setting both headers yourself as custom headers in the v3 Mail Send API or over SMTP — SendGrid passes them through, and you host the unsubscribe endpoint.

Postmark

Automatic on Broadcast streams; passthrough on Transactional. By default, Postmark manages unsubscribes for every Broadcast Message Stream: it appends a one-click unsubscribe link to the bottom of each message and adds RFC 8058-compliant List-Unsubscribe and List-Unsubscribe-Post headers. Nothing to configure — though note you cannot edit the headers while Postmark manages them. If you need to run your own unsubscribe flow, the "manage unsubscribes on your own" option in the Broadcast stream settings requires approval from Postmark support, after which you must supply both the visible link and the headers yourself.

Transactional Message Streams do not get the headers (one-off messages don't need them), but if you add your own List-Unsubscribe headers to a transactional send, Postmark includes them as-is.

Amazon SES

Not automatic — use subscription management or add headers yourself. SES gives you plumbing, not policy. You have two routes:

• SES subscription management. Create a contact list, then send with the SESv2 SendEmail operation specifying contactListName and topicName in ListManagementOptions (over SMTP, the equivalent is the X-SES-LIST-MANAGEMENT-OPTIONS header). SES then adds the List-Unsubscribe and List-Unsubscribe-Post headers, hosts the unsubscribe landing page, and suppresses unsubscribed contacts on future sends. The fine print: you must place the {{amazonSESUnsubscribeUrl}} placeholder in the body (at most twice), the headers are only added on single-recipient sends, it works with Easy DKIM but not with messages you DKIM-sign yourself, and SES overrides any List-Unsubscribe headers you set when ListManagementOptions is present.
• Do it yourself. Skip list management and inject both headers into every message, exactly as in the raw SMTP section below, with your own HTTPS endpoint doing the suppression.

Raw SMTP or self-hosted

You own the whole flow. Add both headers to every marketing message you generate:

List-Unsubscribe: <mailto:unsub@example.com>, <https://example.com/unsub/abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

• The HTTPS URL must contain an opaque per-recipient token — the one-click POST arrives with no cookies and no other identifying context.
• Your endpoint must complete the unsubscribe on a POST with body List-Unsubscribe=One-Click, with no login and no confirmation page, and honor it within two days.
• DKIM-sign the message with both list headers included in the signed header list — providers verify this before trusting the one-click flow.
• Keep the visible unsubscribe link in the body as well.

The endpoint requirements are covered step by step in the RFC 8058 guide.

How to confirm the headers are actually there

Whatever your platform promises, trust only a real message. Test previews often skip the headers entirely.

1. Send a live campaign (not a test preview) to your own Gmail address.
2. Open it, click the three-dot menu, choose Show original, then Download original to save the raw .eml file.
3. Upload the .eml to the free checker — it parses your List-Unsubscribe and List-Unsubscribe-Post headers, confirms the HTTPS one-click endpoint, and flags anything Gmail or Yahoo would reject.

Frequently asked questions