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:


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


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:


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.


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:


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


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:


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.
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 arrives at a page that looks like the image below.


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


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!
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 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:
Language | Code |
---|---|
Brazilian Portuguese | pt-br |
Bulgarian | bg |
Chinese | zh |
Czech | cs |
Danish | da |
Dutch | nl |
English | en |
Estonian | et |
Finnish | fi |
French | fr |
German | de |
Greek | el |
Hebrew | he |
Hungarian | hu |
Italian | it |
Japanese | ja |
Latvian | lv |
Norwegian | no |
Polish | pl |
Portuguese | pt |
Romanian | ro |
Russian | ru |
Slovak | sk |
Spanish | es |
Swedish | sv |
Thai | th |
Turkish | tr |
Ukrainian | uk |
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!