Unsubscribe email (with token)
Unsubscribe an email address from future messages by calling this API from your custom unsubscribe page. Automatically disables the associated email subscription using a token-based approach.
Overview
Use this API to unsubscribe an email address directly from your custom unsubscribe landing page. It is ideal when building branded opt-out experiences and enables you to track which email caused the unsubscribe.
When invoked, this endpoint:
- Sets the email Subscription’s
enabled
property tofalse
- Prevents further messages from being sent to the email address unless explicitly overridden (see Overriding unsubscribes)
- Email Subscriptions can be re-subscribed using the Update Subscription API
For instructions on setting up a custom unsubscribe page, see Create a Custom Unsubscribe Page.
How to Use This API
Step 1: Set Up Your Custom Unsubscribe Page
Follow the guide to Create a Custom Unsubscribe Page. You’ll add a custom unsubscribe URL to your email templates using Liquid syntax.
Example URL in your email template:
Step 2: Extract the Parameters
When a user clicks the unsubscribe link, your custom unsubscribe page should extract the following from the URL:
app_id
: OneSignal app IDnotification_id
: The ID of the specific email message senttoken
: The email token, a secure reference to the subscription
Step 3: Call the API
When the user confirms they want to unsubscribe (e.g., clicks a button on your unsubscribe page), make a POST request to this endpoint:
Example Request (JavaScript):
No request body or authentication is required. The token acts as a secure identifier.
- This API only works for email subscriptions.
- It should only be used from a server or frontend context that you control (e.g., your custom unsubscribe page).
- Once unsubscribed, the email address will not receive future emails from your app unless resubscribed.
Path Parameters
Your OneSignal App ID in UUID v4 format. See Keys & IDs.
The "id" of the email message. Can be passed into the request from the email received by the user with liquid syntax {{message.id}}
. See Create a Custom Unsubscribe Page for setup details.
Query Parameters
The unsubscribe token that is generated via liquid syntax {{subscription.unsubscribe_token}}
when personalizing an email. See Create a Custom Unsubscribe Page for setup details.
Response
202
The response is of type object
.