Message delivery options

Configure delivery options for Messages, Automations, and Sequences.

After configuring the delivery timing and related settings, set up delivery options. Options are organized by channel and platform below.

General

These options are available across all or most channels.

Bypass Ban List

Bypass your Ban ListAn 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. when sending business-critical or otherwise required messages, such as privacy policy update notifications.

If you have a Ban List but do not see this option in the composer, enable it in your project settings. See Bypassing your Ban List in the Ban List documentation.

Campaign categories

Campaign categories are labels that group messages of a similar type or messaging strategy for aggregate reporting. Campaigns help you track the efficacy of both your individual messages and a messaging campaign as a whole. You can add a maximum of ten categories.

Enter a campaign category name, then select Add. Category names have a 64-character maximum.

For categories defined in message limits, its limit displays after the category. To override the limit, select the check box for Ignore limit for this message.

Tip

Campaign categories are listed in the Message Detail section of Message Reports.

Custom keys

Custom keys are additional key-value pairs in your push notification payload for use by custom code in your app or website. You can use custom keys to pass additional campaign identifiers for analytics, pass user information to the device, control the look and feel of the app, provide image links, etc.

By default, a custom key is sent to push notifications on all platforms, but you can choose platform-specific keys as well if your message is going out to more than one platform, e.g., one imageURL for iOS and another imageURL for Android.

Select a platform, then enter the key and value. Click Add Another for additional keys.

Note

For Message Center messages or templates created using the Interactive editor, a separate Custom Keys section is under Message Center Options. Configure those custom keys to set key-value pairs that apply specifically to your Message Center message. See Custom Keys for Message Center.

Expiration

The delivery expiration option discards your message if it hasn’t been delivered to a device within a specific period of time.

Select and configure an option:

Duration: Enter the number of minutes, hours, or days past your defined send time to expire the delivery.
Date & Time: Enter the date and time when delivery attempts should cease.

Expiration behavior per message type:

Message type	Expiration behavior
Push notifications and Web push notifications	If a device is online, the notification will be delivered immediately. If a device is offline, the push service for each platform preserves the notification and attempts to deliver it as soon as it comes online, up until the expiration date. The default expiration for push notifications without an expiration date is 30 days for APNs and 28 days for FCM. For Web, if no expiration is set and a device is offline, the delivery service, e.g., Google or Mozilla, preserves the notification and attempts to deliver it as soon as it comes online, for a maximum of 28 days. There is no way to remove a delivered push notification.
In-app messages	Since in-app messages are delivered via a push payload, they will not be delivered past the expiration date if the user has been offline. In addition, Airship will not display an in-app message past the expiration date.
Message Center	If you created the message using the Visual editor, its expiration is coupled with push notifications and in-app messages.

Ignore channel message limits

Enable this option to override the project-level Message LimitsLimits that cap the number of messages you can send within a specified time frame, preventing you from over-messaging your users. They are set at the project level., ensuring that your audience will receive your message even if they’ve reached the message limit. You may want to override message limits for important messages like breaking news, account alerts, or location proximity-based messages. Overriding message limits does not override Sequence Rule LimitsLimits that cap the number of messages a user can receive from a Sequence within a time frame, preventing you from over-messaging your audience, e.g., a maximum of 1 per day. Rule limits are set per Sequence. or Automation Rule LimitsLimits that cap the number of messages a user can receive from an Automation within a time frame, preventing you from over-messaging your audience, e.g., a maximum of 1 per day. Rule limits are set per Automation..

Start and End Dates

For Automations only, start and end dates define the times during which an automation can deliver messages to your audience.

Enable Start Date and/or End Date.
Set the time, time zone, and date.

Throttle delivery

In the Message composer and for A/B test variants, enable Throttle Delivery to set a delivery rate for the message. Enter the number of messages to be sent per second. The minimum rate is 100 messages per second. Throttle Delivery is only available for the following delivery options: Send Now, Schedule, and Optimize. Not supported for Message Center.

You can change the rate after sending your message and also pause/resume or cancel delivery within 48 hours of send time.

Important

Throttling must be enabled before sending the message. You cannot edit the message and enable it later.
If you combine Message Center with other App message types and pause or stop delivery within 48 hours of send time, delivery status change has no effect on Message Center delivery. Message Center messages will remain in the inbox until expiration, if set. You can also manually remove messages from the Message Center inbox.
If your use case requires a rate lower than 100 messages per second, contact Support to request a different default rate for your project.

