Managing how users unsubscribe from your emails is critical to complying with email standards (like CAN-SPAM), ensuring strong deliverability with providers like Gmail and Yahoo, and building trust with your audience. OneSignal supports both visible unsubscribe links and List-Unsubscribe headers, ensuring your emails are fully compliant while giving you control over when and how users can opt out.

​
Subscription states and suppression logic

Email Subscriptions are either:
  • Subscribed – eligible to receive email messages.
  • Unsubscribed – excluded from most email sends unless explicitly overridden.
To include unsubscribed Subscriptions in your email (e.g., for transactional messages):
  • In the dashboard: Enable Advanced Settings > Include sending to unsubscribed users when sending an email.
  • In the API: Use the include_unsubscribed property in the create email notification API.

Enable sending to unsubscribed users

​
How users get unsubscribed

Email subscription status is updated via:
  • List-Unsubscribe header: A hidden email header used by inbox providers to display native “Unsubscribe” buttons (e.g., Gmail, Yahoo).
  • Unsubscribe link: A visible clickable URL placed in your email content using the [unsubscribe_url] token.

​
List-Unsubscribe header behavior

OneSignal includes a List-Unsubscribe header in all emails except when you enable “Include sending to unsubscribed users.” This helps:
The List-Unsubscribe header is not included if you enable “Include sending to unsubscribed users.”Some inbox providers may hide this header from display unless you meet certain sending volume thresholds. See Gmail’s and Yahoo’s requirements.
If a user clicks this, their email Subscription will be marked as unsubscribed in your OneSignal app. OneSignal provides the [unsubscribe_url] token, which inserts a visible unsubscribe link into your email content. You can also create a branded experience with your own unsubscribe page. See Create a custom unsubscribe page.

​
HTML editor

If using our HTML editor, the default template includes an unsubscribe link automatically:

HTML editor with default unsubscribe link

To add it manually (e.g. via API with email_body):
HTML
<a href="[unsubscribe_url]">Unsubscribe</a>

​
Drag & drop editor

In a text block:
  1. Click Special Links > Suppression > Unsubscribe
  2. The [unsubscribe_url] placeholder is inserted
  3. You can highlight text before inserting to turn it into a link

Unsubscribe link in Drag & Drop editor

Always make unsubscribe links highly visible with readable font sizes (at least 12px) and strong contrast. Hidden or hard-to-find links can lead users to mark your messages as spam, harming future deliverability.
You may replace [unsubscribe_url] with your own unsubscribe landing page. To do this:
If using a custom link, OneSignal will not automatically mark the user as unsubscribed. You must handle that through the API or page behavior.

​
FAQ

If your OneSignal email sending domain is not yet verified, unsubscribe links in test emails won’t be functional. You’ll see placeholder text, but no real link. Once your domain is verified, unsubscribe links will render and function properly.

​
How do I resubscribe an email address?

Users can be resubscribed in three ways:
  1. Dashboard: Go to Audience > Subscriptions > Options > Resubscribe to Email
  2. API: Set enabled: true in the Create User or Update subscription APIs
  3. CSV Import: Set subscribed = yes when importing email addresses
If you use a third-party email provider (ESP), check their suppression list and remove the address there too.
If you’re using ESPs like Mailgun or SendGrid, they may insert their own unsubscribe link. You can disable this in your ESP’s settings to avoid duplication.

​
Do unsubscribe clicks count toward analytics?

  • Clicking the OneSignal custom [unsubscribe_url] does not count towards click analytics.
  • Clicking a custom unsubscribe URL will be counted as a click. See URLs, Links, and Deep Links for more details.