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.

1

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:

<a href="[unsubscribe_url]">Unsubscribe</a>

In the block editor, the default link may appear nested like:

Block editor unsubscribe link

2

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:

<div style="text-align: center;">
  <a
    href="https://examplesite.com/unsubscribe?app_id={{app.id}}&notification_id={{message.id}}&email={{subscription.email}}&language={{user.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

​
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.

<a
  href="https://www.examplesite.com/unsubscribe?app_id={{app.id}}&notification_id={{message.id}}&email={{subscription.email}}&language={{user.language}}&token={{subscription.unsubscribe_token}}"
  data-disable-tracking="true"
>
  Unsubscribe
</a>

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
const unsubscribeURL = (href) => {
  const unsubscribeURL = new URL(href)
  const appID = unsubscribeURL.searchParams.get("app_id")
  const notificationID = unsubscribeURL.searchParams.get("notification_id")
  const unsubscribeToken = unsubscribeURL.searchParams.get("token")
  const language = unsubscribeURL.searchParams.get("language")
  const email = unsubscribeURL.searchParams.get("email")
  return {
    unsubscribeURL: `https://api.onesignal.com/apps/${appID}/notifications/${notificationID}/unsubscribe?token=${unsubscribeToken}`,
    meta: { language, email },
  }
}

You should now be equipped with everything you need to know about creating a custom unsubscribe page.