POST
/
apps
/
{app_id}
/
notifications
/
{notification_id}
/
unsubscribe?token=
{token}
Unsubscribe email (with token)
curl --request POST \
  --url 'https://api.onesignal.com/apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}'
"{\n  \"success\": \"true\"\n}"

​
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 to false
  • 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:

https://yourdomain.com/unsubscribe?app_id={{ app_id }}&notification_id={{ notification_id }}&token={{ token }}

​
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 ID
  • notification_id: The ID of the specific email message sent
  • token: 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:

POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}

Example Request (JavaScript):

fetch("https://api.onesignal.com/apps/your-app-id/notifications/your-notification-id/unsubscribe?token=abc123xyz", {
  method: "POST"
});

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

​
app_id
string
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

​
notification_id
string
required

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

​
token
string

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
application/json

202

The response is of type object.