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 attrbute 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:


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

For Newsletters, you can check the "Send to unsubscribed" option on the recipients page.


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

How do I add an unsubscribe link to my emails?

There are two Liquid tags that will assist you in generating unique unsubscribe links for your messages. {% unsubscribe %} an {% unsubscribe_url %}. They work differently and which one you use will depend on what you need in your message.

{% unsubscribe %}
This tag generates the entire link for you and should be placed anywhere you want us to insert our default unsubscribe link. The default unsubscribe link will always say "unsubscribe" and it will always be untracked automatically. When using the {% unsubscribe %} tag you never need to add anything to the tag to ensure that it is untracked.

{% unsubscribe_url %}
This tag generates just the URL to be used in a link (rather than generating the entire code for the link) and should be placed 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

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

That will result in a custom link that says what you want and is able to be styled.

Now, one point of clarification. Using the {% unsubscribe_url %} tag means the links you create will no longer be untracked by default so you will have to take an extra step to prevent those custom unsubscribe links from being tracked in your stats.

In the code and rich text editors, this means adding class='untracked' to the <a> element in the HTML as pictured below:

Untracked unsubscribe styled link in the Rich Text editor

In the drag and drop editor, unfortunately, this means using an HTML block instead of the link method pictured above. This is because the drag and drop editor will not allow you to add anything like class='untracked' which is required in order for our system to no track the link. You would first add the HTML block to your email (the same way you add a text block - just choose HTML instead of TEXT). Then you would add the HTML code for your link in the content properties as pictured below (not that we broke the code into multiple lines so that you could see it all but in reality, it will usually all be on one line):

Untracked and styled unsubscribe link in the Drag and Drop editor

Here's the code pictured above for the link:

<a href='{% unsubscribe_url %}' class='untracked' style='color:red;'>Click this custom text to unsubscribe!</a>

Note, in that code and in the last two images, there's also code to style the link (style='color:red;'). That is not required and is only there so you can see how styles can be added as well. If you are not comfortable working with HTML or CSS styles, you'll want to consult with a web developer in order to get the custom links styled the way you want them to be.

How do I remove an unsubscribe link from my emails?

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.

Unsubscribe page

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

Unsubscribe successful

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!

Does every email require an unsubscribe link?

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.

Do you require us to use your unsubscribe link in emails?

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_url %} liquid can include an optional parameter lang= to redirect to the unsubscribe page in another language. For example, to redirect users to a French translation of the unsubscribe landing page use {% unsubscribe_url lang='fr' %}. This parameter accepts valid ISO 639-1 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 or in an href attribute in our rich text or code editor that is enclosed in double quotes ( href="{% unsubscribe_url lang='fr' %}"). If you nest double quotes inside double quotes OR single quotes inside single quotes, your link will not work as expected.

Currently supported languages:

  • Chinese
  • Dutch
  • French
  • German
  • Greek
  • Italian
  • Japanese
  • Polish
  • Portuguese
  • Romanian
  • Russian
  • Spanish
  • Swedish
  • Thai
  • Turkish.

If an invalid 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!

Was this article helpful?