Unsubscribes

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.

 Customer.io now has a subscription center!

This article covers global unsubscribes. Go to our subscription center for information on unsubscribing from topics.

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.

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 dropdown in Settings:

In campaign settings, All subscribed is selected by default in workspaces where the subscription center is not enabled.
In campaign settings, All subscribed is selected by default in workspaces where the subscription center is not enabled.

For Newsletters, you’ll see a dropdown in Recipients:

In newsletter settings, All subscribed is selected by default in workspaces where the subscription center is not enabled.
In newsletter settings, All subscribed is selected by default in workspaces where the subscription center is not enabled.

To send your entire campaign or broadcast to unsubscribed users, select “All subscribed and unsubscribed” from the dropdown.

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

image.png
image.png

We have more information on sending behaviour here.

 Warning

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.

Branding

You can update branding for your global unsubscribe page from Settings > Workspace Settings > Subscription Center. Select the Settings tab. Then click Edit for Branding.

You can choose to use the logo for your account or upload a new one and change the background color of the Unsubscribe button.

On the left you can choose to upload a logo or change the backgorund color of your unsubscribe button. On the right you can preview the changes before making them live.
On the left you can choose to upload a logo or change the backgorund color of your unsubscribe button. On the right you can preview the changes before making them live.

FAQ

What messages will someone stop receiving after unsubscribing?

By default, if a customer is globally unsubscribed, we will not send them emails, Push or SMS for any campaign or broadcast.

We continue to send slack messages and webhooks to unsubscribed, since these are often used for internal purposes. In-app messages also ignore users’ global, unsubscribed status.

Keep in mind, transactional messages (password resets or invoices, for example) send to unsubscribed by default, but you can toggle that off in the message’s settings or override it through our API.

For other transactional use cases, you can override the default audience through your campaign or broadcast settings.

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

image.png
image.png

Unsubscribing a person in the user interface

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

image.png
image.png

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
  _cio.identify({
  id: 'user_287',
  unsubscribed: true
});
</script>

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. This header globally unsubscribes people from messages, never from a single subscription topic.

 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.

layout_unsubscribe_link.png
layout_unsubscribe_link.png

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

drag_and_drop_unsubscribe_link.png
drag_and_drop_unsubscribe_link.png

If a user unsubscribes from email, what happens?

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

The subscription landing page reads: Do you want to unsubscribe from our messages? You'll stop receiving messages from us. There is a button labeled Unsubscribe.
The subscription landing page reads: Do you want to unsubscribe from our messages? You'll stop receiving messages from us. There is a button labeled Unsubscribe.

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

The subscription landing page reads: You have successfully unsubscribed. Subscribe to receive our messages. You'll start receiving all our messages again. There is a button labeled Subscribe.
The subscription landing page reads: You have successfully unsubscribed. Subscribe to receive our messages. You'll start receiving all our messages again. There is a button labeled Subscribe.

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?

Check out our subscription center!

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.

 Notice

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:

LanguageCode
Brazilian Portuguesept-br
Bulgarianbg
Chinesezh
Czechcs
Danishda
Dutchnl
Englishen
Estonianet
Finnishfi
Frenchfr
Germande
Greekel
Hebrewhe
Hungarianhu
Italianit
Japaneseja
Latvianlv
Norwegianno
Polishpl
Portuguesept
Romanianro
Russianru
Slovaksk
Spanishes
Swedishsv
Thaith
Turkishtr
Ukrainianuk

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!