Every email by default contains a custom OneSignal unsubscribe link. When clicked, the email address will be removed from further emails sent through OneSignal unless you select the "Include sending to unsubscribed users" option in the dashboard or include_unsubscribed property in the create email notification API.

This guide explains how the OneSignal unsubscribe link works and how to customize it.

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 literal 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.

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.

📘

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, which mean when clicked, the email address does not show up in your ESP suppression list.

If you prefer to use your own unsubscribe link, simply replace the label [unsubscribe_url] in the anchor tag with your desired href. Upon being clicked, it will cause the email to be unsubscribed in OneSignal and unable to receive further emails until removed from your ESP suppression list.

🚧

Remember to sync unsubscribes back to OneSignal

If you are using a custom unsubscribe link, make sure that you update the subscription status in OneSignal to remove unsubscribed recipients from your future marketing campaigns.

How can I resubscribe emails?

If a user unsubscribes from email, they will get resubscribed if you manually click "Resubscribe to email" in the All Users tab for their record. If you use the setEmail SDK method or API Add/Edit Device calls, you will also need to remove that email from your ESP Suppression list.

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. Make sure this is either turned off or customized as you want it.