OneSignal provides a default email-compliant unsubscribe experience that injects a link into your email templates so users can unsubscribe with ease and their preferences are updated in real-time. If you want full control over branding, copy, and fields (such as category opt-outs), you can replace the default link with your own custom page and use the OneSignal API to unsubscribe or update user preferences. A custom unsubscribe page allows:
  • Branded visuals (logos, colors, fonts)
  • Multi-language support
  • Preference management using Tags (opt out of specific email categories instead of all)
  • Additional components like surveys to gather feedback

​
Prerequisites

Before you build your custom page, make sure you have:
OneSignal automatically inserts [unsubscribe_url] in your email templates. This URL unsubscribes the user from all emails in OneSignal. To use your own page:
1

Remove OneSignal's default unsubscribe link

OneSignal automatically inserts [unsubscribe_url] in your email templates. This URL unsubscribes the user’s email Subscription from further emails in OneSignal. See Email Unsubscribe Links for details.To use your own page, locate and remove the default link in your template.
<a href="[unsubscribe_url]">Unsubscribe</a>
In the block editor, the default link may appear nested like:
Block editor unsubscribe link

Block editor unsubscribe link

2

Add your custom unsubscribe link

Replace the default link with your own URL. Use Liquid variables to pass OneSignal data to your page.Common parameters:
ParameterDescription
app.idOneSignal App ID
message.idID of the email notification
subscription.emailSubscriber’s email address
subscription.external_idUser’s external ID
subscription.languagePreferred language (for localization)
subscription.unsubscribe_tokenSecurity token for API verification
Example HTML block:
HTML
  <div style="text-align: center;">
    <a
      href="https://examplesite.com/unsubscribe?app_id={{app.id}}&notification_id={{message.id}}&email={{subscription.email}}&language={{subscription.language}}&token={{subscription.unsubscribe_token}}"
      data-disable-tracking="true"
      style="display: inline; text-decoration: none;"
    >
      Unsubscribe
    </a>
    <p style="display: inline;"> from our emails</p>
  </div>
Add custom unsubscribe link

Add custom unsubscribe link

​
Disable click tracking

Unsubscribe clicks should not be used for engagement metrics. Add the appropriate no-tracking attribute for your sending service:
HTML
  <a
    href="https://www.examplesite.com/unsubscribe?app_id={{app.id}}&notification_id={{message.id}}&email={{subscription.email}}&language={{subscription.language}}&token={{subscription.unsubscribe_token}}"
    data-disable-tracking="true"
  >
    Unsubscribe
  </a>
Provider-specific attributes:
ProviderAttribute
OneSignaldata-disable-tracking="true"
Mailgundisable-tracking=true
SendGridclicktracking=off
Mandrillmc:disable-tracking

​
Host your custom unsubscribe page

Deploy a web page that:
  • Reads query parameters from the unsubscribe link.
  • Displays user-friendly opt-out or preference options.
  • Sends the unsubscribe or update request to OneSignal via API.
We provide a working GitHub sample project you can fork and deploy.
Sample unsubscribe page

Sample unsubscribe page UI

​
Call the OneSignal API

Depending on your use case, you can use the following APIs to unsubscribe or update user preferences:
This API is most commonly used when you have the user’s email address and just want to subscribe or unsubscribe them from all emails.Required query parameters:
  • app_id
  • token
Authentication required
  • Call this API from your server.
You should now be equipped with everything you need to know about creating a custom unsubscribe page.