MailerSend
Knowledge base

How to add a custom unsubscribe header

A List-Unsubscribe header is an email header that tells mailbox providers (like Gmail, Yahoo or Outlook) how unsubscribes should be handled. When a List-Unsubscribe header is given, providers can enable their native inbox unsubscribe functions to display an unsubscribe option in the mailbox interface, at the top of the email by the sender information.

An example of an email in Gmail with the Unsubscribe option enabled by the List-Unsubscriber header.

By default, MailerSend manages List-Unsubscribe headers for you, ensuring that they are RFC 8058 compliant. Still, if you need to customize your unsubscribe flow (for example, if you are sending multiple brands' emails from a single domain), you can manage the headers yourself if you have a Professional or Enterprise plan.

How List-Unsubscribe headers work

Adding a List-Unsubscribe header involves setting the List-Unsubscribe option and adding a value to define the method. There are 2 methods you can use with the List-Unsubscribe header:

URL method

The URL (or 1-click unsubscribe) option will display the Unsubscribe link at the top of the email, allowing recipients to unsubscribe in a single click.

Remember:

This method is not a replacement for an Unsubscribe link at the bottom of marketing emails.

When the "Unsubscribe" button is clicked, a POST request is sent to the URL specified in the List-Unsubscribe header. The recipient must then be removed or added to your suppressions within 2 days.

Mailto method

The mailto (or email-based method) sends an email message to the email address specified in the List-Unsubscribe header when the "Unsubscribe" button is clicked, instead of triggering a POST request. You will then need to process the unsubscribe request.

Remember:

The mailto method isn't compliant with Gmail and Yahoo requirements so we recommend that you go for the URL method instead.

List-Unsubscribe-Post

List-Unsubscribe-Post is an additional header that is set when using the URL method:

"List-Unsubscribe-Post": "List-Unsubscribe=One-Click"

The header lets mailbox providers know that the subscriber should be unsubscribed in a single click, and in fact, some mailbox providers require the List-Unsubscribe-Post header to be set to this value.

Note:

MailerSend automatically sets List-Unsubscribe-Post for you.

How to add a custom List-Unsubscribe header

To add a custom List-Unsubscribe header, you can use the list_unsubscribe parameter when sending an email with the API.

To add a URL:

POST https://api.mailersend.com/v1/email
{
  ...
  "list_unsubscribe": "https://www.mailersend.com/unsubscribe",
  ...
}

If you add a URL, the List-Unsubscribe-Post and List-Unsubscribe=One-Click options will be automatically set for you, so there's no need to add this yourself.

To add a mailto value:

POST https://api.mailersend.com/v1/email
{
  ...
  "list_unsubscribe": "mailto:unsubscribe@mailersend.com",
  ...
}
Note:

The List-Unsubscribe header is available for Professional and Enterprise plans. For more information, check out our plans and pricing page.

Need more info?

Feel free to reach out to support@mailersend.com. A member of our support team will gladly assist you.