Go to Messages, then Messages Overview.
Change the message status:
- Click Pause or Resume.
- Click Stop to cancel delivery. You cannot resume a canceled message.
Change the throttle rate:
1. Click for the message.
2. Click next to Throttle Delivery.
3. Enter a new rate and click Update.

Message Center

These options are specific to Message Center messages and templates created with the Interactive editor.

Custom keys

You can set Custom KeysAdditional key-value pairs in your push notification payload for use by custom code in your app or website. You can use custom keys to pass additional campaign identifiers for analytics, pass user information to the device, control the look and feel of the app, provide image links, etc. that apply specifically to a Message Center message.

Under Message Center Options, add a key and value. Select Add Another for additional keys.

Tip

If your Message Center is set up with Named UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual. filtering, include a custom key with named_user_id as the key and the user’s actual ID as the value.

See information about filtering by Named User in the Message Center documentation for SDK integrations.

Tip

For messages created with the Interactive editor, you can use custom keys to preview lines, which appear below the message title in the inbox.

You must perform some development work before your app can display preview lines in the inbox.

Use com.urbanairship.listing.field1 and com.urbanairship.listing.field2 as keys representing preview lines 1 and 2. In the Value field for each key, enter the text that you want to show on each line of the preview.

You can personalize preview lines using HandlebarsHandlebars is Airship’s templating language for personalization. Handlebars expressions use double curly braces wrapped around a content template, ranging from a simple variable, e.g., {{first_name}}, to complex evaluations of personalization data. to reference AttributesMetadata used for audience segmentation and personalization. They extend the concept of Tags by adding comparison operators and values to determine whether or not to target a user, helping you better evaluate your audience. or Custom EventEvents that indicate that a user performed a predefined action, such as adding an item to a shopping cart, viewing a screen, or clicking an Unsubscribe button. Custom Events can trigger automation, including Sequences and Scenes. You can code them into your app or website, or send them to Airship from an external source using the Custom Event API. Custom Events contain properties that you can use to personalize messages. properties.

Expiration

The Expiration setting for Message Center removes the message from users’ inboxes. This may be helpful if the message represents a coupon, sale, or specific event and needs to expire on a specific date and time, or after a period of time has elapsed (duration).

Under Message Center Options, select one of:

Duration: Enter the number of minutes, hours, or days past your defined send time to remove the message.
Date & Time: Select the date, time, and time zone when the message should be removed.

Note

If you created your Message Center message using the Visual editor, instead of setting an expiration, go to the Options tab and set when to remove it from the Message Center. See Creating content: Visual editor in Message Center content.

SMS

These options are specific to SMS messages.

Expiration (SMS)

The delivery expiration option discards your message if it hasn’t been delivered to a device within a specific period of time. 72 hours is the default.

Enter the number of hours, between 1 and 72.

iOS

These options are specific to iOS messages.

Background processing

The background processing option wakes the app and give it some running time to perform work, such as downloading content for future display. Data included in the push notification is available for background processing, e.g., to send URLs and then download that content. iOS only.

Badge

Update the recipient device’s app badge. A badge is the numeric display on an app icon that typically indicates the number of unread messages. The badge count can be used as an engagement strategy, notifying users about new content and driving them to open your app.

By default messages automatically increment the badge number, but you can specify an exact number, e.g., +3, +12, -3.

Select Increment by 1 or Specify. Specify requires a value in the text field.

Note

Badge functionality requires the device to be opted in to push notifications.

Group

A delivery group uses an identifier to group related notifications from your app into a single stack. Notifications bearing the same group identifier are stacked together. iOS 12 and later only.

Enter an identifier in the text field.

Note

Remember to use the same identifier for subsequent messages you wish to group.

Interruption level

Determine the degree of interruption a user experiences from a push notification. Each level has a different impact on the user’s experience, depending on their Focus settings.

The default level is Active. Select Passive, Time Sensitive, or Critical. For Critical, also specify the alert volume level, at 10% increments.

