Create a custom preference or unsubscribe page

Learn how to replace OneSignal’s default unsubscribe link with a branded, multi-language, and personalized email preferences page, while maintaining compliance and tracking.

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:

• Familiarity with Liquid for personalization.
• OneSignal API access – Depending on your needs, you may use:
  • Update Subscription by Token – Update or unsubscribe by email address.
  • Unsubscribe Email with Token – Track unsubscribes for a specific email message ID.
  • Update User – Update profile, tags, and preferences.
  • Web & Mobile SDKs – Manage preferences in real time.

---

Remove OneSignal’s default unsubscribe link

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
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:

   Parameter	Description
   app.id	OneSignal App ID
   message.id	ID of the email notification
   subscription.email	Subscriber’s email address
   subscription.external_id	User’s external ID
   subscription.language	Preferred language (for localization)
   subscription.unsubscribe_token	Security 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

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:

Provider	Attribute
OneSignal	data-disable-tracking="true"
Mailgun	disable-tracking=true
SendGrid	clicktracking=off
Mandrill	mc: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 UI

---

Call the OneSignal API

Depending on your use case, you can use the following APIs to unsubscribe or update user preferences:

• Update Subscription by Token
• Unsubscribe Email with Token
• Update User

Update Subscription by Token

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.

---