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.
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.
List-Unsubscribe.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.
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.
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.
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.
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.
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!
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).
Article Number: 245
Author: Oct 26, 2026
Last Updated: Oct 26, 2026
Author: Ruth Cheesley [[email protected]]
Online URL: https://kb.mautic.org/article/how-to-set-up-one-click-unsubscribe-in-mautic.html