Unsubscribe Processing in Hurricane MTA Server

Hurricane MTA can be used to generate, insert, and manage unsubscribe links in the headers and body of an email message.

HMS can insert an unsubscribe link and/or a One-Click List-Unsubscribe header (http and/or mailto) in your outbound messages. These mechanisms are also integrated with the suppression system in HMS so that, if properly configured, unsubscribed addresses are suppressed from future delivery. For more information on List-Unsubscribe, please see RFC2369. 

Adding an unsubscribe link and/or One-Click List-Unsubscribe header to your outgoing email messages can help your reputation and may help to keep you compliant with regulations that may require certain unsubscribe features in your messages.  A visible unsubscribe option gives the recipient a friendlier alternative to clicking the spam button which would likely cause more damage to your reputation and deliverability.  As of June 1st, 2024 both Google and Yahoo require bulk senders to include a One-Click List-Unsubscribe header for messages to be eligible for inbox placement. 

Enabling Unsubscribe Link & HTTP List-Unsubscribe Header

Step 1 - Enable Engagement Tracking on the MTA

Enable and configure the tracking server in the Open/Click Tracking global settings.  This turns on the tracking engine that will process the unsubscribe requests.

Step 2 - Enable Engagement Tracking on the Account

In the Account level Engagement Tracking settings, enable the Unsubscribe Processing option and specify a Tracking Server Host for this Account. This host will be used in the List-Unsubscribe header. To add unsubscribe headers to all messages also enable the "Force Tracking" feature. If "Force Tracking" is not enabled, then only messages that contain the placeholder tags described in Step 5 will have the headers and links inserted. 

Step 3 - Suppress Unsubscribing Addresses

Optional: If you would like the MTA to suppress further messages from the addresses that complete the unsubscribe process, then in the Account level Suppression List settings, specify a suppression list for the Add Unsubscribes To option and also make sure to specify that same list in the Check Against option, if you wish to suppress unsubscribes.

If you choose not to use the MTA suppression system for managing the blocked addresses, we recommend you use the logs or HTTP webhooks to only collect the unsubscribe events and process them against your audience through other means.  

Step 4 - Denote Support for One-Click (RFC8058)

With the first three steps completed, the MTA will now be inserting a standard List-Unsubscribe header. To denote support for the One-Click List-Unsubscribe functionality which is required in order to be compliant with the Google and Yahoo requirements, you must also have the MTA also add the List-Unsubscribe-Post header. This can be done either when generating the messages in your software/applications, or it can be inserted by the MTA.

Custom header insertion in the MTA can be achieved utilizing the general.config file. This is located in the Hurricane MTA Server installation directory. In the Accounts folder, choose the account for which you'd like to have the header inserted, then navigate into the config directory and edit the general.config file:

Under the "Other" section you will add:

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

More information about header insertion with the MTA can be found here  

Step 5 - Add the Unsubscribe Link in the Content

Optional: 

The MTA can also insert an unsubscribe link into the body of an email message. It is not required to use the MTA for both body and header unsubscribe mechanisms.  You can deploy just the One-Click List-Unsubscribe headers via the MTA, only the body unsubscribe links, or both.  

To insert an unsubscribe link in the message body, you must insert the proper code in your message content where you want the unsubscribe link to appear:

For text content:

This is my message.
{{HsUnsubscribe}}

Which will generate a link similar to:

http://[hms tracking server address]/unsubscribe?r=[encoded information]

For HTML content:

<HsUnsubscribe>Custom Link Text</HsUnsubscribe>

Which will generate a link similar to this:

<a href="http://[hms tracking server address]/unsubscribe?r=[encoded information]">Custom Link Text.</a>

In addition to generating the appropriate links in your message content, these settings will also cause an http List-Unsubscribe header to be added to your message if "Force Tracking" is not enabled.  

[hms tracking server address]

This value is specified in the Account level Other settings configuration and should resolve to the public internet address of your Hurricane MTA Server.

[encoded information]

This value is encoded and will contain the recipient’s email address and other information.

Processing of the Unsubscribe Link & One-Click List-Unsubscribe Header

When an unsubscribe link from the message body is loaded from HMS, it returns a web page similar to:

Thank You Your request to remove your email address, john@example.com from our mailing list has been received. Please allow up to 72 hours to account for any currently pending messages.

This event will also notify the suppression system that an Unsubscribe has occurred for the original recipient’s address.  If the suppression system has been setup properly (see step 3 above) future emails to the recipient’s address should fail.

Enabling MailTo List-Unsubscribe Header

While not required by mailbox providers, and now considered to mostly be a legacy mechanism for processing unsubscribe events, Hurricane MTA also supports the MailTo list-unsubscribe mechanism. 

To have a mailto List-Unsubscribe header added to your messages you can follow the instructions below:

In the Account level Bounce Handling Options enable and configure Bounce Handling and make sure to select the Auto Add & Process List-Unsubscribe option as well as specifying the Recipient Address as one of the pieces of tracking information to include in the return path.

This will add a List-Unsubscribe header to your outbound messages on this account, that looks something like this:

List-Unsubscribe: <mailto:[encoded information]@[bounce domain]>

[encoded information]

This value is encoded and will contain the recipient’s email address and other information.

[bounce domain]

This value is the Bounce Domain specified in the Account level Bounce Handling Options configuration.

Processing of MailTo List-Unsubscribes

When email is sent to the address in the mailto List-Unsubscribe header, it will be processed by HMS as a bounced message with the code of 6000.  This event will also notify the suppression system that an Unsubscribe has occurred for the original recipient’s address.  If the suppression system has been setup properly (see step 2 above) future emails to the recipient’s address should fail.