Email Subscriptions can either be subscribed or unsubscribed from receiving email messages. When they are unsubscribed, they will be removed from further emails sent through OneSignal unless you specify that you want to include unsubscribed emails. This is helpful when sending marketing vs account-level or transactional emails.

To include unsubscribed email subscriptions in your email messages, select the Advanced Settings > Include sending to unsubscribed users option when Sending Email Messages from your dashboard or use the include_unsubscribed property in the create email notification API.

Email Subscriptions can be marked as unsubscribed through:

• the user clicking the unsubscribe header or link (details below).
• the Import Email Addresses CSV, setting the subscribed column to no.
• the Create user, Update user, or Update subscription API, setting enabled to false.
• the Audience > Subscriptions page, select Options > Unsubscribe from Email next to the Email Subscription.

List-unsubscribe header

Every email you send from OneSignal will include the list-unsubscribe header which allows email recipients to unsubscribe without clicking through an unsubscribe link or marking you as spam. This is to comply with 2003 CAN-SPAM Act and requirements introduced by Gmail, Yahoo, Outlook and others in 2024.

The list-unsubscribe header is not included if your email uses the option to "Include sending to unsubscribed users" discussed at the top of this page.

Also, you may not see the actual header in your emails depending on your sending behavior according to Google's and Yahoo's requirements.

If a user clicks this, their email subscription will be marked as unsubscribed in your OneSignal app.

Adding unsubscribe links in emails

Unsubscribe links are URLs included in the email that users click which navigates them to a page to unsubscribe.

We provide a default unsubscribe link in this format [unsubscribe_url] which is included in all emails. You can remove this and add your own unsubscribe link if preferred. See Create a custom unsubscribe page for details on creating your own unsubscribe links and page.

HTML

If you are creating an email directly with our HTML editor, we automatically set an unsubscribe link.

If you are using the API (email_body property), you can include the [unsubscribe_url] in the href= portion of an <a> tag like this:

<a href="[unsubscribe_url]">Unsubscribe</a>

Drag & drop editor

Within a Content Block, you can add this unsubscribe link [unsubscribe_url] in a text area by selecting Special Links > Suppression > Unsubscribe. This will drop the unsubscribe link into the text area. You may also highlight text before adding this link.

📘

Make sure unsubscribe links are accessible

It is expected that any unsubscribe link is visible to your email recipient. Use accessible, or high contrast, colors and a large enough font that is easy to read (we recommend at least 12px). If a person can't easily see unsubscribe links, they may mark your emails as spam which will affect future deliverability across all your emails.

Custom unsubscribe URL destinations

When using OneSignal's unsubscribe URL, the associated email address will be marked as unsubscribed within OneSignal and will not be included in further messages unless you select the Advanced Settings > Include sending to unsubscribed users option in the dashboard when Sending Email Messages or use the include_unsubscribed property in the create email notification API.

You can setup a custom unsubscribe URL following this guide on Create a Custom Unsubscribe Page.

FAQ

Unsubscribe links are not working in my test emails?

If your account is unverified and you are sending test emails, the unsubscribe links will not work render when sending. You will still see the word unsubscribe, but it will not be a clickable link. When your account is verified for sending, these links will automatically populate with the unsubscribe URL as expected.

How can I resubscribe emails?

If a user unsubscribes from email, they can be resubscribed in the following ways:

1. You manually click "Resubscribe to email" in the Audience > Subscriptions tab for their record.
2. SDK addEmail method
3. Update user or Update subscription API, setting enabled to true.
4. Import Email Addresses with CSV upload and subscribed to yes.

*You may also need to remove that email from your ESP Suppression list if using your own custom unsubscribe URL and not the OneSignal Email setup.

Why am I seeing 2 unsubscribe links?

If you are using Mailgun or SendGrid, you may have turned on this setting within your ESP's dashboard. It is recommended to turn this off.

Does clicking the unsubscribe link get counted as a click?

Clicking the OneSignal custom [unsubscribe_url] does not count towards click analytics but if you used a custom unsubscribe url, that will be counted as a click.