Unsubscribe Links & Email Subscriptions

Add unsubscribe links to your emails and understand email subscriptions.

Email Subscriptions can either be opted-in to receiving email messages or or opted-out. When they are opted-out (aka unsubscribed) they will be removed from further emails sent through OneSignal 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.

Email Subscriptions can be marked as unsubscribed through:

  • the user clicking the unsubscribe link detailed 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.

Adding Unsubscribe Links in Emails

Customizing the unsubscribe link can be done using HTML or the Drag & Drop Editor. The default unsubscribe link uses this liquid syntax [unsubscribe_url]. The unsubscribe link can be added in the following ways:

HTML

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

1309

Image showing editor with default HTML and Unsubscribe Link

If you are using the API (email_body property), you can put [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.

1114

Image shows unsubscribe link selection

📘

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

The OneSignal unsubscribe link is not tied to your Email Service Provider. The email will not show in your ESP suppression list / Unsubscribe list.

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.