Create a custom unsubscribe page
Learn how to build a branded, multi-language, and personalized unsubscribe page for OneSignal emails, allowing users to manage preferences and reduce opt-outs.
OneSignal provides a default unsubscribe page for email recipients, but building a custom unsubscribe page allows you to deliver a more personalized experience—and potentially reduce unsubscribe rates.
By customizing your page, you can include:
- Branded visuals (logos, colors, fonts)
- Multi-language support
- Preference management (opt-out of specific types of emails instead of all)
- Additional components like surveys to gather feedback
Email setup
To use a custom unsubscribe page, you’ll need to replace OneSignal’s default unsubscribe link with your own.
Remove the defaul unsubscribe URL
OneSignal automatically adds an unsubscribe link to emails. To use a custom URL, locate and remove this default link from your template.
In the HTML editor, the default link appears as:
In the block editor, the default link may appear nested like:
Block editor unsubscribe link
Add the custom unsubscribe URL
Use an HTML Block (or HTML editor) to add your custom unsubscribe link. Be sure to use Liquid syntax to dynamically populate each required user property.
Recommended Unsubscribe URL Parameters:
app.id
– Your OneSignal App ID (required)message.id
– ID of the email notification (required)subscription.email
– Subscriber’s email address (useful for your custom logic)user.language
– User’s preferred language (for localization)subscription.unsubscribe_token
– Security token (required)
Example HTML block:
Add custom unsubscribe link
Host your custom unsubscribe page
Create and deploy a page that listens for a user action (e.g. clicking an “Unsubscribe” button) and sends an unsubscribe request to OneSignal via the API.
Sample implementation:
Fork and deploy from the GitHub Repository
Sample usubscribe link
Disable click tracking
To prevent tracking clicks on your unsubscribe link (recommended for privacy), add the appropriate attribute depending on your provider.
Provider-specific attributes:
- OneSignal:
data-disable-tracking="true"
- Mailgun:
disable-tracking=true
- SendGrid:
clicktracking=off
- Mandrill:
mc:disable-tracking
Call the OneSignal API to unsubscribe
Your custom page should parse the query parameters and trigger a POST request to OneSignal’s Unsubscribe with Token endpoint.
Required Query Parameters:
app_id
notification_id
token
Optional Metadata:
email
language
You should now be equipped with everything you need to know about creating a custom unsubscribe page.