Ban Lists

A Ban List is an externally maintained record of users that should not be included in Airship message audiences. Before sending a message, Airship validates the audience members with the Ban List. Any matching recipients are dropped from the audience before sending the message. AXP


You are responsible for maintaining any Ban List, including accuracy and timing of its updates. Please verify with your legal and compliance teams:

  • that any Ban List provided to the Airship Service is compliant with local regulations regarding which End Users should be added to a Ban List;
  • scenarios when communications are appropriate to audience members on a Ban List;
  • timing of required updates to the Ban List under applicable industry and local regulatory standards.

Airship does not monitor and is not otherwise responsible for the Ban List content and modifications that have to be made to the Ban List.

About Ban Lists

A Ban List has these components:

  • Your record of banned users — These may be users compiled from “Do not contact me” responses or any other reason to omit them from messaging.

    You decide the record’s format and storage location outside of Airship. Each user must be associated with a Channel IDAn Airship-specific unique identifier used to address a channel instance, e.g., a smartphone, web browser, email address. or Named UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual.. We recommend Named User since it maps to all Channel IDs associated with a user. Named User must already be implemented for your project.

  • An external webhook — This is an HTTP callback Airship uses to access your record of banned users. You configure the callback and provide Airship with a request URL formatted for querying your data.

    The webhook must provide a specific response when a match is found. You can format the request URL to use Channel ID, Named User, or both. You can also format it to pass variables. You set a default value for the variable when setting up the URL and can override the values for individual messages.

  • A Ban List configuration in your Airship project — You will enter your request URL and confirm Airship is authorized to use it for its intended purpose.

Once the above items are in place, this is the Ban List workflow:

  1. Airship makes an API call to your webhook for every Channel ID in a message audience.
  2. Your webhook checks your record of banned users for matches for each Channel ID. If a match is found, the webhook sends a response telling Airship to drop the matched user.
  3. Airship drops the send for each match.

Only necessary data to prevent users from receiving messages is captured during time of send and is not stored beyond what is necessary for that purpose. Airship does not access or store administrative configurations related to your Ban List.

You can set up one Ban List per project. Ban Lists are not supported for In-App AutomationMessages that are cached on users’ devices and displayed when your users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times., ScenesMulti-screen experiences that are cached on users’ devices and displayed when your users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times. Scenes can include survey questions or be presented as a story., or SurveysQuestion-and-answer experiences used to collect and aggregate feedback or generate a net promoter score. They are cached on users’ devices and displayed when your users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times..


Ban Lists do not work with email addresses or MSISDNsThe mobile phone number of an individual in your Airship audience. Each MSISDN represents an individual mobile device. in Inline ListsAn ad-hoc, CSV-formatted list of email, SMS, app, web, or open channel addresses that you want to register and send a message to. Unlike static lists or segments, you upload this list when creating your message. Airship registers new addresses in the list as channels when you send the message. since Ban Lists must match against existing user data.


Using an external Ban List can mean a lot of API calls in a short period of time. When configuring your Ban List in Airship, you can set a frequency rate for your requests. The minimum rate is 100 requests per second.


You can bypass your Ban List when sending business-critical or otherwise required messages, such as privacy policy update notifications. Bypass is supported for both the API and dashboard.


Each dropped recipient counts toward the Not Sent count in a message report. A SEND_ABORTED event occurs when a recipient is dropped from our system before delivery is attempted, with reason value FEED_BANNED_RESPONSE. For additional information and a sample event, see the Send Aborted event in the Real-Time Data Streaming API reference.

Webhook requirements

When you send a message, Airship will make an API call to your webhook with a URL parameter containing a Named User ID and/or Channel ID. Your server must return a header indicating Airship should drop a matched user from the send.

Set up your webhook to return an X-UA-Segmentation-Action header to specify an action to be taken by Airship. The only value supported is drop, to drop the recipient from the send. This header is valid only for 200- and 400-level status codes and is ignored if provided for 300- or 500-level status codes. It is also ignored if the value is not recognized or the header is missing. Any other response will allow the message to go through.

Formatting your request URL

Your request URL is used to retrieve the user data. You will enter it in the dashboard when configuring your Ban List. It comprises your domain, protocol, path, and any variables you want to include.


  • The URL must contain a parameter for the identifiers in your Ban List, one of:
    • ?channel_id={{$}}
    • ?named_user={{ua_named_user_id}}
    • ?named_user={{ua_named_user_id}}&channel_id={{$}}
  • Use double square brackets ([[var]]) for send time, or message-level, variables.

This example request URL has a send time variable category and the parameter for Named User:[[category]]?named_user={{ua_named_user_id}}.

Configuring your Ban List

Owners and Administrators can configure a project’s Ban List.

In the Airship dashboard:

  1. Go to Settings.
  2. Under Project Configuration, select Manage for Dashboard Settings.
  3. Select Configure for Ban List.
  4. Configure the list settings:
    Request URLThe URL to retrieve the user data from. See Formatting your request URL.Enter the request URL.
    Default value for <variable>The default value for each send time variable included in the request URL.Enter a default value.
    Confirm request URL domainThe domain in the request URL. For example, Do not include the protocol or variables.Enter the domain.
    HeadersOptional. HTTP request headers that may be required to successfully communicate with the external webhook. For example, authorization headers. Header information is not a part of the request URL.Select Add header, and then enter a key and value. Repeat for additional headers.
    Throttle requestsOptional. Allows setting a frequency rate for your requests. See Throttling. The minimum rate is 100 requests per second.Enter the number of API requests to allow per second.
  5. Select Confirm access rights for request URL.
  6. Select Done.

Now you can toggle the Ban List setting to enable it for your project.

Overriding variable default values

If your project has a Ban List enabled and the request URL includes send time variables, you can override their default values for individual messages.

When sending messages using the API, use the ban_list_parameters push option to override values for variables.

In the dashboard, you can override the default values:

  • In the Delivery step of the Message, A/B Test, Automation composers
  • In the Delivery step when composing each message in a Sequence

In the Delivery step, go to Ban List. Each variable is listed under the heading Default value for <variable>. Enter a new value for any variable.

Bypassing your Ban List

Using the API, include the bypass_ban_list_processing push option and set it to true.

To use this feature in the dashboard, your project Owner or Administrator must first enable the option:

  1. Go to Settings.
  2. Under Project Configuration, select Manage for Dashboard Settings.
  3. Enable Bypass Ban List.

    Disable this setting when no longer needed to avoid accidentally sending messages to banned users.

Then, when creating messages, enable Bypass Ban List in the Delivery step. Location per ComposerA tool for creating messages using the dashboard. Composers are defined by what you can include and control: message types, delivery, and automation.:

Message, A/B Test, and AutomationDelivery
SequenceA series of messages that is initiated by a trigger. Airship sends messages in the series based on your timing settings, and you can also set conditions that determine its audience and continuation. Sequences can be connected to each other and to other messaging components to create continuous user experiences in a Journey.Delivery for each message in the Sequence

Success, Retry, and Error Conditions

Airship considers any 2xx response from a feed to be a success and will continue a message using the feed response. Airship considers any 3xx and 5xx codes (except 502/503) to be error conditions.

HTTP statusResultBehavior
2xxSuccessAirship uses the feed response, even if empty.
3xxErrorError behavior determined by user.
5xxErrorError behavior determined by user.
timeout (60s)RetryUp to 4 retries, 60s between attempts.
502/503RetryUp to 4 retries, 60s between attempts.