By using Customer.io’s unsubscribe functionality, you can offer your customers a way to opt out of your messages. We’ll be able to track the unsubscribe to the specific message they unsubscribed from. For emails, you can also include an unsubscribe option in your email headers.

How unsubscribes work

Unsubscribes in Customer.io are managed using a user profile attribute named unsubscribed that should be assigned a value of true for anyone that is to be treated as unsubscribed. When someone clicks an unsubscribe link that we generate for you, we take care of updating the value of the unsubscribed attribute to true. You can manage this behaviour yourself if you’d like a bit more control.

The behavior of messages sent after a person’s unsubscribed attribute becomes true is determined first by a global campaign setting, then by individual message settings.

Default behaviour

Messages will not send to a person who is unsubscribed. However, you can choose to send to them. For campaigns and API triggered broadcasts, you’ll see a switch in Global Workflow Settings:


For Newsletters, there is a switch under Sending Options on the recipients page.


This is unchecked by default. To send your entire campaign or broadcast to unsubscribed users, check this box.

You can also click into an individual message and use the Sending to Unsubscribed dropdown to adjust individual message behavior:


We have more information on sending behaviour here.


Please remember that continuing to email someone who has unsubscribed could result in your breaching anti-spam laws in your country, and we do reserve the right to terminate your account if you do so.


What messages will someone stop receiving after unsubscribing?

By default, if a customer is unsubscribed, we will not send them:

  • Newsletters
  • Segment triggered campaign messages (including Push and SMS)
  • API Triggered Broadcast messages (including Push and SMS)

Slack and webhooks will send to unsubscribed, as we find these are often used for internal purposes.

For transactional use cases (password resets or invoices, for example), you can override this default setting, by flipping this switch in the Global Settings of your workflow:


You can also adjust this setting on an individual message. On emails, Push, and SMS messages, you’ll see this option:


Unsubscribing a person in the user interface

You can do this on an individual’s Person page, where you can see an ‘Unsubscribe’ button:


Unsubscribing a person via JavaScript/our API

Through the API, you’ll need to identify the customer and set the attribute unsubscribed equal true.

<script type="text/javascript">
  // Only send this when a user is logged in
  id: 'user_287',
  unsubscribed: true

There are two Liquid tags that will assist you in generating unique unsubscribe links for your messages: {% unsubscribe %} and {% unsubscribe_url %}. They work differently and which one you use will depend on what you need in your message but, in both cases, we add the List-Unsubscribe header to your email automatically.

 Test sends do not contain a List-Unsubscribe header

If you are sending ad hoc test emails from the template composer, it is worth nothing that the List-Unsubscribe header will not be included in those sends.

This header is only included in live sends from your campaign or newsletter, as the header requires the recipient’s identifier in order to attribute the unsubscribe request back to their profile and delivery.

The {% unsubscribe %} tag generates the entire link for you and should be placed anywhere you want us to insert our default unsubscribe link. The {% unsubscribe %} is automatically untracked; you do not need to add anything to it to prevent it from tracking clicks.

Use {% unsubscribe_url %} if you want to style the link in your email. This tag only generates the URL for your unsubscribe link (rather than generating the entire code for the link); you should place it anywhere you would normally place the URL for the link you want to use for your link.

When using the code and rich text editors, that means placing the {% unsubscribe_url %} tag in the href attribute of an <a> element in the HTML as pictured below:

Untracked unsubscribe link in the Rich Text editor
Untracked unsubscribe link in the Rich Text editor

When using the drag and drop editor, that means placing the {% unsubscribe_url %} tag in the settings for the link you create as pictured below:

Untracked unsubscribe link in the Drag and Drop editor
Untracked unsubscribe link in the Drag and Drop editor

That will result in a custom link that says what you want and is able to be styled. The default unsubscribe_url link is automatically untracked. When using the {% unsubscribe_url %} tag you don’t need to add anything to the link or button to ensure that it is untracked. If you want to track it, add class='tracked' to the <a> element in the HTML.

An unsubscribe link is added by default in the Empty Layout used for new Rich Text and Code-based emails. Edit this Layout by going to the Layouts tab in your Workspace.


In the drag and drop editor, remove the unsubscribe link by editing or deleting the block.


If a user unsubscribes from email, what happens?

For emails, a user clicks the link in the email and arrive at a page that looks like the image below.

screenshot of the unsubscribe landing page
screenshot of the unsubscribe landing page

If they click the unsubscribe button, we set the unsubscribed attribute = true and confirm that they are unsubscribed.

screnshot of the unsubscribed confirmation page
screnshot of the unsubscribed confirmation page

If they accidentally unsubscribe, they have the option to resubscribe. If they click the resubscribe button, we set the unsubscribed attribute to false and confirm that they are subscribed once again.

How do I handle more complex messaging preferences?

There are a couple of ways to do this, depending on your specific setup. We have a whole doc dedicated to multiple subscription types!

We don’t programmatically enforce it but we encourage it. If you are sending marketing email, you should adhere to all local laws about customer communication.

No. While we require you to include an unsubscribe whenever necessary and legal, we allow you to use your own unsubscribe functionality if you so choose. If you do, though, we won’t be able to track which email someone unsubscribed from or place an unsubscribe in your email header.

How do I send my customers to an unsubscribe page in another language?

The unsubscribe page will display in the language of your customer’s browser as long as this language is supported (see our list below).

If you’d like to manually set the unsubscribe page language, append the optional parameter lang= within the {% unsubscribe_url %} liquid. For example, to redirect users to a French translation of the unsubscribe landing page use {% unsubscribe_url lang='fr' %}. This parameter accepts valid IETF Language Codes for any of the languages we currently we have translations for.


Please note the use of single quotes around the language code ('fr'). This is important if the code is being placed in a link in the drag-and-drop editor. It’s also important for links enclosed in double quotes ( href="{% unsubscribe_url lang='fr' %}") that are placed in an href attribute in our rich-text or code editors. If you nest double quotes inside double quotes OR single quotes inside single quotes, your link will not work as expected.

Currently supported languages:

Brazilian Portuguesept-br

If an invalid or unsupported language code is provided, we default back to the English unsubscribe page. We are always willing to add additional languages, so please let us know if you can provide a translation!

Copied to clipboard!