List-unsubscribe in e-mail header. How-to?

Question

I'm trying to add a List-Unsubscribe header to my e-mail that is being sent. So far I hadn't any luck trying to do so.

What I have got so far:

var mailMessage = new MailMessage
                    {
                        Subject = newsletter.Subject,
                        Body = newsLetterHTML,
                        IsBodyHtml = true,
                        Sender = new MailAddress(senderAddress)
                    };
                    mailMessage.To.Add(subscriber.Email);
                    mailMessage.ReplyToList.Add(senderAddress);
                    mailMessage.Headers.Add("List-Unsubscribe", unSubscribeUrl);

The unSubscribeUrl is something like 'www.example.com/unlist?id=8822772727'. When I sent the e-mail everything works fine except for the list-unsubscribe option. Which is not shown in any mail client.

Any assistance would be welcome!

UPDATE
This is the whole code I use for sending the email:

var mailMessage = new MailMessage
                    {
                        Subject = newsLetter.Subject,
                        Body = newsLetterHTML,
                        IsBodyHtml = true,
                        Sender = new MailAddress(senderAddress)
                    };
                    mailMessage.To.Add(subscriber.Email);
                    mailMessage.ReplyToList.Add(senderAddress);
                    mailMessage.Headers.Add("List-Unsubscribe", String.Format("<{0}>", "http://www.foo.com/unlist?id=8888"));
                    mailMessage.HeadersEncoding = Encoding.Default;

                    var smtpClient = new SmtpClient();
                    smtpClient.Send(mailMessage);

UPDATE 2
After a little research I got the header into the mailMessage. When I sent an email I can see the following headers:

List-Unsubscribe: <http://demo.localhost/home/hobbymap-gerard/afmelden-voor-nieuwsbrief?id=c786aeb0-554d-4670-94d8-82d6f25a050b>
MIME-Version: 1.0
From: [email protected]
To: [email protected]
Reply-To: [email protected]
Date: 8 Feb 2011 09:50:22 +0100
Subject: Test met plaatje
Content-Type: text/html; charset=us-ascii
Content-Transfer-Encoding: quoted-printable  

But when I open the email in any client I can't see the unsubscribe button in the client? Am I doing something else wrong?

Vickers

Do you see the "List-Unsubscribe" when you check the message headers at the receiving client? Can you add other headers? Try using WireShark to verify that you are sending the List-Unsubscribe header to the local SMTP server. If so, it may be that your local SMTP server is stripping out that header. – Triable

The RFC only shows mailto: URLs in the examples, maybe they only support mailto: unsubscribes? – Athapaskan

Answer 1

Most email clients only support mailto-links.

Try this, it should work always:

mailMessage.Headers.Add("List-Unsubscribe", "<mailto:[email protected]?subject=unsubscribe>");

The RFC specifies it is possible to use http-links also. But i've found that if you include http-links, the email clients no longer shows the unsubscribe link. I think it's because of the possibility that people only have access to the mail protocol.

So this does not always work:

 mailMessage.Headers.Add("List-Unsubscribe", "<http://www.host.com/list.cgi?cmd=unsub&lst=list>, <mailto:[email protected]?subject=unsubscribe>"; 

Mcnamara

I had this same issue. I had both a http and mailto form in the header and GMail was not displaying the link to unsubscribe. When I removed the http and went with just the mailto url, it worked fine. – Guib

It is an outdated answer but for history... GMail and MS Outlook (and m.b. other popular clients) no longer show unsubscribe link. You should deserve reputation of honorable sender. After that ESP MAY add your address to whitelist and allow users to see unsubscribe link in UI. Furthermore for those who implements DKIM: if DKIM check fails it also may be because of max LENGTH violation of this header. I've tested different List-Unsubscribed header length and discovered that GMail fails DKIM if string is longer than 60 chars (UTF-8). And both mailto and http versions had passed check. – Anet

@VictorPonamarev spent couple of days to find reason and fix it. So you can use List-Unsubscribe longer than 60 chars if set up "relaxed" Canonicalization in /etc/opendkim.conf than "simple". And no one word about it in the RFC... – Unbolted

GMail only displays the unsubscribe link after validating that the sender is legitimate. See <https://mcmap.net/q/536863/-list-unsubscribe-header-doesn-39-t-show-unsubscribe-link-in-gmail> – Pentamerous

Answer 2

In addition to other answers, there is also RFC-8058 that requires another header to enable HTTPS link unsubscribe functionality:

List-Unsubscribe:<https://example.com/unsubscribe.html?opaque=123456789>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

List-Unsubscribe-Post header should have a value List-Unsubscribe=One-Click. This is to prevent accidental unsubscribe by anti-spam software and allow an extra step of displaying a web page with an unsubscribe button.

Some email client will not process List-Unsubscribe links without List-Unsubscribe-Post header.

Foliaceous

Answer 3

According to the List-Unsubscribe website, the URL should be wrapped with angle brackets, e.g. <https://www.example.com/unlist?id=8822772727>.

You can try something like:

mailMessage.Headers.Add("List-Unsubscribe", String.Format(
    CultureInfo.InvariantCulture, "<https://{0}>", unSubscribeUrl));

To ensure you are not flagged as spam make sure to have an SSL Certified domain.

Costanzo

Hi Frederic, Thank you for your reply. I tried to add the angle brackets but it doesn't make a difference. I did the following: `mailMessage.Headers.Add("List-Unsubscribe", String.Format("<{0}>", personalUnsubscribeUrl)); mailMessage.HeadersEncoding = Encoding.Default;' – Vickers

@Gerard, did you check that your URL actually starts with http://? I think it might be mandatory. – Kuchen

@Frederic, The url I use is: http://demo.localhost/organisatie/afmelden-via-url?id=a7522a34-5c3d-4b38-8ea9-6c3ed360b377 – Vickers

@Gerard, can you test with a domain other than localhost, e.g. something like http://www.foo.net/...? – Kuchen

@Frederic, nope that doesn't make any difference. – Vickers

@Gerard, maybe the problem is in the mail client. Which one are using for your tests? – Kuchen

@Frederic, I updated the question with the part that sends the emails. – Vickers

I tested its success with gmail as well. It does not identify (: – Mapp

GMail will only display the unsubscribe link after validating that the sender is legitimate. So don't expect your link to show up if the mailing list is new. See <https://mcmap.net/q/536863/-list-unsubscribe-header-doesn-39-t-show-unsubscribe-link-in-gmail> – Pentamerous