Create a Custom Unsubscribe Page

OneSignal has a built-in unsubscribe page, but creating a custom one can improve and personalize your user experience.

This is particularly helpful when you want to have different landing pages specific to language, region, or any other attribute that would align with a personalized experience for your recipients.

Please be aware that your custom Unsubscribe page should not require users to log in.

Benefits Of Creating a Custom Unsubscribe Page

By customizing your unsubscribe page, you can add:

• Custom branding, such as your business logo and colors,
• Multi-Language Support, or
• Additional functionality like a customer survey.

Replace the Unsubscribe URL

When you create an email, OneSignal will add our default Unsubscribe link. However, OneSignal allows you to remove the default unsubscribe link and use a link to your custom page.

Default Unsubscribe URL

To add your Unsubscribe link to the email, you can delete the default unsubscribe link and replace it with an HTML block and the provided liquid syntax. Remember to replace the examplesite.com/unsubscribe with your unsubscribe url destination.

Select the HTML Block

When creating the unsubscribe URL you will need to use liquid syntax for each of the user properties needed to unsubscribe the email. You can go to our message personalization page to view the list of user properties.

Unsubscribe URL User Properties:

• app.id: The ID of your OneSignal application (required for the API request to unsubscribe).
• message.id: The ID of the specific notification (required for the API request to unsubscribe).
• subscription.email: The email address tied to the subscription (recommended for building your own custom page).
• user.language: The user's language preference (recommended for building your own custom page).
• subscription.unsubscribe_token: A security token for the unsubscribe action (required for the API request to unsubscribe).

Copy the URL below into your HTML block to replace the default unsubscribe link. Remember to replace the examplesite.com/unsubscribe with your unsubscribe url destination.

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

Custom Unsubscribe URL

Host Your Own Landing Page

Next, set up the custom unsubscribe page to trigger the unsubscribe action directly via a button click. In our example, JavaScript adds a click event listener to the button, making a POST request to the OneSignal API endpoint for unsubscribing.

📘

We've built a boilerplate page that you can start with. Go to the [GitHub Repository] to fork the repo and deploy it to your URL.

Exclude the Custom Unsubscribe URL from Click Tracking

To exclude the URL from Click Tracking, add the click tracking disable attribute to the anchor tag of your unsubscribe URL.

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

OneSignal - disable-tracking=true
Mailgun - disable-tracking=true
Sendgrid - clicktracking=off
Mandrill - mc:disable-tracking

Call the OneSignal API to Unsubscribe the Email

The following code on the custom unsubscribe page unsubscribes the email via the API endpoint.

This will extract the query parameters from the custom URL and construct the OneSignal API Unsubscribe with token endpoint for unsubscribing and its supporting metadata.

Query Parameters:
app_id: The ID of your OneSignal application.
notification_id: The ID of the specific notification.
token: A security token for the unsubscribe action.

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

👍

Setup Complete!

If you are having difficulty, please contact [email protected] for assistance.