Custom Domain Proxy

Send Airship traffic through your own domain.

Airship traffic is routed using domains including,, and Customers viewing these domains in URLs will likely not associate them with your brand. The domains may also be denied by content blockers, resulting in disabled Airship features.

Substituting your own domain instead can provide a consistent brand experience for your users and it is easily identifiable when adding to a trusted domains list in a content blocker. This is accomplished by setting up a custom domain proxy, which relays requests (traffic) from your custom domain to Airship instead of directly to Airship.

Supported features

Custom domains are supported for the following Airship features:

Configuration process

Complete these steps to configure a custom domain:

  1. Configure your CDN proxy. This includes:
    • Creating your custom domain. We recommend creating a dedicated subdomain, e.g.,
    • Pointing traffic from your custom domain to Airship. You will specify a CDN origin based on the location of your Airship data center.
  2. Request proxy access. Airship will configure feature support your test projects.
  3. Test the configured features in your test projects.
  4. After a successful test, request production support. Airship will configure feature support your live/production projects.

In this document, configuration steps use an example subdomain:


You may use a configured CDN to support more than one Airship project. We recommend trying the custom domain on a test project first, and then moving to your live/production project once it has passed testing.


In order to configure a custom domain, you will need access to the following:

  • Your domain’s DNS configuration
  • A CDN proxy, and access to configure it
  • A security certificate issued for the proxy domain

You must provide your own CDN, which you will configure with your own TLS certificates, and point to an origin we provide. We have tested the following providers:


For assistance with a CDN product, please contact that product’s support team. Airship Support is unable to help you directly for those products.

CDN origin

The origin you use as a target for your CDN depends on your project’s data center:

  • North American data center:
  • EU data center:

Contact Airship Support if you are unsure which value to use.

Configuration steps

CDN proxy configuration varies depending on your CDN provider. We provide information for configuring Cloudflare and Amazon CloudFront.


We recommend using a dedicated subdomain for the CDN, as you will be passing all traffic from the domain to Airship. We do not support any setup which routes traffic for only some paths.

Configure your CDN proxy: Amazon CloudFront

Create a new CloudFront distribution with the following settings:

  • Origin: The correct origin for your data center: or
  • Viewer protocol policy: HTTPS only
  • Cache key and origin requests
    • Cache policy: CachingOptimized
    • Origin request policy: AllViewer

The remaining settings are your responsibility, but you must provide a valid certificate.

Configure your CDN proxy: Cloudflare


Cloudflare is typically configured for an entire domain (e.g.,, not just a subdomain. This is the only configuration Airship has tested, and these instructions assume you have already successfully configured Cloudflare for your domain.

Under Cloudflare’s DNS management, add a new subdomain record:

  • Type: CNAME
  • Name: Your chosen subdomain name, e.g., analytics
  • Content/Origin: The correct origin for your data center: or
  • Proxy Status: Proxied

In order for Cloudflare to work with an Airship origin, the SSL/TLS mode must be set to Full (strict).

Request proxy access for test projects

Once your proxy is configured, you can visit the custom domain in a web browser, however you will receive a generic “Error 404” message. This is expected.

Next, contact Airship Support with a request for your custom domain to be configured for proxy access. Provide this information:

  • The Airship project app keys for test projects you wish to configure to use the custom domain. You can view your app key in Settings » Project Details.
  • Your custom domain, e.g.
  • The features you wish to enable: Email preference centers and/or the Web SDK.

Airship Support will confirm when they complete configuration. You can then test the proxy in a test (non-live/production) project.

Test: Email preference center

For an email preference center, edit an existing preference center URL, replacing the default Airship domain with your custom domain:

  • Default:<app_key>/<page_id>?channel_id=<channel_id>
  • Custom:<app_key>/<page_id>?channel_id=<channel_id>

The preference center should work with no further changes. See also: Testing the appearance of an email preference center.


The custom domain proxy feature will not affect email link tracking domains. You may not use the same domain for email tracking links and a custom domain proxy.

When sending an email, you may use Unsubscribe / List unsubscribe or Double opt-in links to allow end users to update their opt in status. When using these links, Airship provides a default “success” landing page if you do not specify your own.

When using the custom domain proxy feature for these links, they will use your custom domain instead of the Airship default domains.

To test this feature, send an email to yourself that includes an Unsubscribe link, without specifying a redirect URL. After following the link in the email you receive, you should be redirected through your custom domain and arrive at a default landing page on that same domain.

HTML example
<a data-ua-unsubscribe="1">Unsubscribe</a>

Plain text example

Test: Web SDK


You should test the domain configuration on a staging deployment of your website to avoid interruptions.

The Web SDK’s initialization code must be updated to specify the new SDK source URL, as well as the API endpoints. These will have the same value. For example:

snippet.html (SAMPLE ONLY)
<script type="text/javascript">
!function(n,t,c,e,u){function r(n){try{f=n(u)}catch(n){return h=n,void i(p,n)}i(s,f)}function i(n,t){for(var c=0;c<n.length;c++)d(n[c],t);
}function o(n,t){return n&&(f?d(n,f):s.push(n)),t&&(h?d(t,h):p.push(t)),l}function a(n){return o(!1,n)}function d(t,c){
n.setTimeout(function(){t(c)},0)}var f,h,s=[],p=[],l={then:o,catch:a,_setup:r};n[e]=l;var v=t.createElement("script");
    appKey: '<app_key>',
    token: '<bearer_token>',
    vapidPublicKey: '<vapid_public_key>',

    // this configuration key is new, and needed for the custom domain
    apiUrl: ''
push-worker.js (SAMPLE ONLY)
uaSetup.worker(self, {
  defaultIcon: '<icon_url>',
  defaultTitle: 'Example Site',
  defaultActionURL: '',
  appKey: '<app_key>',
  token: '<bearer_token>',
  vapidPublicKey: '<vapid_public_key>',

  // this configuration key is new, and needed for the custom domain
  apiUrl: ''

Make the following changes:

  • Update the path to ua-sdk.min.js to the custom domain, keeping the path the same as before.
  • Add a new configuration key apiUrl, containing the custom domain and protocol, without a trailing slash.

You must update the initialization code both in the snippet in your web pages and in your push worker, e.g., push-worker.js.

Once configured, you should see any SDK traffic being sent from the browser through your custom domain without error.

Request support for live/production projects

After your configuration has been tested with a successful outcome, once again contact Airship Support. Reply to your original proxy access request with a request to have the configuration committed to your live/production projects and provide:

  • The Airship project app keys for live projects you wish to configure to use the custom domain. You can view your app key in Settings » Project Details.

This final step by Support ensures that any URLs generated by the Airship dashboard will reflect the correct settings for your custom domain.