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. When used, the associated email address will be marked as unsubscribed within OneSignal and we will no longer send to this address until they resubscribe. The email will not show in your ESP suppression list / Unsubscribe list.

You can use a custom unsubscribe link – simply replace [unsubscribe_url] in the anchor tag with your desired href.

• If you use an unsubscribe link provided by your ESP, we should get a webhook event and unsubscribe the email address.
• If you use your own custom link (e.g TypeForm) you would need to mark the email address as unsubscribed within OneSignal and possibly your ESP if you choose to do so. Keep in mind, if the user does resubscribe, you will need to also resubscribe them to OneSignal and remove them from your ESP suppression list accordingly.

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 > Users tab for their record.
2. SDK setEmail method
3. API Edit Device call.

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