Interruption level	Overrides scheduled delivery	Breaks through Focus	Supports sounds/vibration	Overrides ring/silent switch	iOS minimum
Active (default)	No	No	Yes	No	n/a
Passive	No	No	No	No	15
Time Sensitive	Yes	Yes	Yes	No	15
Critical	Yes	Yes	Yes	Yes	12

Important

Critical alerts require:
1. A special entitlement issued by Apple.
2. Feature enablement by Airship. Contact your account manager or Support if you have the Apple entitlement and want to use critical alerts with Airship.
Critical alerts must be allowed by a user on their device.

Mutable content

The mutable content option allows a notification’s content to be changed or downloaded before delivery. This feature is automatically enabled if media is defined in the message’s Optional Features » Media settings. iOS 10 and later only.

Relevance score

The relevance score is one of multiple factors used by Apple to determine which push notifications are featured more prominently within the Notification summary. Use this setting to override the default value of 0. iOS 15 and later only.

Set a value between 1 and 10.

Sound

Play a custom sound when your audience receives a message. The sound file that you specify must be bundled with your app by your app developer.

Enter “default” to use your audience’s default system notification sound or the name of the sound file that you want to play, for example “beep.caf”.

See Configure Notification Options for more information.

Android and Fire OS

These options are specific to Android and Fire OS messages.

Collapse key

A collapse key is an optional delivery feature that acts as a grouping and replacement mechanism for messages with the same value. The Collapse Key comes into play when a device is offline (e.g. airplane mode) or in doze mode; if multiple messages are available with the same collapse key value when a device comes back online, it will display only the most recent message and discard previous that have the same value.

Enter the key in the text field.

Delivery priority

The delivery priority option sends your notification using Firebase Cloud Messaging (FCM) high priority. When not enabled, messages default to normal priority. Android only.

Note

From Google’s About FCM Messages: Delivery options: Setting the priority of a message :

High priority. FCM attempts to deliver high priority messages immediately, allowing the FCM service to wake a sleeping device when necessary and to run some limited processing (including very limited network access). High priority messages generally should result in user interaction with your app. If FCM detects a pattern in which they don’t, your messages may be de-prioritized.

Notification category

Send your message with a specific notification category instead of the default. A notification category is a grouping mechanism for messages in Android versions 8.0 and later, synonymous with Android notification channels. Users can set behaviors for each notification category within your Android app, determining the types of messages they are most interested in.

Select a notification category.

Note

You must add your app’s notification categories to your Airship project before you can select them for your messages. See: Manage Android Notification Categories.

Email

These options are specific to email messages.

URL parameters

Override project-level email URL ParametersVariables you can automatically append to all link URLs in emails. They function as tags for tracking campaign performance, both on the web and in an app. or add custom parameters for the current message only. Existing project-level parameters are listed onscreen for reference.

Under URL parameters for this message, enter a parameter name and value.
- To override an existing parameter, enter its name and enter a new value.
- To remove an existing parameter, enter its name and leave the value empty.
- To add a parameter, enter a parameter name and value.
Select Add parameter to add more.

Web

These options are specific to web push notifications.

Require interaction

Important

Support for the Require Interaction option varies by browser and OS.

Enable Require interaction to require your audience to interact with your web notification to dismiss it from the browser window.

Users may interact with a web notification in these ways:

Click the notification, which opens the message-defined URL, or the default Action URL.
Dismiss the notification.
Click the Settings icon or button on the notification.

API equivalents for delivery options

Set Campaign Categories using the Campaigns object. See Campaigns Object in the API reference.

Start and End dates are for Automation only. You can set them using the activation_time and deactivation_time properties in the Pipeline object. See Pipeline Object in the API reference.

These options can be set using Platform Overrides:

Composer option	API
Background processing^1,2	`content_available`
Badge²	`badge`
Collapse key (Fire OS)	`consolidation_key`
Collapse key (Android)	`collapse_key`
Custom keys	`extra`
Delivery priority³	`delivery_priority`
Expiration	`expiry`
Group²	`thread_id`
Interruption level²	`interruption_level`
Mutable content^1,2	`mutable_content`
Notification category³	`notification_channel`
Relevance score²	`relevance_score`
Require interaction⁴	`require_interaction`
Sound²	`sound`
URL parameters⁵	`url_parameters`

^{1. Automation only}
^{2. iOS only}
^{3. Android only}
^{4. Web only}
^{5. Email only}

Feedback

Was this page helpful?