Thanks to visit codestin.com
Credit goes to documentation.onesignal.com

Skip to main content

​
Overview

OneSignal provides a default email-compliant unsubscribe experience that injects a link into your email templates so users can unsubscribe with ease and their subscription statuses 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. This guide explains how to add your own custom unsubscribe page to emails (removing the default OneSignal link) and which of our APIs to use to unsubscribe the user’s email Subscription. If you want to add more functionality to your custom unsubscribe page (like opt out of specific email categories instead of all), this is detailed in our Preference Center tutorial.
OneSignal automatically inserts a special link in the format [unsubscribe_url] to your email templates. This URL unsubscribes the user from all emails in OneSignal. See Email Unsubscribe Links for details. To use your own page, locate and remove the default link in your template.
  • Drag-and-Drop Editor
  • HTML Editor
In the drag-and-drop editor, the default link may appear nested like:
Drag-and-Drop editor unsubscribe link

Drag-and-Drop editor unsubscribe link

Now that you have removed our special link, you can replace it with your own URL. Many times, these links require some additional data to be passed to your page. Use Liquid variables to pass OneSignal data to your page. Common parameters:
ParameterDescription
subscription.emailSubscriber’s email address
subscription.external_idUser’s external ID
app.idOneSignal App ID
message.idID of the email notification
subscription.languagePreferred language (for localization)
subscription.unsubscribe_tokenSecurity token for API verification
Example URL: 
https://examplesite.com/unsubscribe?app_id={{app.id}}&notification_id={{message.id}}&email={{subscription.email}}&language={{subscription.language}}&token={{subscription.unsubscribe_token}}
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

Add custom unsubscribe link

​
Disable click tracking

Unsubscribe clicks are generally not used for engagement metrics. If you want to disable link tracking, you can add the data-disable-tracking="true" attribute to your link like this:
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:
ProviderAttribute
OneSignaldata-disable-tracking="true"
Mailgundisable-tracking=true
SendGridclicktracking=off
Mandrillmc:disable-tracking

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

Sample unsubscribe page UI

​
Calling 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
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.
⌘I