OneSignal is a multi-channel customer engagement platform combining push notifications, email, SMS, and in-app messaging under a unified subscriber model. The email unsubscribe mechanism uses the {{message.email_unsubscribe_url}} Liquid tag in email templates. OneSignal emits RFC 8058 headers automatically for authenticated domains configured through the Email Setup section. This guide covers the tag, the multi-channel opt-out model, and how to verify the setup end to end.
OneSignal unsubscribe link
| Tag syntax | {{message.email_unsubscribe_url}} |
| Placement | Auto-embedded in default email footer |
| Scope | Per-channel by default (email opt-out preserves push, SMS, in-app) |
| Config path | Settings > Email Setup > Sender Domains |
| RFC 8058 one-click | Yes, automatic for authenticated sender domains |
How to add the unsubscribe tag in OneSignal
Place the merge tag exactly as shown below in the email template. OneSignal replaces it at send time with a signed URL scoped to the recipient and campaign.
{{message.email_unsubscribe_url}}For custom HTML templates, wrap the tag in an anchor to render a proper hyperlink in the delivered email:
<a href="{{message.email_unsubscribe_url}}">Unsubscribe from this list</a>Auto-embedded in default email footer
Yes, automatic for authenticated sender domains The recipient's mailbox provider (Gmail, Yahoo) uses the List-Unsubscribe-Post header to expose the native one-click button on the message. Requires domain authentication with DKIM and DMARC.
An email unsubscribe on OneSignal does not stop push notifications or SMS by default. Consumer brands typically enable cross-channel opt-out under account settings to make one unsubscribe click apply globally across every channel. B2B senders often keep per-channel control since a user may want product alerts (push) but not marketing emails.
Testing your OneSignal unsubscribe link
- Send a test message to a controlled Gmail address you own via the OneSignal campaign preview action
- Click the footer unsubscribe link and confirm the opt-out on the landing page
- Check the subscriber or contact record: the status should be Unsubscribed within seconds
- Verify the RFC 8058 headers in Gmail: open the message, click three dots, then Show original. Look for
List-UnsubscribeandList-Unsubscribe-Post: List-Unsubscribe=One-Click
Want the full 222-platform reference?
See the pillar guide with the compliance landscape, the RFC 8058 deep dive, and the unsubscribe tag for every ESP: How to add an unsubscribe link: the complete 2026 guide →
How to add the OneSignal unsubscribe link (step by step)
OneSignal email templates include the unsubscribe link in the default footer, but custom templates or API sends require manual insertion of the Liquid tag.
- Open your email template or campaign in the OneSignal dashboard under Messages > Email.
- Add or edit a text block where the unsubscribe link should appear.
- Insert the Liquid tag
{{message.email_unsubscribe_url}}. OneSignal replaces it at send time with a signed URL unique per subscriber. - Wrap in an anchor:
<a href="{{message.email_unsubscribe_url}}">Unsubscribe</a>. - Add the physical postal address block. OneSignal reads it from Settings > Email Setup > Business Details.
- Send a test to a seed address and verify the rendered link routes to the OneSignal-hosted preference center.
Multi-channel opt-out model
OneSignal’s unified subscriber record spans push, email, SMS, and in-app channels. An email unsubscribe by default removes the address from email marketing only, preserving push and SMS subscription. Account settings can enforce cross-channel opt-out, applying an email unsubscribe globally across all channels for the subscriber. Consumer brands typically choose cross-channel to respect blanket opt-outs; B2B senders often keep per-channel control since a subscriber may want to receive product alerts but not marketing emails.
RFC 8058 one-click headers
OneSignal added RFC 8058 one-click unsubscribe automatically ahead of the Google and Yahoo 2024 requirements. The List-Unsubscribe and List-Unsubscribe-Post headers inject on every marketing send from domains authenticated under Email Setup > Sender Domains. SPF, DKIM, and DMARC records must be verified. OneSignal customer success teams help configure authentication for accounts sending significant volume, since the multi-channel focus means email deliverability is often an afterthought for teams new to the platform.
Preference center and channel granularity
The OneSignal-hosted preference center exposes checkboxes per channel and per message category when configured. A subscriber can granularly opt out of Promotional email while keeping Product Updates and remaining subscribed to push notifications. This granularity is a strong retention feature that lets brands reduce unsubscribe rates by offering topic-level control rather than blanket opt-out. Configuration is done under Settings > Preference Center where categories are defined and mapped to sends via tags.
Frequently Asked Questions
What is the OneSignal email unsubscribe tag?
The tag is {{message.email_unsubscribe_url}}. OneSignal replaces it with a signed URL unique per subscriber. Use it inside an anchor: <a href="{{message.email_unsubscribe_url}}">Unsubscribe</a>.
Does an email unsubscribe also opt out of push and SMS?
Not by default. Email unsubscribe applies only to the email channel, preserving push, SMS, and in-app subscriptions. Account settings can enforce cross-channel opt-out to make one unsubscribe click apply globally across every channel simultaneously.
Does OneSignal support one-click unsubscribe for Gmail and Yahoo?
Yes, automatically for authenticated domains. OneSignal injects List-Unsubscribe and List-Unsubscribe-Post headers on every marketing send from domains verified under Email Setup > Sender Domains, satisfying the Google and Yahoo bulk-sender requirements.
Can subscribers opt out of specific message categories?
Yes through the Preference Center. Categories are defined under Settings > Preference Center and mapped to messages via tags. Subscribers can then check or uncheck categories on the hosted preference page, opting out of promotional content while remaining subscribed to product updates.
Can I customize the OneSignal unsubscribe preference page?
Yes. The Preference Center supports branding (logo, colors, custom copy) and category configuration under Settings. Enterprise accounts can host the preference page under a custom subdomain via CNAME configuration, keeping the unsubscribe flow visually consistent with the brand website.
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.
