List-Unsubscribe header

My Mautic version is: 2.16.2
My PHP version is: 7.3.17-1
My Database type and version is:

Your problem
Can anyone help - I have just been checking with Litmus on inbox deliverability and I’m getting a message saying that there is an issue with some systems (outlook) being the main one. They are saying that have an issue with my List-Unsubscribe header. does anyone have any ideas on how I can fix this?

The message I got was:
We have detected your message does include a List-Unsubscribe header, however it only provides the URL and does not include the mailto: function. Litmus recommends including a valid and monitored email address option when implementing the List-Unsubscribe header in marketing messaging.

Hi @harry5

Welcome to the Mautic Forums. I think they mean you need an unsubscribe link in your email.

You can add {unsubscribe_url} in your email as a link.

Some of the Tokens Available in the Email builder:
Unsubscribe Text: {unsubscribe_text}
Unsubscribe URL: {unsubscribe_url}
Web View Text: {webview_text}
Web View URL: {webview_url}

Hi @codes9

thanks for the response, No its the email header where I’m having the issue. I do have the unsubscribe in the body as you say but Litmus is claiming there is an issue in the email header that I should resolve.

its driving me slightly crazy


You’re right it’s referring to the email header. This can be set by your mail server if you set it up. But you can set this on the email in Mautic:

Your email should include this in the header section. The last part would be the Unsubscribe URL for your mail.

List-Unsubscribe: <mailto:>, <>

Thanks @codes9

I think I understand now. a couple of questions:

  1. instead of adding on each email can I add it to the custom email headers in the config so that it appears on every email automatically? Screenshot 2020-11-09 at 19.39.56
  2. i get everything apart from the bit. how do I create the URL? this is dynamic right? (it will be different for each user)

thank you for you help this is really useful

Global custom email headers can also be setup in your config. Click the Gear icon => Configuration => Mail & Send Settings


The unsubscribe URL would be the same link that is rendered from the short-code inside your email as I referenced above. You’ll have to check what renders in your emails if you put this link. I’ve not tested if this short-code will render in the custom headers section. If you configure custom unsubscribe forms for each email you may need to set-up the header per email.


Thank you for your help. I will give it a try

Hello @harry5,
Thx for bringing up this important topic.
The email is added if you have a monitored mailbox. There was a bug related to this, you can see there how this email looks like:

If you want to know more about monitored mailbox, you can find it here:

Good luck to you!

thanks @joeyk

I’m using SES for sending so not using the monitored inbox. I haven’t had a chance to test yet but will feedback as soon as I have.

Hi, I also use Amazon SES. Monitored inbox for your bounces is just an extra setup to generate the mailto unsubscribe and please Litmus.

At the risk of replying to a thread that isn’t active anymore, I tried following the suggestion here to add a List-Unsubscribe header to all emails via Email Sending configuration. However, this doesn’t seem like a valid solution because the headers in these configurations aren’t applied to Mautic emails (see the tooltip):


I don’t want to add the List-unsubscribe header to all emails manually because our emails are created and sent via the REST API. I also saw that the REST API doesn’t provide the capability for adding custom headers to emails created through it.

Is there another alternative that I have missed?