Email Custom Unsubscribe Pages

By default, email is for commercial use and requires an unsubscribe link in both the HTML and plain text message bodies.

Default unsubscribe handling

When the user follows an unsubscribe link, Airship unsubscribes the user (i.e., opts them out of email messaging) and redirects to a confirmation web page that tells them they are unsubscribed. The Airship-hosted default confirmation web page displays the message “You have been successfully unsubscribed.” You also have the option to link to your own confirmation web page.

The user is opted out of all commercial messages if the message was marked as commercial or opted out of all email messaging if marked as transactional.

How custom unsubscribe pages work

Custom unsubscribe pages are a double opt-out flow where users are not immediately unsubscribed when they click the unsubscribe link in an email. Instead, they are redirected to your custom web page, which must contact Airship systems to unsubscribe the user from future messaging.

When using custom unsubscribe pages, you will add a link to your custom web page in the email body using specific formatting. Airship will route users to your page, appending some extra identifiers to your URL that your page can use to fetch or update user data in Airship systems.

The method of unsubscribing is fully in your control. It can be as simple as a link to confirmation page, or you can employ the flexibility of the Airship API. For example, you can have a confirmation button that unsubscribes the user from all emails, or you can allow users to choose specific topics that they want to opt out of.

Unsubscribe web page

You must self-host your unsubscribe web page. It can be a static HTML page with a link to confirm unsubscribing. This does not require a backend. The drawback of this method is that the user is unsubscribed from all emails.

With a more advanced implementation, you can make API calls from the unsubscribe page. This gives you the flexibility to do things like:

• Display a “success” message directly on the unsubscribe page, eliminating the need for a confirmation page
• Add or remove tags
• Unsubscribe from a Subscription ListAn audience list of users who are opted in to messaging about a specific topic. Users can manage their opt-in status per list using a Preference Center.

This method can be useful if you host your own email unsubscribe page rather than using an Airship Preference CenterA page where users can manage their opt-in statuses for the Subscription Lists in your project. Preference Centers are presented within your app or website or as an Airship-hosted web page..

Unsubscribe links

The unsubscribe links in your email messages must include an href attribute that points to your unsubscribe web page. The href is required when using custom unsubscribe pages. For formatting information, see: Email unsubscribe links.

When an email body contains a link to a custom unsubscribe page, you do not need to also include an unsubscribe link for opting out of all messaging.

Opt-out management

Since the unsubscribe action is bypassed by Airship, you must manage user opt-out status yourself. You can do so via the Custom Unsubscribe URL or the Airship API. Both methods are described below in Implementing custom unsubscribe pages.

Requesting enablement

You must implement and test custom unsubscribe pages for a non-production project before going live in production.

First, ask Airship support  to enable custom unsubscribe pages for a test project. Make sure to include the project name and app key in your request. You can find both in Settings in the Airship dashboard.

When custom unsubscribe pages are enabled, Airship adds extra parameters (detailed below) to your project’s unsubscribe links that are necessary for implementation.

Creating your unsubscribe web page

After a user clicks the unsubscribe link in your email, they go to your unsubscribe web page. You must add an unsubscribe action to the page, one of:

1. Link to confirmation page — The user clicks an “Unsubscribe from all” link on the page, which directs to a web page that tells them they are unsubscribed.

2. API call from your unsubscribe page’s backend — This is useful for advanced unsubscribe options, such as creating a form that allows the user to choose their subscription preferences. The user experience is up to the developer.

These options are not mutually exclusive, and you are free to implement both of them on your unsubscribe page.

Linking to a confirmation page

This unsubscribe method links from your unsubscribe page to a confirmation page. You format the link using the Custom Unsubscribe URL. The Custom Unsubscribe URL is integrated with Airship reporting and associates the unsubscribe action with the email message that brought the user to your unsubscribe page. After the link is clicked, you will be able to see the unsubscribe action in your message- and campaign-level reports.

The Custom Unsubscribe URL you use depends on your data center location:

• US: https://asemailmgmtus.com/api/channels/email/custom-unsubscribe/
• EU: https://asemailmgmteu.com/api/channels/email/custom-unsubscribe/

The URL requires the ua_unsubscribe_token query parameter in order to identify the user to unsubscribe and the originating message. You can access this query parameter on your unsubscribe page and pass it on to Airship’s Custom Unsubscribe URL without changes. You can also use the ua_redirect query parameter to specify a custom confirmation page.

For more information about the Custom Unsubscribe endpoint, see the API: Custom Unsubscribe Email Channel.

This is an example of a basic unsubscribe web page with a link that unsubscribes the user and redirects them to a confirmation page:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Custom unsubscribe page</title>
    <script>
      document.addEventListener("DOMContentLoaded", () => {
        const params = {
          ua_unsubscribe_token: new URLSearchParams(window.location.search).get("ua_unsubscribe_token"),
          ua_redirect: "https://example.com/confirmation.html"
        };
        document.getElementById("unsubscribe").href =
            "https://asemailmgmtus.com/api/channels/email/custom-unsubscribe/?" +
            new URLSearchParams(params).toString();
      });
    </script>
  </head>
  <body>
    <a id="unsubscribe">Unsubscribe</a>
  </body>
</html>

Calling the Airship API

This method is to make calls to the Airship API from your unsubscribe page’s backend.

In order to use the API to unsubscribe your email recipient, you need to be able to identify them. You can use handlebars to include the channel ID of the recipient in your unsubscribe URL by appending a query string parameter, for example: channel_id={{$channel.id}}. You can use this ID to look up the channel’s email address, update the opt-in status of the channel, set tags or subscription lists, and more. For more information on available API operations, see the Airship API Reference.

Opting a user out via the API does not associate the opt-out with a message, and the opt-out is not included in message- or campaign-level reporting.

Sending test messages and confirming opt-outs

Once your custom unsubscribe page is published, create a test email message in Airship and use your unsubscribe web page URL in the unsubscribe link. For details about formatting unsubscribe links, see: Email unsubscribe links.

To make sure that your unsubscribe page is successfully opting out users in Airship, use Contact Management to view the current status of your test channels.

Going live

Once you’ve verified that your unsubscribe link is successfully working, ask Airship support  to enable custom unsubscribe pages for your production project. Make sure to include the project name and app key in your request. You can find both in Settings in the Airship dashboard.