2. One-click Unsubscribe

1. There must be a visible unsubscribe link in the email body—it is fine if it redirects to a preference page.
2. Unsubscribes must be handled within 2 days.
3. Implement one-click unsubscribe.

1 and 2 are pretty straight forward. 3? May be not so much.

What is one-click unsubscribe?

One-click unsubscribe is an extension of a feature called List-unsubscribe.

List-unsubscribe is a feature you can define in your emails to let the receiving mailbox know receivers can unsubscribe from the email. This makes it possible for the mailbox to provide an easy way for receivers to unsubscribe—an unsubscribe button for example.

List-unsubscribe is added to a part of the email called the email header. (Email headers are used to add additional information to the email in a way that is not visible in the email content).

Mailboxes interpret the unsubscribe header in different ways. If an email contains one, you should see a custom "Unsubscribe" button somewhere at the top of the email.

A list-unsubscribe header will contain an unsubscribe URL or an email for unsubscribe request, or both. One-click unsubscribe extends this with an additional header to "tell" the unsubscribe URL the request is a one-click unsubscribe request. This means the unsubscribe should be processed with no further requirements from the user.

Note that the fact that the "Unsubscribe" button is not shown doesn't mean the list-unsubscribe header wasn't added to the email. Your mail provider may decide to not show the button even though the header is present.

To confirm, you can view the message header and search for "List-unsubscribe" to see if it exists. Here is how to view the message with headers in Yahoo! Mail and Gmail on the web:

How do I implement one?

If you use an email marketing tool, your service provider would automatically take care of this for you. We do. If you are not sure, you can check one of the campaigns you have sent to yourself as explained above.

If you want to manually do it, you need to add the following headers to the email.

List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Unsubscribe: <https://yoursite.com/unsubscribe>, <mailto:[email protected]>

The List-Unsubscribe header includes both the unsubscribe URL and unsubscribe email. Either form is allowed for the header but we recommend you use both. Some services only support the mailto option.

You should be able to automatically process unsubscribes via incoming emails to the unsubscribe email address.

Once unsubscribe is clicked, a POST request (with multipart/form-data or application/x-www-form-urlencoded encoding) is made to the unsubscribe URL with the following data: List-Unsubscribe=One-Click. From there, process the unsubscribe as you would normally do if the URL is visited directly.

But I use an API, how can I add an email header?

Your email API service should have a feature to add custom email headers. If not, they should provide a way to send an email with the list-unsubscribe header. Here are some examples: Mailgun, Sendgrid and AWS SES.

If you really want to handle it yourself, here:

For Sendgrid, you can add a headers object to the request parameter for Send (v3) like this:

{
  "personalizations": [{
    "to": [{
      "email": "[email protected]"
    }],
    "subject": "Your subject line here"
  }],
  "from": {
    "email": "[email protected]"
  },
  "content": [{
    "type": "text/plain",
    "value": "Hello, World!"
  }],
  "headers": {
    "List-Unsubscribe": "<mailto:[email protected]>, <http://www.unsubscribe.example.com>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

For Mailgun, additional headers can be added to the form parameters for the messages API like this:

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Subject line",
  "html": "Hello world",
  "h:List-Unsubscribe": "<mailto:[email protected]>, <http://www.unsubscribe.example.com>",
  "h:List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
}

For Amazon SES, it is a little different. You need to create a mime message with the headers and use SendRawEmail (or its equivalent in your choice language's SDK) to send the email.