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.

...in triggered campaigns, and API triggered broadcasts

Messages in these campaigns, by default, do not send to unsubscribed people. You'll notice this at the top of the workflow, where the "Send messages to unsubscribed users" box is unchecked:


This is because these campaign types are generally used for marketing messages that people may want to opt out of.

To override this default, you can click into an individual message and click Edit next to 'Don't send to unsubscribed':

Unsubscribe edit

You'll then be able to choose your preferred sending behavior:


We have more information on sending behaviour here.

Sending to Unsubscribes

As shown above, you can choose to send to unsubscribed users both at the campaign level and on the individual action. We ask that you be careful when doing this, and only recommend it in transactional use cases. 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.

Newsletters will also not be sent to unsubscribed people; however, there is an option to override this too. You may have noticed this option:

Option: send newsletters to unsubscribed users

You can learn more about the newsletter behaviour here.


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 checking this box in the workflow:


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


Clicking 'Edit' will allow you to set the specific behavior for that message:

  • Sending to unsubscribed people
  • Not sending to unsubscribed
  • Use the default for the campaign

Unsubscribing a person in the user interface

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

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?

This depends on which editor you're using for your emails.

...in the text and code editor

When using the text and code editor (or creating an associated Layout), you can insert code similar to the following and we'll render a unique unsubscribe link for that person:

<a href="{% unsubscribe_url %}" class="untracked">Unsubscribe</a>

If you don't want clicks on the unsubscribe link to be tracked, be sure to include class="untracked"in your unsubscribe link!

...in the drag-and-drop editor

By default, each new email created in our drag-and-drop editor includes an unsubscribe link. If you accidentally delete it, just paste the following text into your email to re-add it:

{% unsubscribe %}

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. Currently we have translations for German, Greek, Spanish, French, Japanese, Polish, Portuguese, Romanian, Russian, Thai, Turkish, and Chinese. 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?