OneSignal has a built-in unsubscribe page when users click the unsubscribe link in emails. However, creating your own can improve your user experience and reduce unsubscribes. By customizing your unsubscribe page, you can add:

• Custom branding, such as your business logo and colors.
• Multi-language support.
• Allow users to opt-out of specific types of emails and not all emails.
• Additional functionality like a customer survey.

Email setup

When sending emails, you will need to update the default unsubscribe URL and add your own.

Remove the default unsubscribe URL

When you create an email, we will add our default Unsubscribe link automatically. You can remove this default unsubscribe link and use a link to your custom page.

Search the template for the "Unsubscribe" link and delete it.

If you are using the HTML editor, the link will look like: <a href="[unsubscribe_url]">Unsubscribe</a>

Add the custom unsubscribe URL

Select the HTML Block or if using an HTML template, use the provided HTML below.

When creating the unsubscribe URL you will need to use liquid syntax for each of the user properties needed to unsubscribe the email. See Message Personalization for a list of all available properties.

Unsubscribe URL 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 if your unsubscribe page supports different languages).
• 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 actual 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 example

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.