Customer.io is a data-driven messaging platform for SaaS product teams, focused on behavior-triggered campaigns, transactional email, and multi-channel journeys (email, SMS, push, in-app). Unlike marketing-first ESPs, Customer.io separates unsubscribe handling at the workspace, message group, and newsletter level, which gives fine-grained control but also creates the most common configuration mistake: sending a marketing campaign under the Transactional API endpoint, which bypasses all unsubscribe logic. This guide covers the exact unsubscribe tokens, the subscription groups model, the RFC 8058 headers Customer.io emits, and the common issues.
Customer.io unsubscribe link: quick reference
| Item | Value |
|---|---|
| Include tag (recommended) | {% include 'unsubscribe' %} |
| Direct URL variable | {{customer.unsubscribe_url}} |
| Newsletter-scoped variable | {{newsletter.unsubscribe_url}} |
| Config path | Workspace Settings > Compliance > Subscription center |
| Scope model | Workspace-level, plus per-Message Group opt-outs |
| RFC 8058 one-click | Yes, auto-generated for Marketing sends when domain is authenticated |
The three unsubscribe scopes in Customer.io
Workspace-level unsubscribe
The default. When the recipient clicks the unsubscribe link generated by {% include 'unsubscribe' %}, Customer.io sets the customer’s unsubscribed attribute to true. Every Campaign, Broadcast, and Journey message that has an unsubscribe check in its filter skips the customer from that moment forward. Use this for straightforward marketing sends where a single opt-out should stop all promotional messaging.
Message Group opt-outs
Message Groups (formerly Subscription Groups) let you split marketing surfaces into topics: Product Updates, Weekly Digest, Promotional. Customers can opt out of one topic without leaving the others. The unsubscribe link in a specific Message Group sets a per-group flag; the workspace-level unsubscribed attribute stays false. Configure Message Groups in Workspace Settings > Compliance > Subscription center.
Newsletter-scoped unsubscribe
When you send via the Newsletters feature (one-off Broadcasts), the {{newsletter.unsubscribe_url}} variable renders a URL that unsubscribes the recipient from that specific newsletter feed only. Useful when the recipient subscribed via a topic-specific signup form and should be able to unsubscribe from that topic without affecting other campaigns.
Adding the unsubscribe link in a Customer.io template
The recommended approach uses the built-in Liquid include, which renders a footer block containing the unsubscribe link, the physical address, and any custom copy defined at the workspace level:
{% include 'unsubscribe' %}For custom placement (in the header, mid-email, or a specific styled block), use the raw URL variable in an anchor tag:
<a href="{{customer.unsubscribe_url}}">Unsubscribe from all marketing emails</a>Customer.io refuses to send a Marketing-tagged Campaign without at least one unsubscribe link in the body. The check is enforced at the workspace level: if you disable the check for a specific Campaign, Customer.io logs a compliance warning that surfaces in Workspace Settings > Audit log.
Configure the Subscription Center
- Go to Workspace Settings > Compliance > Subscription center
- Enable the Subscription Center toggle
- Add Message Groups: Product Updates, Newsletter, Promotional (or your own taxonomy)
- For each Message Group, set the default subscription state (opted-in or opted-out) that new customers receive
- Choose whether the “unsubscribe from all” link is visible on the Subscription Center page. Turning this off forces customers to opt out group by group, which reduces total unsubscribes but risks GDPR concerns if the “unsubscribe from all” path is not clearly available elsewhere
- Save. Every Campaign now checks the Message Group opt-out flag before sending to a customer
Message Groups are applied to a Campaign at the Campaign settings level: pick which Group the Campaign belongs to. Broadcasts (Newsletters) can also be tagged with a Message Group.
RFC 8058 one-click compliance in Customer.io
Since February 2024, Gmail and Yahoo require senders exceeding 5,000 daily emails to those providers to support one-click unsubscribe via the List-Unsubscribe-Post header defined in RFC 8058. Customer.io emits the correct headers automatically for every Marketing Campaign and Newsletter send when the sending domain is authenticated (SPF, DKIM, DMARC).
Transactional messages sent via the Transactional API (/api/v1/send/email) do not include unsubscribe headers by default. This is by design: transactional messages are exempt from CAN-SPAM. However, if a transactional message carries any marketing content (upsell block, cross-sell footer), you must add the headers manually via the API request payload:
{
"identifiers": { "id": "customer-123" },
"transactional_message_id": "welcome",
"message_data": { "name": "Alex" },
"headers": {
"List-Unsubscribe": "<https://track.customer.io/unsubscribe/...>",
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
}
}Testing your Customer.io unsubscribe link
- Send a test to a controlled Gmail address. In the Campaign editor click Preview > Send preview email
- Click the footer unsubscribe. Verify you land on the Subscription Center (or on the workspace-wide unsubscribe confirmation page)
- Check the customer profile. Search for your test email in People; the
unsubscribedattribute should betruewithin seconds - Verify the RFC 8058 headers in Gmail:
List-Unsubscribe: <mailto:...>, <https://track.customer.io/unsubscribe/...>
List-Unsubscribe-Post: List-Unsubscribe=One-Click- Test one-click:
curl -X POST -d "List-Unsubscribe=One-Click" "https://track.customer.io/unsubscribe/..."Expected: HTTP 200 or 202. Verify the customer attribute updated on the profile.
Common issues and how to fix them
Marketing content sent via the Transactional API skips unsubscribe checks
The most common Customer.io mistake. The Transactional API bypasses unsubscribe filters by design, so a customer who has opted out of marketing can still receive a transactional message that happens to include a promotional block. Fix by moving the send to a Marketing Campaign, or by manually checking the unsubscribed attribute in your application logic before firing the transactional call.
Liquid error: could not find template ‘unsubscribe’
The Subscription Center is not enabled at the workspace level. Enable it in Workspace Settings > Compliance > Subscription center. Once enabled, the unsubscribe include becomes available as a Liquid partial in every template.
Message Group unsubscribe does not stop the Campaign
The Campaign is not assigned to the Message Group. Open the Campaign settings, scroll to Compliance, and pick the Message Group in the Message Group dropdown. Once set, the Campaign automatically excludes customers who have opted out of that Group.
Gmail one-click button not showing
Domain authentication is incomplete. Verify in Workspace Settings > Email > Domain that DKIM shows green and SPF shows aligned. Publish a DMARC record at the parent domain with at least p=none. Wait 24 hours for full DNS propagation before re-testing.
Related unsubscribe guides
- SendGrid unsubscribe link: uses
{{{unsubscribe}}}, similar API-driven model for transactional-heavy sends - Mailgun unsubscribe link: uses
%unsubscribe_url%, developer alternative with tag-scoped suppression - Postmark unsubscribe link: uses
{{{ pm:unsubscribe }}}, competing transactional platform - Klaviyo unsubscribe link: uses
{% unsubscribe %}, e-commerce alternative for behavioral marketing - Loops unsubscribe link: uses
{{ unsubscribeUrl }}, modern developer alternative for SaaS product email - Resend unsubscribe link: uses
{{{RESEND_UNSUBSCRIBE_URL}}}, JavaScript-first API alternative
For the full 222-platform reference and the compliance landscape, see the pillar guide How to add an unsubscribe link: the complete 2026 guide. For the legal side, see CAN-SPAM Act, GDPR, and global unsubscribe laws.
Customer.io unsubscribe FAQ
Can I unsubscribe a customer via the API?
Yes. Send a PUT request to /api/v1/customers/{customer_id} with {"unsubscribed": true}. The workspace-level unsubscribed flag flips immediately, and every Marketing send filter excludes the customer from that point on. For Message Group opt-outs, use the Subscription Center API to set per-group flags.
Can a customer resubscribe on their own?
Yes, via the Subscription Center. The customer visits the personalized preference URL (from any prior email) and re-opts in to any Message Group or the workspace-wide list. Alternatively, the customer can submit a signup form connected to a Journey that sets unsubscribed = false.
Does an email unsubscribe also stop SMS and push messages?
No, not by default. Customer.io tracks channel consent separately: unsubscribed covers email only. For SMS and push, use per-channel consent attributes (sms_opted_out, push_opted_out) that you set via the API or via channel-specific opt-out mechanisms (STOP keyword for SMS, native permission revocation for push).
Can I import a suppression list from another platform?
Yes. Use the API to PUT customers with {"unsubscribed": true}, or use the CSV import in People > Import with the unsubscribed column set to true. Customer.io honors the flag immediately once the import completes.
About the Author
Alaa · LinkedIn
Email infrastructure specialist with 8+ years of hands-on experience in SMTP, deliverability, and email verification. I’ve configured and troubleshot mail systems across Postfix, Exchange, and cloud relays, managed IP reputation and warmup campaigns, and built verification pipelines processing millions of addresses. My work spans DNS authentication (SPF, DKIM, DMARC, BIMI), bounce handling, blocklist monitoring, and compliance frameworks including CAN-SPAM and GDPR. I write every article on SMTPedia to give email professionals, developers, and marketers the accurate, RFC-grounded reference they need.
About SMTPedia
SMTPedia is an independent email industry reference covering SMTP, IMAP, POP3, email deliverability, marketing platforms, DNS authentication, and email verification. Every article is researched from official provider documentation, IETF RFCs, and industry best practices. Settings and configurations are verified quarterly.
We are cited as a source by ChatGPT, Microsoft Copilot, and thousands of email professionals worldwide. Learn more about our editorial process.
