This repository is a comprehensive guide for implementing custom email unsubscribe features using OneSignal's API. Aimed at developers, it demonstrates how you can provide users with a seamless and secure unsubscribe process. The example is designed to be easily integrated into your existing projects and comes with detailed explanations and code snippets to get you up and running quickly.
View Previews
- Clone this repo,
git clone https://github.com/OneSignalDevelopers/custom-email-unsubscribe-page-sample - Navigate to the repo,
cd ~/path-of-repo - Start a simple server,
npx http-server . - Send email (see this guide to learn how setup email with custom unsubscribe link)
- Click the unsubscribe link
The unsubscribe button will unsubscribe you when clicked.
This demo demonstrates implementing OneSignal's Custom Email Unsubscribe Page feature using a button and OneSignal's API. Below are the key components:
The HTML layout consists of a single "Unsubscribe" button. Unlike the previous example that used a form, this example triggers the unsubscribe action directly via a button click.
<body>
<h1>Custom Unsubscribe Button</h1>
<button type="button">
Unsubscribe
</button>
</body>The JavaScript code adds a click event listener to the button to trigger the unsubscribe request.
const onClick = (event) => {
const { unsubscribeURL } = unsubscribeURL(window.location.href)
fetch(unsubscribeURL, {
method: "POST",
}).then((res) => {
// ... request handling
})
}
document.addEventListener("DOMContentLoaded", () => {
const buttonEl = document.getElementById("unsubscribe_button");
buttonEl.addEventListener("click", onClick);
});- Upon page load, the
DOMContentLoadedevent is triggered. - The JavaScript function
unsubscribeURLconstructs the OneSignal API endpoint to unsubscribe the user from email. - A click event listener is added to the button. When clicked, it makes a POST request to the API endpoint.
By incorporating this code, you can create a custom unsubscribe feature directly interacting with OneSignal's API through a button click.
The URL structure for the API endpoint is of the form
<Base URL>?app_id=<App ID>¬ification_id=<Notification ID>&email=<User Email>&language=<User Language>&token=<JWT>
- Base URL:
https://examplesite.com/unsubscribe- This is the location of your custom unsubscribe page. - 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.email: The email address tied to the subscriptionlanguage: The user's language preference
The JavaScript code constructs the URL OneSignal needs to unsubscribe the user from the email.
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 },
}
}- Email Link: The user receives an email containing the unsubscribe link.
- Click Action: When the user clicks the link, they are directed to your custom unsubscribe page, and the query parameters
app_id,notification_id, andtokenare passed along. - Page Load: Upon loading, the
DOMContentLoadedevent triggers the JavaScript code. - URL Parsing: The function
unsubscribeURLextracts the query parameters to construct the OneSignal API endpoint for unsubscribing and its supporting metadata. - Button Configuration: A click event listener is added to the button to make a POST request to this API endpoint.
For additional resources, please join the OneSignal Developer Community.
Please reach out to us or learn more about OneSignal through the channels below.
- Follow us on Twitter to never miss any updates from the OneSignal team, ecosystem & community
- Join us on Discord to be a part of the OneSignal Developers community, showcase your work and connect with other OneSignal developers
- Read the OneSignal Blog for the latest announcements, tutorials, in-depth articles & more.
- Subscribe to us on YouTube for walkthroughs, courses, talks, workshops & more.
- Follow us on Twitch for live streams, office hours, support & more.
Show your support and give a ⭐️ if this project helped you :-)