How to set up one-click unsubscribe in Mautic

That little Unsubscribe link Gmail and Yahoo show next to the sender's name is called one-click unsubscribe. Since 2024 it's been required for bulk marketing email at both, and it's also one of the kindest things we can do for the people on our lists. Making it easy to leave beats having folks hit the spam button!

It works through two email headers, defined in RFC 8058. The good news is that Mautic adds them for you. Your job is to make sure they're working.

How it works

Every marketing email carries two hidden headers.

List-Unsubscribe: <https://mautic.yourdomain.com/email/unsubscribe/abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

When someone clicks Unsubscribe in Gmail or Yahoo, the mailbox provider sends a request to that link behind the scenes. Mautic unsubscribes the contact straight away, without them ever visiting your site.

Mailbox providers only show the button when the email has a valid DKIM signature that covers both headers. That's the part that most often goes wrong.

Before you start

Mautic 4.4.11 or later
DKIM working for your sending domain, see How to set up DKIM for Mautic
Your Mautic site served over HTTPS, because the unsubscribe link must use HTTPS

Step 1. Check the headers are there

Send a marketing email (not a transactional one) from Mautic to a Gmail address you control.
Open it, choose Show original from the three-dot menu, and search the source for List-Unsubscribe.
You should see both headers, and the link should start with https://.

If the link starts with http://, fix your site URL in Settings > Configuration > General Settings and make sure your server is serving Mautic over HTTPS.

Step 2. Check DKIM covers both headers

In the same message source, find the DKIM-Signature header and look at the h= list. It must include both list-unsubscribe and list-unsubscribe-post.

If they're missing, it's your email service doing the signing that needs changing, not Mautic. Check your service's settings or contact their support. One community member tracked this exact problem down to how their DKIM signing handled headers when sending through Amazon SES.

Step 3. Test the unsubscribe

Use a test contact in Mautic with your own Gmail or Yahoo address.
Send them a marketing email and click the provider's Unsubscribe link.
Check the contact in Mautic. They should now be marked as Do Not Contact for email.

Gmail doesn't show the button for every sender or every message, so if it doesn't appear, check the headers (Steps 1 and 2) instead of relying on the button.

Things to know

One-click unsubscribes the contact from all email. Mautic sets the contact to Do Not Contact for the email channel, so they won't get any marketing email from that Mautic instance, even if they only meant to leave one newsletter. Community members running several newsletters from one instance have raised this. Keep it in mind when you plan segments, categories and your preference centre, and be clear on your forms about what people are signing up for.

Keep a visible unsubscribe link too. The header doesn't replace the link in your email footer. Use the {unsubscribe_text} or {unsubscribe_url} tokens in your email templates.

List-Id is optional. Some testing tools complain when there's no List-Id header. You can add one as a custom header on an email's Advanced tab.

Transactional emails don't need it. One-click unsubscribe is required for marketing email only, and Gmail exempts transactional messages. Don't send marketing content as transactional to dodge it, though!

Act within two days. Gmail asks senders to honour unsubscribes within 48 hours. Mautic does it immediately, so you're covered.

If you build your own unsubscribe endpoint

Some integrators replace Mautic's unsubscribe link with their own. If you do, your endpoint must accept a POST request with the body List-Unsubscribe=One-Click, must not redirect, must not need cookies or a login, and should use a hard-to-guess token in the link so nobody can unsubscribe your contacts by guessing. Note that Mautic still adds its own link alongside yours.

Quick checklist

Mautic 4.4.11 or later, served over HTTPS
Both headers present in marketing emails
Both headers included in the DKIM signature
Test unsubscribe marks the contact as Do Not Contact
Visible unsubscribe link in every marketing email

Over to you

How are you handling one-click unsubscribe when you run several newsletters from one Mautic instance? I'd love to hear your approaches, and it's a great topic for our product team too!

References

Google Email sender guidelines FAQ. Gmail Help. Available at https://support.google.com/mail/answer/14229414?hl=en-GB (Accessed 26 October 2026).

Levine, J. and Herkula, T. (2017) Signaling one-click functionality for list email headers. RFC 8058. Internet Engineering Task Force. Available at https://www.rfc-editor.org/rfc/rfc8058.html (Accessed 26 October 2026).