# Set up and integrate Email, SMS/MMS/RCS, and Open Channels

Configure and manage messaging channels that integrate directly via API without requiring an SDK.

<!-- SECTION: Email, PATH: https://www.airship.com/docs/developer/api-integrations/email/ -->

## Email

Set up and manage email registration, compliance, and delivery for your Airship project.

<!-- PAGE: Getting Started, PATH: https://www.airship.com/docs/developer/api-integrations/email/getting-started/ -->

# Getting Started

> Email is a native Airship messaging channel, supporting both commercial and transactional messages.## Overview

Getting started with Airship email is a three-step process. This document will guide you through the following
steps:

* Provision your account for email.
* Register users.
* Optionally create content templates and send email.

> **Tip:** If you use an AI coding assistant, you can connect it to Airship with Skills and an MCP server. See [Airship AI Tools](https://www.airship.com/docs/developer/ai-tools/ai-tools/).

## Provision Account

To get started using Airship email, contact your account manager or [Airship Support](https://support.airship.com) to provision your project for email notifications.

## Register Users

Registering an email address returns a [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id). You will typically reference your audience of email addresses by Channel IDs or other abstractions within Airship rather than using the email address directly.

There are multiple ways to register users:

* **Email address submission in a Scene** — A user can submit their address using the [Email element](https://www.airship.com/docs/guides/messaging/editors/native/elements/#email) in a [Scene](https://www.airship.com/docs/reference/glossary/#scene). The address is associated with the [Contact](https://www.airship.com/docs/reference/glossary/#contact) viewing the Scene, and the channel is automatically opted in to both transactional and commercial messaging.
* **Opt-in form** — A user can sign up for email messages through an [opt-in form](https://www.airship.com/docs/guides/messaging/features/opt-in-forms/) you can add to your website.
* **Email channel registration API** — You can generate an email channel for an individual user by using the [Email Channel Registration API](https://www.airship.com/docs/developer/rest-api/ua/operations/email/#registeremailchannel).
* **Simultaneously send a message and register new user** — See [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send).
* **SDK** — Register an email channel through the [Android](https://www.airship.com/docs/developer/sdk-integration/android/audience/contacts/#email-channel-association) and [Apple](https://www.airship.com/docs/developer/sdk-integration/apple/audience/contacts/#email-channel-association) SDKs.
* **CSV Upload** — You can upload email addresses in a CSV file to set [Tags](https://www.airship.com/docs/reference/glossary/#tag) or [Attributes](https://www.airship.com/docs/reference/glossary/#attributes). Airship registers new channels for addresses that are new to your project. See: 
    * [Setting attributes using a CSV file](https://www.airship.com/docs/guides/audience/attributes/setting/#csv-file)
    * [Setting tags using a CSV file](https://www.airship.com/docs/guides/audience/tags/#file-upload)


**Example Request — Registration**

```http
POST /api/channels/email HTTP/1.1
Authorization: Basic <master secret authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "channel": {
      "type": "email",
      "commercial_opted_in": "2018-07-30T08:35:00",
      "address": "name@example.com",
      "timezone": "America/Los_Angeles",
      "locale_country": "US",
      "locale_language": "en"
   }
}
```


**Example Response — Registration**


```http
HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "channel_id": "adb2f0ca-e2a4-4c16-bda5-37736EXAMPLE"
}
```


We recommended also associating the email channel with a [Named User](https://www.airship.com/docs/reference/glossary/#named_user):

**Example Request — User Association**


```http
POST /api/named_users/associate HTTP/1.1
Authorization: Basic <master secret authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "channel_id": "adb2f0ca-e2a4-4c16-bda5-37736EXAMPLE",
   "device_type": "email",
   "named_user_id": "example-named-user-id"
}
```


### Opt-in/out Values

You can account for the types of emails each address has subscribed to, or unsubscribed from, for both commercial and transactional messages. We represent subscription, as well as tracking permissions, using `opted_in` and `opted_out` values on email.

* `commercial_opted_in`: The date-time that a user subscribed to commercial emails.
* `commercial_opted_out`: The date-time that a user unsubscribed from commercial emails.
* `transactional_opted_in`: The date-time that a user subscribed to transactional
emails from you. Users do not have to subscribe to transactional emails; you only
need to use this key if a user opted into transactional emails after previously
opting out.
* `transactional_opted_out`: The date-time that a user unsubscribed from transactional
emails.
* `open_tracking_opted_in`: The date-time that a user enabled open tracking of emails. New channels are opted in by default.
* `open_tracking_opted_out`: The date-time that a user disabled open tracking of emails. 
* `click_tracking_opted_in`: The date-time that a user enabled click tracking in emails. New channels are opted in by default.
* `click_tracking_opted_out`: The date-time that a user disabled click tracking in emails.

> **Note:** For [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send) endpoints, you can provide one of `ua_commercial_opted_in`
> or `ua_transactional_opted_in`, corresponding to the type of email you want to send.


These keys are all optional. However, an email channel with no `opted_in` or `opted_out` values can only receive transactional emails. Users must have a `commercial_opted_in` value to receive commercial
emails; users do not need to subscribe to receive transactional emails (though they can explicitly unsubscribe).

If a user has an `opted_out` of a particular email type (or the user never opted into commercial emails), and the user is a part of your audience for a message of that type, the email designated for the opted-out user is dropped at delivery time.

If a channel has both `opted_in` and `opted_out` values for a particular email type, Airship respects the most recent value. So, if a user opted into commercial emails after previously opting out, that user can receive commercial emails from you even though that user's channel possesses both `commercial_opted_in` and `commercial_opted_out` values; if the opt-in date is prior to the opt-out date, the user will not
receive commercial emails from you.

### Double Opt-In

*Double opt-in* is a process where users who sign up for messaging must confirm opting in before they can receive messages. You can use double opt-in to ensure your email subscribers intended to sign up and have entered the correct email address.

The general process:

1. A new user signs up for email messaging. — *You can add an* [Opt-in Form](https://www.airship.com/docs/reference/glossary/#opt_in_form) *to your website.*
1. Airship sends a confirmation email to the address used to sign up. — *You set up the email in the dashboard or using the API.*
1. The user follows the confirmation link in the email, and Airship updates their channel as opted in.
1. The user can now receive commercial emails.

---

To set up the confirmation email:

* From the dashboard, [create an Automation](https://www.airship.com/docs/guides/messaging/messages/sequences/create-automation/) or [Sequence](https://www.airship.com/docs/guides/messaging/messages/sequences/create/create/) using the [[Double Opt-In Trigger](https://www.airship.com/docs/reference/glossary/#double_opt_in_event_trigger)](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#double-opt-in).
* For the API, create an Automation use the `/api/pipelines` endpoint with the `double_opt_in` event. Sequences cannot be created using the API.

You can filter the trigger by using properties attached to the opt-in event, and you can reference the properties using [Handlebars](https://www.airship.com/docs/reference/glossary/#handlebars) to personalize the message content. If you choose to use properties in these ways, **your developer must add the properties when setting up email channel registration**.

You must provide an opt-in link in the body of the message, and users must follow the link to confirm opting in. For link formatting, see: [Email double opt-in links](https://www.airship.com/docs/guides/messaging/messages/content/email/email-double-opt-in-links/).

Additionally, you must send the message as *Transactional* and should also bypass a user's opt-in status. (Though the confirmation email is transactional, its purpose is to subscribe to commercial messaging.)

* In the dashboard, you set these options in *Sender Information* section when adding the message content. See [Creating content](https://www.airship.com/docs/guides/messaging/messages/content/email/email/#creating-content) in *Email content*.
* For the API, set `"message_type": "transactional"` and `"bypass_opt_in_level": "true"`. See: [Email Overrides](https://www.airship.com/docs/developer/rest-api/ua/schemas/platform-overrides/#emailoverrideobject).

---

Next, set [`"opt_in_mode": "double"`](https://www.airship.com/docs/developer/rest-api/ua/operations/email/#registeremailchannel) when registering new email channels. When a new channel is registered using this `"double"` parameter, it creates a `double_opt_in` event. This event is used to trigger sending the confirmation email.

You can use the `properties` object to add properties for the event that be can used to filter the Automation or Sequence trigger and for personalizing the message content using [Handlebars](https://www.airship.com/docs/reference/glossary/#handlebars).

### Updating Registration

You can update the `opted_in` and `opted_out` values using a PUT call for the
channel.

> **Important:** The `address` you provide in this request must be the one that is associated with the channel you
> are updating. You may not update the user's email address with this endpoint.


**Example Request — Update opt-in date**


```http
PUT /api/channels/email/adb2f0ca-e2a4-4c16-bda5-37736EXAMPLE HTTP/1.1
Authorization: Basic <master secret authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

 {
     "channel" : {
        "type": "email",
        "address": "name@example.com",
        "commercial_opted_in": "2021-11-01T12:00:25"
     }
  }
```


To comply with storage requirements for personally identifiable information,  email addresses are not returned when you look
up a channel. If you need to find the channel associated with an address, you can
    look up the channel by email address using the [`/api/channels/email/{email_address}`
    endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/email/#getemailchannel).

**Example Request — Lookup channel by email address**


```http
GET /api/channels/email/name%40example.com HTTP/1.1
Authorization: Basic <master secret authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json
```


### Updating an Email Address

You may register a new email address and remove an existing address using the
[Replace Email Channel endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/email/#replaceemailchannel).

Performing this operation will:

* Register a new email channel
* Associate the new email channel with the same user as the source channel
* Uninstall the source channel

In the following example, `c59e2660-8a5f-4b11-9439-c4e0fEXAMPLE` is Channel ID of the channel you're replacing:

**Example Request — Replace**


```http
POST /api/channels/email/replace/c59e2660-8a5f-4b11-9439-c4e0fEXAMPLE HTTP/1.1
Authorization: Basic <master secret authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "channel": {
      "type": "email",
      "commercial_opted_in": "2022-04-07T18:51:00",
      "address": "new-name@example.com",
      "timezone": "America/Los_Angeles",
      "locale_country": "US",
      "locale_language": "en"
   }
}
```


**Example Response — Replace**


```http
HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "channel_id": "a7808f6b-5cd8-458b-88d0-96eceEXAMPLE"
}
```


> **Important:** When replacing an email address for a user, a new email channel is created. This
> channel inherits the properties of the contact to which it's associated, but
> does not inherit any properties from the source channel.
> 
> We recommend associating email addresses with a [Named User](https://www.airship.com/docs/reference/glossary/#named_user), and performing actions such as setting tags or attributes, or
> attributing events, at the user level.


### Unsubscribe

When a user unsubscribes to email of a particular type, you should set the `commercial_opted_out`,
`transactional_opted_out`, or both to the date-time when the user unsubscribed.

While the `opted_in` values are still present on the unsubscribed email channel, Airship will respect the newer `opted_out` values; the channel will not receive emails corresponding to the `opted_out` type, even if they are members of the audience for an email.

As a more drastic measure, you can also [uninstall email channels entirely](https://www.airship.com/docs/developer/rest-api/ua/operations/email/#uninstallemailchannel). You should use this option with caution. If the uninstalled email address opts-in again, it will generate a new `channel_id`. You cannot reassociate the new `channel_id` with any opt-in information, tags, Named Users, insight reports, or other information from the uninstalled email channel.

### Suppression

When Airship receives feedback for a delivery address, such as a hard bounce or a spam complaint, their email channel's `suppression_state` value is automatically updated according the type of complaint received. Possible values: `spam_complaint`, `commercial_spam_complaint`, `bounce`, or `imported`. You can also set a value when registering users.

For more information, including about about removing suppression, see: [Email Bounce Handling and Suppression](https://www.airship.com/docs/developer/api-integrations/email/bounce-handling/).

## Send Email

Now that you have registered users, they are able to receive email from Airship. Email messages can be sent via the Airship dashboard or API.

* **Dashboard** — See [Email content](https://www.airship.com/docs/guides/messaging/messages/content/email/email/) to learn how to configure the email content in a [message](https://www.airship.com/docs/guides/messaging/messages/create/), [A/B test](https://www.airship.com/docs/guides/experimentation/a-b-tests/messages/), [Automation](https://www.airship.com/docs/guides/messaging/messages/sequences/create-automation/), or [Sequence](https://www.airship.com/docs/reference/glossary/#sequence).


* **API** — Use the [Push API](https://www.airship.com/docs/developer/rest-api/ua/operations/push/); you must set [email platform overrides](https://www.airship.com/docs/developer/rest-api/ua/schemas/platform-overrides/#emailoverrideobject) such as `sender_name`, `sender_address`, etc.

You can also create templates for your email notifications. You [create templates in the dashboard](https://www.airship.com/docs/guides/personalization/content/templates/), then send using the dashboard or API. In the API, send a template using the [`/create-and-send`](https://www.airship.com/docs/developer/rest-api/ua/operations/bulk-sending/#createandsend) or [`/pipelines`](https://www.airship.com/docs/developer/rest-api/ua/operations/automation/) APIs.

> **Important:** * You can provide your own HTML email without using a template. However, you cannot personalize emails using merge fields without using a template.
> 
> * If your template contains merge fields, you must include all merge fields in your request or none at all.


<!--
### Send Email Using a Template

Using the [Personalization API endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/personalization/), you can send an email specifying a template ID. The `substitutions` object contains the variable names (as keys) and the values you want to substitute in the template, for the audience.

> **Important:** If your template contains merge fields, you must include all merge fields in your request or none at all.


In this example, we are targeting the Named User `aandersson` and providing values for `FIRST_NAME` AND `LAST_NAME` keys included in the template.

**Example Request With a Template**


```http
POST /api/templates/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "device_types": [
      "email"
   ],
   "audience": {
      "named_user": "aandersson"
   },
   "merge_data": {
      "template_id": "bde1d200-e68d-4230-bd9a-34a1939b18ff",
      "substitutions": {
         "FIRST_NAME": "Anders",
         "LAST_NAME": "Andersson"
      }
   }
}
```


### Send Email Without a Template {#push-api}

When sending an email via the [Push API](https://www.airship.com/docs/developer/rest-api/ua/operations/push/), you must set [email platform overrides](https://www.airship.com/docs/developer/rest-api/ua/schemas/platform-overrides/#emailoverrideobject) such as `sender_name`, `sender_address`, etc.

**Example Request Without a Template**


```http
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
      "named_user": "jane_doe"
   },
   "device_types": [
      "email",
      "android"
   ],
   "notification": {
      "android": {
        "alert": "Hello Android user!"
      },
      "email": {
        "subject": "Winter Sale!",
        "html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.airship.com/email/success.html\">Unsubscribe</a></p>",
        "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.airship.com/email/success.html\"]]",
        "message_type": "commercial",
        "sender_name": "Airship",
        "sender_address": "team@airship.com",
        "reply_to": "no-reply@airship.com"
      }
   }
}
```


-->


<!-- /PAGE: Getting Started -->

<!-- PAGE: Commercial vs. Transactional Email, PATH: https://www.airship.com/docs/developer/api-integrations/email/commercial-transactional/ -->

# Commercial vs. Transactional Email

> The Airship platform handles commercial email legal requirements and industry best practices, from opt-in/opt-out rules to data privacy laws.An email can contain three different types of information:

* **Commercial content** — Advertises or promotes a commercial product or service, including content on a website operated for a commercial purpose.
* **Transactional (or *relationship*) content** — Facilitates an already agreed-upon transaction, or updates a customer about an ongoing transaction.
* **Mixed content** — Both commercial and transactional content in the same message.

> **Note:** Emails are considered **commercial by default and require an unsubscribe link**. You can manually flag messages as transactional and send them without the unsubscribe link, in accordance with CAN-SPAM regulations.


## Commercial Content

If the message contains only commercial content, its primary purpose is commercial, and it must comply with the requirements of [CAN-SPAM](https://www.ftc.gov/enforcement/rules/rulemaking-regulatory-reform-proceedings/can-spam-rule). If it contains only transactional or relationship content, its primary purpose is transactional or relationship. In that case, it may not contain false or misleading routing information, but is otherwise exempt from most provisions of the CAN-SPAM Act.

## Transactional Content

The primary purpose of an email is transactional or relationship if it consists only of content that:

1. Facilitates or confirms a commercial transaction that the recipient already has agreed to;
1. Gives warranty, recall, safety, or security information about a product or service;
1. Gives information about a change in terms or features or account balance information regarding a membership, subscription, account, loan, or other ongoing commercial relationship;
1. Provides information about an employment relationship or employee benefits; or
1. Delivers goods or services as part of a transaction that the recipient already has agreed to.

## Mixed Content

It's common for email sent by businesses to mix commercial content and transactional or relationship content. When an email contains both kinds of content, the primary purpose of the message is the deciding factor. Here's how to make that determination:

> If a recipient reasonably interpreting the subject line would likely conclude that the message contains an advertisement or promotion for a commercial product or service, or if the message's transactional or relationship content does not appear mainly at the beginning of the message, the primary purpose of the message is commercial.

So, when a message contains both kinds of content – commercial and transactional or relationship – if the subject line would lead the recipient to think it's a commercial message, it's a commercial message for CAN-SPAM
purposes. Similarly, if the bulk of the transactional or relationship part of the message doesn't appear at the beginning, it's a commercial message under the CAN-SPAM Act.

For more information, see the FTC's [CAN-SPAM Act: A Compliance Guide for Business](https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business).

## Opt-in and Opt-out Requirements {#opt-in-reqs}

**Commercial Emails**

* Require date of consent to subscribe (register) an email address to the commercial email list.

* Require an [unsubscribe link](https://www.airship.com/docs/guides/messaging/messages/content/email/email-unsubscribe-links/) in the email content. You can also provide separate unsubscribe links to opt out of [Subscription Lists](https://www.airship.com/docs/reference/glossary/#subscription_list).

* Customers who unsubscribe from commercial emails will still be registered to receive transactional emails (unless they unsubscribe from a transactional email as well).

**Transactional Emails**

* Date of consent to register an email address to receive transactional emails is optional. If no consent date is included and the user has opted out of transactional type emails from your brand, then they will not be able to receive any in the future. If they need to be re-registered to receive these emails, then their date of consent is required and must be later than their opt out date.

* Unsubscribe links are not required for transactional email messages, and in most cases we do not recommend including one.

**Business-critical Emails**

* There are some cases where a brand would like to include an unsubscribe link on a type of transactional email but will still need to send business-critical emails, such as order confirmations or password reset emails. In  these cases, the opt-out can be overridden and sent regardless of unsubscribe status (for commercial or transactional).

* Business-critical emails should never include an unsubscribe link.

**Bounce Handling**

See: [Bounce Handling](https://www.airship.com/docs/developer/api-integrations/email/bounce-handling/).

**Spam Complaints**

* Some end users will not want to receive any emails from your brand at all,
   and will show this by hitting the Spam button in their inbox. When
   this occurs, Airship will remove the email address from your list,
   mark the email channel as a spam complaint, and never deliver to it again.

**Change of Address**

* If a customer has changed their email address in a brand's system, you can update the
   Airship record using the API. This will update the email address while maintaining the channel ID, named user, and any tag information added for that channel. See: [Updating Addresses and Registration](https://www.airship.com/docs/developer/api-integrations/email/getting-started/#updating-addresses-and-registration).

**Compliance Event API**

* Maintaining clean mailing lists is important — not only for Airship,
   but for your brand as well. You can use the free [Compliance Event API](https://www.airship.com/docs/developer/rest-api/connect/operations/compliance-event-stream/#opencomplianceeventstream) to stream send, unsubscribe, bounce, and spam complaint events. These events should be processed and properly handled on your end on a regular basis.


<!-- /PAGE: Commercial vs. Transactional Email -->

<!-- PAGE: Analytics and Reporting, PATH: https://www.airship.com/docs/developer/api-integrations/email/analytics-and-reporting/ -->

# Analytics and Reporting

> Airship captures events from last-mile delivery services, so you can track both email statuses and engagement.## Last-mile Events

Last-mile delivery events appear in [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds) and message reports as  [Custom Email Events](https://www.airship.com/docs/developer/rest-api/connect/schemas/custom-email-events/).

Status events, like `bounce` and `delay`, help you determine whether or not your messages are received by your audience. We also capture `open`, `click`, and `delivery` events so you can track engagement metrics for your email campaigns. For `click`, only HTTP and HTTPS links are tracked.

See [Custom Email Events](https://www.airship.com/docs/developer/rest-api/connect/schemas/custom-email-events/) for a complete list of last-mile events and their properties.

## Custom Events

To add your own custom events to a channel or named user, use the [Custom Events API](https://www.airship.com/docs/developer/rest-api/ua/operations/custom-events/).

## Disable Events

When creating your message, you can disable open and click tracking to preserve your audience's privacy and exclude irrelevant messages from your metrics. You may want to disable open and click tracking for things like transactional messages or messages where you don't have a clear call to action.

See [Creating content](https://www.airship.com/docs/guides/messaging/messages/content/email/email/#creating-content) in *Email content*.

## Performance Analytics

Additional reporting is available in [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa). See: [Email in Performance Analytics](https://www.airship.com/docs/guides/reports/analytics/email/).

<!-- /PAGE: Analytics and Reporting -->

<!-- PAGE: Email Bounce Handling and Suppression, PATH: https://www.airship.com/docs/developer/api-integrations/email/bounce-handling/ -->

# Email Bounce Handling and Suppression

> Airship handles issues with email delivery automatically to protect your sending reputation and help ensure compliance.## Email bounce events

When an email fails to deliver to a recipient's inbox, Airship will report that failure via the [Compliance Stream](https://www.airship.com/docs/guides/reports/real-time-data-streaming/#compliance-events-for-email-and-sms) and internal reporting. Emails can bounce for a variety of reasons, which Airship will consider either a "soft" or "hard" bounce.  

Airship distinguishes between hard and soft bounces with a `bounce_class`. Hard bounces are represented in events with `bounce_class` values of 10, 30, or 90. When a hard bounce response is received, an email address is considered to be permanently undeliverable. All other classes of bounce are considered soft bounces and delivery will continue to be attempted for future messages. In order to protect your sending reputation, email addresses that receive a hard bounce will be "suppressed" from future messaging.

## Email suppression

Suppression acts as a failsafe to prevent accidental sends to addresses that may pose a risk to either sending reputation or to legal compliance. Airship tracks a suppression state per channel, in addition to transactional and commercial opt-in status. To be eligible to receive email messages, an address must be both opted-in and not suppressed for the type of messaging being sent. 

For example, when a recipient marks a message as spam, a suppression state of `spam_complaint` is added to the channel. While suppressed, the email address will not receive any messaging, regardless of their opt-in state. If an audience list is later uploaded that updates the opt-in status of the email address, Airship will continue to honor the suppression state and will continue to not send any messages to the address.

### Suppression types

An email channel can have one of four suppression state values. Depending on the value, the suppression state can function as either a full or partial block.

* `bounce` — A hard bounce response was received. The address is considered undeliverable, and continuing to send to it could hurt the sender's reputation. **No future messages will be sent to the email address**.

* `spam_complaint` — A recipient marked a [Transactional Email](https://www.airship.com/docs/reference/glossary/#transactional_email) as spam. This indicates they do not wish to receive any additional messages from the brand, regardless of type. **No future messages will be sent to the email address**.

* `commercial_spam_complaint` — A recipient reported a message designated as [Commercial Email](https://www.airship.com/docs/reference/glossary/#commercial_email) as spam. They have indicated that they do not want to receive future communications of that type. **Transactional email will continue to be sent, but no future commercial email will be sent**.

* `imported` — This value may be set manually via API or list upload to suppress a channel. **No future messages will be sent to the email address**.

### Looking up suppression state

* **API** — Use the API to download a list of all email channels with their suppression state included.
   * [Channel Lookup](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#getchannel)
   * [Look Up an Email Address](https://www.airship.com/docs/developer/rest-api/ua/operations/email/#getemailchannel)

* **Dashboard** — If you know the email address, named user, or channel ID that you are looking for, you can view the suppression state for an individual channel in [Contact Management](https://www.airship.com/docs/guides/audience/contact-management/#viewing-channel-details).

### Setting suppression

Set suppression status for an individual email channel using the [Suppress an Email Channel API](https://www.airship.com/docs/developer/rest-api/ua/operations/email/#suppressemailchannel).

<!-- Not for this release.

CSV uploads can be performed in several ways:

* [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send) CSV upload in the Message composer
* Use the [Create and Send API](https://www.airship.com/docs/developer/rest-api/ua/operations/bulk-sending/#createandsend)
* [CSV upload](https://www.airship.com/docs/reference/messages/csv-formatting/) for setting tags and attributes or for associating channels with [Named Users](https://www.airship.com/docs/reference/glossary/#named_user)

When preparing your CSV, set the suppression state on each channel to a valid value in the `ua_email_suppression_state` column.

-->

### Removing suppression

> **Important:** * Suppression is an added layer of protection that opts out an email channel from messaging, preventing sending email to the address. Please consult your legal counsel to determine if your specific use case aligns with regulatory requirements in your jurisdiction.
> 
> * After removing suppression, you must opt the channel back in to messaging before they can receive email from you again.


For the API, use the [Remove Suppression from an Email Channel API](https://www.airship.com/docs/developer/rest-api/ua/operations/email/#unsuppressemailchannel) to remove the suppression reason. For the dashboard, see [Removing email suppression](https://www.airship.com/docs/guides/audience/contact-management/#removing-email-suppression) in *Contact Management*.

## Bounce class reference

The `bounce` compliance event type reflects the reason that an email server or recipient rejected your email as a `bounce_class`. The `bounce_class` is a reason code between 1 and 100.

> **Note:** Hard `bounce_class` events (classifications 10, 30, and 90) result in an automatic opt-out for the `delivery_address` listed in the event.


|Classification|Name|Description|Category|
|--- |--- |--- |--- |
|1|Undetermined|The response text could not be identified.|Undetermined|
|10|Invalid Recipient|The recipient is invalid.|Hard|
|20|Soft Bounce|The message soft bounced.|Soft|
|21|DNS Failure|The message bounced due to a DNS failure.|Soft|
|22|Mailbox Full|The message bounced due to the remote mailbox being over quota.|Soft|
|23|Too Large|The message bounced because it was too large for the recipient.|Soft|
|24|Timeout|The message timed out.|Soft|
|25|Admin Failure|The message was failed by SparkPost’s configured policies.|Admin|
|26|Smart Send Suppression|The message was suppressed by Smart Send policy.|Admin|
|30|Generic Bounce: No RCPT|No recipient could be determined for the message.|Hard|
|40|Generic Bounce|The message failed for unspecified reasons.|Soft|
|50|Mail Block|The message was blocked by the receiver.|Block|
|51|Spam Block|The message was blocked by the receiver as coming from a known spam source.|Block|
|52|Spam Content|The message was blocked by the receiver as spam.|Block|
|53|Prohibited Attachment|The message was blocked by the receiver because it contained an attachment.|Block|
|54|Relaying Denied|The message was blocked by the receiver because relaying is not allowed.|Block|
|60|Auto-Reply|The message is an auto-reply/vacation mail.|Soft|
|70|Transient Failure|Message transmission has been temporarily delayed.|Soft|
|80|Subscribe|The message is a subscribe request.|Admin|
|90|Unsubscribe|The message is an unsubscribe request.|Hard|
|100|Challenge-Response|The message is a challenge-response probe.|Soft|

<!-- /PAGE: Email Bounce Handling and Suppression -->

<!-- PAGE: Email Custom Unsubscribe Pages, PATH: https://www.airship.com/docs/developer/api-integrations/email/custom-unsubscribe-pages/ -->

# Email Custom Unsubscribe Pages

> Unsubscribe links are a critical component of your email program. You can take advantage of Airship's default unsubscribe link behavior or use a custom unsubscribe flow.> **Important:** If you use a custom unsubscribe page, it is your responsibility to ensure that email unsubscribe requests are handled in accordance with CAN-SPAM and other regulatory requirements that may apply to your local jurisdiction.


By default, email is for [commercial use](https://www.airship.com/docs/developer/api-integrations/email/commercial-transactional/) 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 List](https://www.airship.com/docs/reference/glossary/#subscription_list)

This method can be useful if you host your own email unsubscribe page rather than using an Airship [Preference Center](https://www.airship.com/docs/reference/glossary/#preference_center).

### 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](https://www.airship.com/docs/guides/messaging/messages/content/email/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](https://support.airship.com/) 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 the Airship dashboard: Next to your project name, select the dropdown menu (▼), then **Project Details**.

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.

1. **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](https://www.airship.com/docs/developer/rest-api/ua/operations/email/#customunsubscribeemailchannel).

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

**Web page with an unsubscribe link**

```html
<!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](https://www.airship.com/docs/developer/rest-api/ua/).

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](https://www.airship.com/docs/guides/messaging/messages/content/email/email-unsubscribe-links/).

To make sure that your unsubscribe page is successfully opting out users in Airship, use [Contact Management](https://www.airship.com/docs/guides/audience/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](https://support.airship.com/) 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 the Airship dashboard: Next to your project name, select the dropdown menu (▼), then **Project Details**.


<!-- /PAGE: Email Custom Unsubscribe Pages -->

<!-- PAGE: Apple Private Email Relay, PATH: https://www.airship.com/docs/developer/api-integrations/email/apple-private-email-relay/ -->

# Apple Private Email Relay

> If you use the [*Sign in with Apple* login service](https://developer.apple.com/sign-in-with-apple/) in your app, your users can choose to route emails from you through Apple's private email relay service.[Apple's private email relay service](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/communicating_using_the_private_email_relay_service) lets your users hide their email addresses as an added layer of privacy when using your app.

When a user enables [Hide My Email](https://support.apple.com/en-us/HT210425), Apple generates a unique and randomized email address, e.g., `a1b2c3@privaterelay.appleid.com`, that you can associate with that user. When you send email to that address, Apple forwards it to the email address associated with the customer's Apple ID.

## Registering your domains with Apple

In order to send Airship email messages to those using Apple private email relay, you must first register your domains with Apple. This ensures that if there’s a problem causing emails to fail, or the user no longer wants to receive your emails, Apple can notify you of the bounce. Follow the steps for *Register domains* in Apple's developer guide [Configure private email relay service](https://developer.apple.com/help/account/configure-app-capabilities/configure-private-email-relay-service/).

If you are using a separate bounce domain from your sending domain, you'll need to register both the sending and the bounce domains. If you don’t register all the source domains, email sent to the private relay service will result in a bounce.

> **Important:** * Before registering your domains, your Airship project must already be provisioned for email. Contact your account manager or [Airship Support](https://support.airship.com) if your project does not yet include email.
> 
> * If you attempt to send emails to private relay email addresses but haven't registered your domains with Apple, your messages will be rejected.



<!-- /PAGE: Apple Private Email Relay -->

<!-- PAGE: Data Collection, PATH: https://www.airship.com/docs/developer/api-integrations/email/data-collection/ -->

# Data Collection

> Understand what data is collected for email channels.## Email event data collection

Through our integration with our email service provider partner, Airship captures email event data to measure campaign performance, track engagement, take action on spam complaints, and to handle unsubscribe requests and other email bounce events. This information is used to populate reports, including [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa). It is also made available for processing outside of Airship via [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds). 

The following is a list of email events that we capture:

| Event name | Description |
| --- | --- |
| injection | Message is received by or injected into our email service provider partner |
| delivery | Remote Message Transfer Agent or Mailbox acknowledged receipt of a message |
| bounce | Remote Message Transfer Agent or Mailbox has permanently rejected a message |
| spam_complaint | Message was reported as spam by the recipient |
| out_of_band | Remote Message Transfer Agent or Mailbox initially reported acceptance of a message, but it has since reported that the message was not delivered |
| delay | Remote Mailbox has temporarily rejected a message |
| click | Recipient clicked a tracked link in a message |
| open | Recipient opened a message in a mail client, rendering a tracking pixel at the bottom of the message |
| initial_open | Recipient opened a message in a mail client, rendering a tracking pixel at the top of the message |
| list_unsubscribe | Recipient clicked the 'unsubscribe' button on their email client |
| link_unsubscribe | Recipient clicked an unsubscribe link in a received email |

To provide the services, Airship uses an email provider Subprocessor. The Subprocessor may also process the following data:

* Email cloud sending data
   * Email address and contact data: name, email address, and other demographic and segment data provided by you as the customer
   * Email sending information: IP addresses, usage data, cookies data, location data, browser data
   * Email content
* Event data as described in this document

The data is used by the Subprocessor to provide the services, including event insights of emails sent to customers, provide support and troubleshooting, and to fulfill its legal obligations.

### Recipient details per event

The following is a list of recipient data that we capture for [email events that we capture](#email-event-data-collection):

| Recipient data | Description | Applicable Events |
| --- | --- | --- |
| Channel ID | Email channel identifier | *All events* |
| Email Address | Email address of the end-user | *All events* |
| Event Name | Type of engagement event | *All events* |
| User Agent | User agent string returned for email client or web browser | open, initial_open, click |
| Is Mobile | Indicates if this was a mobile device | open, initial_open, click |
| Is Prefetched | Indicates if this event was likely prefetched, for example through Apple MPP | open, initial_open, click                        |
| Is Proxy | Indicates if the user agent is a proxy server | open, initial_open, click |
| Agent Family | Agent or client type based on user agent | open, initial_open, click |
| Device Brand | Device Manufacturer based on user agent | open, initial_open, click |
| Device Family | Device Model based on user agent | open, initial_open, click |
| OS Family | Operating system based on user agent | open, initial_open, click |
| OS Version  | Operating system version based on user agent | open, initial_open, click |

Tracking for `click`, `open`, and `initial_open` is enabled by default. You can disable open and click tracking per channel in [Contact Management](https://www.airship.com/docs/guides/audience/contact-management/#viewing-channel-details). You can disable open and click tracking per message when [configuring Sender Information](https://www.airship.com/docs/guides/messaging/messages/content/email/email/#creating-content).

## Email pixel tracking

Email opens are measured using a transparent pixel image embedded in the message HTML. When an email client loads the image, the request is recorded as an open event. This helps gather data that indicates the email's effectiveness, aiding in marketing strategy and optimization of future campaigns.

* `initial_open` is triggered by a pixel positioned near the top of the message.
* `open` is triggered by a pixel positioned near the bottom of the message.

Email marketers depend on being able to measure campaign success and audience engagement through pixel tracking. Changes in email client behavior, particularly within Gmail and Apple Mail, now influence the accuracy of these metrics.

### Prefetching

Tracking pixel prefetching occurs when an email client, or intermediary proxy, requests remote images, including the tracking pixel, before or without a human viewing the message. These automated requests can register as opens and inflate open and unique open counts. In addition, device and location attribution may reflect proxy infrastructure rather than the end device.

### Gmail prefetching and Apple MPP

When a user of Google's Gmail receives an email during their session, whether on web or mobile app, Gmail triggers prefetching in order to download all email images just before display.

The prefetch request originates from a Google IP address and includes a specific user-agent string, which Airship uses to distinguish prefetch opens from genuine opens. An example of this user-agent string is `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.246 Mozilla/5.0`.

With the release of Apple iOS 15, iPadOS 15, watchOS 8 and macOS 12 Monterey, Apple began offering Mail Privacy Protection (MPP), which hides the recipient's email address from senders. This prevents the sender from being able to identify the recipient or use pixel tracking. Also, open timestamps from MPP do not represent the actual time a recipient viewed the message. Similar to Gmail, Apple's proxy servers employ specific user-agent strings.

Most Apple Mail users enable MPP. The inability to discern genuine opens from Apple's prefetch opens renders open statistics originating from Apple devices unreliable, so monitoring user-agent strings is important for understanding email opens' origins.

### Interpreting prefetched opens

Prefetching makes it hard to know whether an open is from a real user or an automated client. Simply filtering by user agent isn't reliable since client behavior varies, and excluding prefetched traffic entirely can distort engagement metrics.

Airship addresses this challenge by combining multiple engagement signals rather than relying solely on open events. Our reporting emphasizes stronger engagement indicators, such as link clicks enriched with URL parameters, to provide a clearer view of genuine user behavior.

Airship separates prefetched opens from genuine opens, giving you flexibility in how you analyze your email performance.

**In reporting:**
- Message reports count prefetched and unknown opens separately from genuine opens. With the Click Map, you can learn how to position key elements where they are most likely to be seen and engage users. See [Email Performance](https://www.airship.com/docs/guides/reports/message/#email-performance) in *Message Reports*.
- [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa) lets you access separate Total and Unique opens using the `IsPrefetched` dimension. See [Email in Performance Analytics](https://www.airship.com/docs/guides/reports/analytics/email/) to explore this data.

**Best practices for analysis:**
- Segment or exclude events flagged as `Is Prefetched` when analyzing performance.
- Prioritize `click` events and downstream conversion metrics over opens for KPI tracking.
- Use the separated data to understand the impact of prefetching on your specific audience.

## Data privacy

Airship makes HTTPS encryption (also referred to as TLS connection) available for data in transit to or from the Service. For more information, see [Airship Security Measures](https://www.airship.com/legal/security-measures/). Email data collected by Airship is not transferred to any third parties unless a partner integration is enabled and configured by the application. For information on individual data requests, see [Individual Data Privacy Rights](https://www.airship.com/docs/guides/audience/privacy/individual-data-privacy/).


<!-- /PAGE: Data Collection -->

<!-- PAGE: Email Compliance, PATH: https://www.airship.com/docs/developer/api-integrations/email/compliance/ -->

# Email Compliance

> Airship supports email best practices.> **Important:** Please note that this content is provided for information purposes only and is not intended to be nor should be relied on as legal or compliance advice.
> 
> Different locations may have varying legal and privacy requirements for email notifications, so please verify with your legal or regulatory compliance team that your email usage, proposed use cases, and messaging configuration are compliant with applicable local laws and regulations.


Airship's email service provides customers with a platform for building successful marketing programs while supporting compliance with applicable laws and regulations such as [CAN-SPAM](https://www.ftc.gov/enforcement/rules/rulemaking-regulatory-reform-proceedings/can-spam-rule), [General Data Protection Regulation (GDPR)](https://gdpr-info.eu/), and the Directive on Privacy and Electronic Communications (the EU's ePrivacy Directive).

See also [Data Collection for Email](https://www.airship.com/docs/developer/api-integrations/email/data-collection/).

## General requirements

You must obtain consent, provide disclosure, and designate email type.

### Commercial and transactional email

Email messages generally fall into two categories:

- **Commercial** — This is primarily promotional content intended to market products or services.  
   - Most jurisdictions require prior consent before sending.
   - Recipients must be able to easily unsubscribe.
- **Transactional** — This is content necessary to facilitate or complete a transaction, such as receipts, order confirmations, and account alerts.  
   - Transactional email may not require consent, but must stay within the scope of the transaction.

When composing a message in Airship, designate the type of email. This ensures that unsubscribe handling, suppression logic, and analytics are applied appropriately. See [Commercial vs. Transactional Email](https://www.airship.com/docs/developer/api-integrations/email/commercial-transactional/).

### Consent management

Airship supports consent collection through:

- **Forms and [Scenes](https://www.airship.com/docs/reference/glossary/#scene)** — Collect email addresses and marketing permissions directly in Airship or using your own forms.
- **API integration** — Sync subscriber consent status from external systems.

Your subscriber lists should only include recipients who have given the required consent for the type of messages you send.

## Unsubscribe handling and suppression management

For commercial messages, Airship enforces unsubscribe compliance:

- [**Unsubscribe links**](https://www.airship.com/docs/guides/messaging/messages/content/email/email-unsubscribe-links/) — Add to templates or message footers.
- **Automatic suppression** — Airship suppresses unsubscribed addresses, excluding from future commercial sends.
- **Bounce handling** — Airship suppresses hard-bounced addresses to maintain deliverability.

Airship also suppresses addresses marked as spam complaints, where feedback loops are available. Suppression helps you stay compliant and protect your sender reputation. See [Email Bounce Handling and Suppression](https://www.airship.com/docs/developer/api-integrations/email/bounce-handling/).

You can review unsubscribed and suppressed addresses using the Contact Management tool. See [Removing email suppression](https://www.airship.com/docs/guides/audience/contact-management/#removing-email-suppression) in *Contact Management*.

## Data collection and tracking

Airship collects email performance data such as delivery, open, click, bounce, spam complaint, and unsubscribe events. See [Data Collection for Email](https://www.airship.com/docs/developer/api-integrations/email/data-collection/).

### Tracking considerations

Event tracking, specifically open tracking, in Airship operates using pixels placed in emails that detect opens through pixel rendering detection.

Before enabling event tracking, ensure you have collected the appropriate consent and configured tracking accordingly.

In many jurisdictions, pixel tracking must be disabled by default and is subject to prior consent. These are two standard methods for ensuring prior consent is received: 

- **Obtain consent at the time of email collection:** This method requires adequate disclosures, for example, information about the purposes of tracking and a link to an applicable privacy policy, and an opt-in checkbox that is not pre-selected when data subjects provide their email address. 

- **Obtain consent using a link embedded in an email without a tracking pixel:** This method may be appropriate after initial email collection. It requires sending an email without a tracking pixel that links to a page where recipients can review adequate disclosures and opt in to the use of tracking pixels using an opt-in checkbox that is not pre-selected.

### Tracking controls

Configure tracking to align with your privacy commitments:

- **Channel-level control** — Disable open and click tracking for specific email channels using Contact Management, CSV import, or API. See the following section, [Managing tracking opt-in status](#managing-tracking-opt-in-status).

- **Message-level control** — Disable tracking for individual sends, even if the channel is opted in.

### Collecting open-tracking consent on your sign-up form

Certain jurisdictions may require that prior consent for open pixel tracking be collected separately from consent to receive emails. This separate consent should be clearly labeled with a description of the tracking purpose.  

Through customer-hosted email sign-up forms, if you need to add a separate check box for email pixel tracking, you can pass the recipient's tracking consent status using the `open_tracking_opted_in` or `open_tracking_opted_out` field in the [Email channel registration API](https://www.airship.com/docs/developer/rest-api/ua/operations/email/#registeremailchannel). This records consent at the channel level, and Airship will respect the tracking status on all subsequent sends to that channel.

If a recipient does not check the tracking consent box, register the channel with an `open_tracking_opted_out` date. Use the `click_tracking_opted_out` field if click tracking consent is also required for your use case.

### Managing tracking opt-in status

You have multiple options for managing the tracking opt-in status for an email channel:

In the dashboard, go to **Audience**, then **Contact Management**, search for an email channel, and select the arrow icon (→) for the channel. You can then edit each tracking option.
   ![Enabled Open and Click tracking for an email channel in Contact Management](https://www.airship.com/docs/images/contact-mgmt-email-tracking_hu_230ef4bffbfc629d.webp)
   
   *Enabled Open and Click tracking for an email channel in Contact Management*

The Contact Management tool is an [AXP](https://www.airship.com/docs/reference/feature-packages/) feature. If you are not on AXP, you can view Tracking for an email channel but not change status. See [Viewing channel details](https://www.airship.com/docs/guides/audience/contact-management/#viewing-channel-details) in *Contact Management*.

Using CSV upload or the API, specify dates for `open_tracking_opted_in` / `open_tracking_opted_out` or `click_tracking_opted_in` / `click_tracking_opted_out` with:

   * [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send) CSV upload in the Message composer or using the [Create and Send API](https://www.airship.com/docs/developer/rest-api/ua/operations/bulk-sending/#createandsend)
   * [CSV upload](https://www.airship.com/docs/reference/messages/csv-formatting/) for setting tags and attributes or for associating channels with [Named Users](https://www.airship.com/docs/reference/glossary/#named_user)
   * The [Email channel registration API](https://www.airship.com/docs/developer/rest-api/ua/operations/email/#registeremailchannel)

By default, new channels are opted in to both open and click tracking. A channel can be opted out of tracking by setting an opted out date. The channel can be opted back in to tracking by setting an opted in date that is newer than the opted out date.

## Data access and auditing

For compliance reporting and auditing, export email engagement data or stream events to your systems in real time using Airship's APIs. See [Compliance events for Email and SMS](https://www.airship.com/docs/guides/reports/real-time-data-streaming/#compliance-events-for-email-and-sms) in *Real-Time Data Streaming*.


<!-- /PAGE: Email Compliance -->

<!-- /SECTION: Email -->

<!-- SECTION: SMS, MMS, and RCS, PATH: https://www.airship.com/docs/developer/api-integrations/sms/ -->

## SMS, MMS, and RCS

Set up and manage SMS, MMS, and RCS for your Airship project.

<!-- PAGE: Getting Started, PATH: https://www.airship.com/docs/developer/api-integrations/sms/getting-started/ -->

# Getting Started

> Configure your project to register SMS users with Airship, and send them a message.When working with SMS, you must register each audience member's [MSISDN](https://www.airship.com/docs/reference/glossary/#msisdn) with a `sender` using the Channels API or a keyword operation. Registering an SMS channel returns a [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id). If the audience member did not explicitly opt in to notifications when they register, you'll trigger a double opt-in process.

This document explains the registration processes for SMS channels.

See the [SMS Channels API reference](https://www.airship.com/docs/developer/rest-api/ua/operations/sms/) for more information about SMS channel endpoints.

> **Tip:** If you use an AI coding assistant, you can connect it to Airship with Skills and an MCP server. See [Airship AI Tools](https://www.airship.com/docs/developer/ai-tools/ai-tools/).

## Configure Your Project

[Contact Airship Sales](https://www.airship.com/contact-us/) to:

1. Provision your project for SMS notifications.
1. Set up your **sender IDs**.

A sender ID is an originating phone number or string identifier used to indicate who an SMS message comes from. Members of your audience subscribe (opt in) to each sender ID they want to receive messages from.

Your project can have multiple senders, and your audience can opt in to multiple senders within your project.

If your Airship project has more than one sender ID, you can select one when you create your message. Selecting an individual sender ID ensures that your message only goes to members of your audience subscribed to that sender.

When your sender ID is a short code, prepend the 2-letter [ISO 3166 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) when using the short code in the API. This is similar to the way that you would prepend a country code to a standard phone number.

See [SMS senders](https://www.airship.com/docs/developer/api-integrations/sms/senders/) and [RCS branded senders](https://www.airship.com/docs/developer/api-integrations/sms/rcs/).

> **Important:** Procuring or migrating an existing sender code is not instantaneous. Short code migrations may require up to eight weeks of lead time.


## Set Up Keywords

You can set up keywords in the Airship dashboard. See: [SMS keywords](https://www.airship.com/docs/guides/messaging/features/sms-keywords/).

## Register SMS Users

After Airship completes your project setup, you can register SMS users, which returns [Channel IDs](https://www.airship.com/docs/reference/glossary/#channel_id). The process to register users can depend on local data privacy laws and whether or not your audience explicitly opts in to notifications.

There are multiple ways to register users:

* **Phone number submission in a Scene** — A user can submit their phone number using the [SMS element](https://www.airship.com/docs/guides/messaging/editors/native/elements/#sms) in a [Scene](https://www.airship.com/docs/reference/glossary/#scene). Registration automatically triggers the [Double Opt-In](https://www.airship.com/docs/reference/glossary/#double_opt_in) process, and the phone number is associated with the [Contact](https://www.airship.com/docs/reference/glossary/#contact) viewing the Scene.
* **Mobile-originated message** — A user can text you a keyword that explicitly opts them in to your sender's audience.
* **Opt-in form** — A user can sign up for SMS messages through an [opt-in form](https://www.airship.com/docs/guides/messaging/features/opt-in-forms/) you can add to your website.
* **SMS channel registration API** — Use the SMS channel registration API to register individual channels. This may be helpful if your audience opts into SMS messages from your app or website.
* **Simultaneously send a message and register new user** — See [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send).
* **SDK** — Register an SMS channel through the [Android](https://www.airship.com/docs/developer/sdk-integration/android/audience/contacts/#sms-channel-association) and [Apple](https://www.airship.com/docs/developer/sdk-integration/apple/audience/contacts/#sms-channel-association) SDKs.
* **CSV Upload** — You can upload [MSISDNs](https://www.airship.com/docs/reference/glossary/#msisdn) in a CSV file to set [Tags](https://www.airship.com/docs/reference/glossary/#tag) or [Attributes](https://www.airship.com/docs/reference/glossary/#attributes). Airship registers new channels for MSISDN/sender combinations that are new to your project. See: 
    * [Setting attributes using a CSV file](https://www.airship.com/docs/guides/audience/attributes/setting/#csv-file)
    * [Setting tags using a CSV file](https://www.airship.com/docs/guides/audience/tags/#file-upload)

---

Users explicitly opting into notifications using a keyword trigger an opt in flow. Airship defaults to a double opt-in, but it is common to use a single opt-in flow for keyword purposes.

If your user does not explicitly opt into notifications, or provides you their `msisdn` without using a keyword (through a sign up on your website, in your app, etc.), you will trigger a double opt-in by registering the user through the channel registration API without an `opted_in` value.

If you register a member of your audience using the channel registration API with an `opted_in` value, the user will not receive a notification confirming that they opted in.

```mermaid
graph TD
  A[User provides<br>MSISDN] -->B{Did user<br>explicitly opt in?}
  B -->|No| C[Create channel]
  B --> |Yes, with keyword| D[Create channel]
  B --> |"Yes, without keyword<br>(Register through API)"| Z[Create channel]
  subgraph Single Opt-in
  D
  end
  C -->|Send MSISDN MT opt-in request| E{Did user respond<br>with opt-in keyword?}
  E -->|Yes| F[Update channel with opt-in]
  E -->|No| G[User cannot receive messages]
  F --> |Send user confirmation| H[User can receive messages]
  D -->|Send user confirmation| H
  Z --> H
  subgraph Double Opt-in
  C
  E
  F
  G
end
subgraph Silent Opt-in
  Z
end
```


### SMS Channel Registration API

You can use the [SMS channel registration API](https://www.airship.com/docs/developer/rest-api/ua/operations/sms/#registersmschannel) to register SMS users when they opt in to SMS notifications through your website or app.

Users register and opt in to messages from particular senders, so Airship generates a unique `channel_id` for each `msisdn`/`sender` combination.

You can also create channels that are not opted in to notifications, triggering a double opt-in flow. You might do this when offering shipping notifications or event updates to users who have opted in to different notifications from you.

If you do not provide an `opted_in` date when registering a new user, Airship starts a double opt-in process and sends an message to the MSISDN, asking the user to respond with a keyword to initiate the opt-in process, followed by a second message to text "Y" (or "y") to complete the opt-in. **You cannot send a message to a user until you update their channel with a valid `opted_in` value.**

**Example request**

```http
POST /api/channels/sms HTTP/1.1
Authorization: Basic <master secret authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "msisdn" : "15558675309",
   "sender": "12345",
   "opted_in": "2018-07-10T11:59:59"
}
```


**Example response**


```http
HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json; version=3
Location: https://go.urbanairship.com/api/channels/34b3dfc1-d717-40fe-89e8-10584ed1c123df6a6b50-9843-0304-d5a5-743f246a4946

{
   "ok": true,
   "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}
```


### Send a Message While Registering Users {#create-and-send}

If your audience provides you their MSISDNs, you can register them with Airship and send them a message at the same time using [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send).

If you provide a `ua_opted_in` value for the new channels in your audience, they will be eligible to receive future messages. If you do not set a `ua_opted_in` value for the new channels, they'll receive the message and begin the double opt-in flow.

Addresses in the list that are already registered with Airship will receive your message if either of the following conditions are true:

* They are already opted in for messaging (their channel has a valid `opted_in` value).
* You provide a `ua_opted_in` date-time value for an `msisdn` that is newer than an `opted_out` value on the channel. This does not update the `opted_in` value on the channel; it only overrides the `opted_out` value to send the current message. You must update the `opted_in` value using [SMS channel update API](https://www.airship.com/docs/developer/api-integrations/sms/opt-in-out-handling/#update-sms-channel) to opt it back into your messaging audience.

<!--```mermaid

```
-->

Your CSV must include `ua_msisdn`, `ua_sender` and `ua_opted_in` headings. You can use additional headings to personalize messages with [Handlebars](https://www.airship.com/docs/reference/glossary/#handlebars). See [CSV formatting](https://www.airship.com/docs/guides/audience/segmentation/bulk-sending/#csv-formatting) in *Bulk sending*.

**Create and Send CSV example**

```text
ua_msisdn,ua_sender,ua_opted_in,fav_food
5558675309,12345,2020-05-05T10:34:22,tacos
5559867543,12345,2020-05-05T12:03:45,pizza
```


**Create and Send message example**

```http
POST /api/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "audience": {
        "create_and_send": [
            {
                "ua_msisdn": "15558675309",
                "ua_sender": "12345",
                "ua_opted_in": "2020-05-05T10:34:22",
                "fav_food": "tacos"
            },
            {
                "ua_msisdn": "15551234567",
                "ua_sender": "12345",
                "ua_opted_in": "2020-05-05T12:03:45",
                "fav_food": "pizza"
            }
        ]
    },
    "device_types": [
        "sms"
    ],
    "notification": {
        "sms": {
            "alert": "Hey, I hear you like {{fav_food}}"
        }
    }
}
```



### Determining Time Zone and Locale for SMS Channels {#timezone}

When you register or update an SMS user in Airship, you can set their IANA `timezone`, `locale_country`, and `locale_language`. If you don't set these values yourself, Airship attempts to infer country and time zone information from the country code and format of your audience's phone numbers ([MSISDNs](https://www.airship.com/docs/reference/glossary/#msisdn)). You can use this information to reach your SMS audience at the right time and in the right language.

> **Note:** Airship does not infer `locale_language` values.


Airship takes advantage of the `timezone` when you schedule a message using `local_scheduled_time` in the API or the [Delivery By Time Zone](https://www.airship.com/docs/reference/glossary/#delivery_by_time_zone) checkbox in the Delivery step in the Airship dashboard, and sends your message to your audience at the specified time in their respective time zones.

<!-- Commented out per https://urbanairship.atlassian.net/browse/DOC-2009.

The `locale_country` and `locale_language` values support localization. If you send a [localized message](https://www.airship.com/docs/guides/messaging/messages/localization/), Airship sends your audience the appropriate version of your message based on their country or the combination of country and language values.

-->

These values all appear in an SMS channel's `tag_groups`.

**Register an SMS channel with a short code and country designation**

```http
POST /api/channels/sms HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "msisdn" : "15035556789",
  "sender": "12345",
  "opted_in": "2020-02-13T11:58:59",
  "timezone": "America/Los_Angeles",
  "locale_country": "US",
  "locale_language": "en"
}
```


> **Note:** Payloads without country codes are acceptable only if your project has a single short code for a single country.



<!-- /PAGE: Getting Started -->

<!-- PAGE: Opt-In/Out Handling, PATH: https://www.airship.com/docs/developer/api-integrations/sms/opt-in-out-handling/ -->

# Opt-In/Out Handling

> Airship handles requests to opt in and opt out of SMS notifications.Users must opt in to receive SMS messages from your Sender ID and can opt out at any time. There are four ways users can opt in or opt out of your SMS audience:

* **Mobile-Originated (MO) Message:** A message originating from the mobile handset can contain a keyword that triggers an opt-in. The opt-in keyword can trigger a single or double opt-in flow.
* **External Opt-In:** Users can opt in to SMS messages through your website using [Opt-in Forms](https://www.airship.com/docs/guides/messaging/features/opt-in-forms/) or through your app or other channels, [using the API](#non-mobile-single-opt-in).
* **SDK:** Register an SMS channel through the [Android](https://www.airship.com/docs/developer/sdk-integration/android/audience/contacts/#sms-channel-association) and [Apple](https://www.airship.com/docs/developer/sdk-integration/apple/audience/contacts/#sms-channel-association) SDKs.
* **CSV Upload:** You can include the `ua_opted_in` field when uploading [MSISDNs](https://www.airship.com/docs/reference/glossary/#msisdn) in a CSV file to set [Tags](https://www.airship.com/docs/reference/glossary/#tag) or [Attributes](https://www.airship.com/docs/reference/glossary/#attributes). Airship registers new channels for MSISDN/sender combinations that are new to your project. See: 
    * [Setting attributes using a CSV file](https://www.airship.com/docs/guides/audience/attributes/setting/#csv-file)
    * [Setting tags using a CSV file](https://www.airship.com/docs/guides/audience/tags/#file-upload)

## SMS Data Protection and Compliance

Requests to opt in to or out of SMS notifications are processed by the Airship Service, but the obligation to comply with such requests remains with the customer. Our opt-in and opt-out database is encrypted and is also segregated from campaign content. For opt-ins and opt-outs that occur via mobile-originated messages, Airship stores date/time data for those opt-ins and opt-outs for a rolling 4 years.

## Mobile-Originated Opt-Ins

A *mobile-originated message* is a message sent from a member of your audience (originating from the mobile handset of a user) to you.

### Single Opt-In

Single opt-in is the process of registering users and considering them opted in when they send you a single message containing a keyword. This method does not require users to confirm that they want to opt in through a second mobile-originated (MO) message.

While a single opt-in is a simple way to register users, it may not always be an optimal opt-in method. Airship mobile-originated opt-in handling defaults to a double opt-in process. [Contact Airship Support](https://support.airship.com/) if you want to take advantage of a single opt-in workflow.

The response to the keyword is a confirmation text message that provides information about the text program. The message usually:

* confirms that the user has subscribed to an ongoing text program.
* provides the number of messages the subscriber can expect to receive.
* informs the subscriber where they can obtain more information and how they can opt out.

Example:
: *BrandX: Welcome to the BrandX Info and Alerts Program! Message frequency varies by use. For help, reply HELP. To end, reply, STOP. Msg&DataRatesMayApply.*

### Double Opt-In

Double opt-in requires a user to send you a keyword indicating that they want to receive mobile messages, and a second keyword confirming their choice:

1. Your audience texts a keyword to trigger the opt-in process.
1. Airship sends your audience a message requesting confirmation using a keyword.
1. Your audience texts the confirmation keyword, opting in to your audience.

Because each message in the opt-in workflow supports unique keywords, the double opt-in method provides multiple indices to categorize users as they opt in to your audience; you can add, remove, or replace tags for any of the opt-in messages, ensuring that you precisely segment your audiences and target future messages to the right users.

<!-- Add example from Mitzi later?
BrandX: Thanks for your interest to join the rewards program, to confirm, please reply YES. Msg&DataRatesMayApply. For help, reply HELP. To end, reply STOP.

YES

BrandX: Welcome! You will receive 5 msg/mo. No purchase required. Msg&DataRatesMayApply. To end, reply STOP. For help, reply HELP. For more info, https://airsp.co/Oi9dy76d .
-->

### Keywords

You can add additional keywords to trigger an opt-in or opt-out. See: [SMS keywords](https://www.airship.com/docs/guides/messaging/features/sms-keywords/).

## Non-Mobile Single Opt-In

If users provide consent to receive text messages without a mobile-originated keyword — like through your website or app — you can register them through the API in a single step. Use the [`/api/channels/sms`](https://www.airship.com/docs/developer/rest-api/ua/operations/sms/#registersmschannel) endpoint with the date-time when the user `opted_in`.

> **Tip:** It may take up to an hour before you can message new users. If you want to message a new SMS user immediately, you can register new SMS users and send a message simultaneously using [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send).


```http
POST /api/channels/sms HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "msisdn" : "15035556789",
    "sender": "12345",
    "opted_in": "2018-02-13T11:58:59"
}
```


When registering your audience without a mobile keyword, it is your responsibility to obtain express written consent from users. If users have not provided sufficient consent, you should perform a double opt-in.

## Non-Mobile Double Opt-In

If users provide their phone numbers and express interest in SMS messages through your website or app but do not give sufficient consent to receive SMS messages from a particular sender, you can register them through the Airship API without an `opted_in` value.

When you register a user through the API without an `opted_in` value, Airship sends them a message prompting them to opt in. The user must then respond with a valid keyword to opt in to notifications.

> **Tip:** Airship generates a `channel_id` even when you register users who have not opted in. You can add tags to these channels and associate them with named users before audience members opt in.


```mermaid
sequenceDiagram
Participant Audience
Participant You
Participant Airship
Audience->> You: Registers via webform/app
You->> Airship: Register user through API
Airship->>Airship: Creates channel ID for audience
You-->> Airship: (Optional) add tags to new channel
Airship->> Audience: Sends opt-in request via SMS
Audience->> Airship: Texts opt-in keyword to Airship
note over Audience, Airship: Your audience/channel ID is opted in and can receive messages
```


When registering your audience without a mobile keyword, it is your responsibility to ensure that your users understand that they are agreeing to receive SMS messages from you and provide express written consent to receive SMS messages from you.

## Creating a One-Click Opt-In Link Using HTML

For mobile websites, you can set up a hyperlink or a button on a page that will open up the device's messaging app and prepopulate the long or short code and keyword for the SMS opt-in.

> **Note:** This feature will work on most mobile devices as well as a few desktop devices, but is not guaranteed to work on every mobile device model or operating system.


**HTML Hyperlink Template:**


```html
<a href="sms://CODE?&body=KEYWORD">Click Here to Opt-In</a>
```


**HTML Hyperlink Example:**


```html
<a href="sms://54321?&body=JOIN">Click Here to Opt-In</a>
```


## Update Opt-in Status {#update-sms-channel}

If your audience opts in to messaging outside of a standard opt-in flow — through your website or app — you can update the channel's `opted_in` value to add them to your messaging audience.

You can also update a channel to change its time zone and locale information.

> **Note:** You must know the `channel_id` to update a channel. You can look up a channel by `msisdn` and `sender` combination to find the channel identifier that you want to update.


**Update the `opted_in` value for a channel**

```http
PUT /api/channels/sms/{channel_id} HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "msisdn": "15035556789",
   "sender": "12345",
   "opted_in": "2018-02-13T11:58:59",
   "timezone": "America/Los_Angeles",
   "locale_country": "US",
"locale_language": "en"
}
```


## Opt out of SMS messages

If your audience opts out of messaging, you can mark the channel as opted-out (inactive) and they will not receive alerts even when they are addressed in the future. Use the [`/api/channels/sms/opt-out`](https://www.airship.com/docs/developer/rest-api/ua/operations/sms/#optoutsmschannel) endpoint and specify the `sender` and `msisdn`.

**Opt-out of SMS messages**

```http
POST /api/channels/sms/opt-out HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "sender": "12345",
   "msisdn": "15035556789"
}
```


## Automated Opt-In Interactions

You can define automated responses to opt-in keywords based on whether an `msisdn` is opting in for the first time or is currently opted in. [Contact Airship Support](https://support.airship.com/) to set up automated opt-in interactions. Examples:

* **First time opting in** — Send a welcome message: *"Thanks for joining BrandX! Here is your offer code...."*
* **Currently opted in** — Send a welcome message without an offer: *"Looks like you are already subscribed to BrandX."*

<!-- Postponed features:

You can set up several automated responses to opt-in keywords based on whether an `msisdn` is opting in for the first time, is already opted in, or has previously opted in within a certain time frame, as well as limit opt-in attempts. [Contact Airship Support](https://support.airship.com/) to set up automated opt-in interactions.

Opt-in Status - Send a message based on whether an `msisdn` is opting in for the first time or is currently opted-in:
* **First time opting in** - Send a welcome message - _"Thanks for joining BrandX! Here is your offer code..."_
* **Currently opted in** - Send a message without an offer - _"Looks like you are already subscribed to BrandX"_

Previously Opted In** - Send a different message to a user who has previously opted out, based on their opt-out date, such as X number of days:
* **Before last opt-out date** - If opted-out prior to the last 60 days, send an opt-in message with an offer.
* **Within last opt-out date** - If opted-out within the last 60 days, send an opt-in message without offer, or a rejection message.

Limit Opt-In Attempts - Limit the number of attempts to confirm a double opt-in and send a different message based on the number of attempts:
* **Within opt-in attempt limit** - Send a confirmation request message - _"Sorry, we did not recognize the response, to confirm your opt-in, please reply Y or YES."_
* **Exceeded opt-in attempt limit** - Send a limit reached message - _"We were unable to confirm your opt-in, to restart the opt-in process, text JOIN to 12345."_

-->
## Manually Triggered Keyword Interactions

You can trigger a keyword interaction on behalf of your audience, without receiving a mobile originated (MO) message, using the Airship API. You may want to do this to test your keywords or to trigger keyword interactions on behalf of your audience — including keywords that opt users in or out of your messaging audience.

For example, if a member of your audience requests to be removed from your messaging audience over the phone, you could use the following operation to opt them out. This triggers the mobile terminated message confirming that the user has been removed from your messaging audience.

**Trigger a "STOP" Keyword Interaction**

```http
POST /api/sms/15035556789/keywords HTTP/1.1
Content-Type: application/json
Authorization: Basic <master authorization string>

{
   "keyword" : "stop",
   "sender_ids" : [ "54321", "1234"]
}
```



<!-- /PAGE: Opt-In/Out Handling -->

<!-- PAGE: SMS Keyword Webhooks, PATH: https://www.airship.com/docs/developer/api-integrations/sms/inbound-message-handling/ -->

# SMS Keyword Webhooks

> Set up a webhook to process inbound SMS messages.You can set up SMS keywords in the Airship dashboard. See [SMS keywords
](https://www.airship.com/docs/guides/messaging/features/sms-keywords/). As an alternative, you can use webhooks for inbound message handling.

Airship can forward [Mobile-Originated Messages](https://www.airship.com/docs/reference/glossary/#mobile_originated) from your audience to your webhook so you can process requests from your audience and send custom, targeted responses to individual members of your audience based on the keywords they use in mobile originated messages.

You can use a webhook to respond to mobile-originated messages when either the keyword or the information you want to respond with are variable and defined outside of Airship. For example, if users text the defined keyword `balance` to your sender ID, you can use a webhook to process incoming messages and respond with each individual user's balance. If a user texts a variable keyword, like `order <#orderNumber>`, you can use a webhook to respond with the status of the specified order number.

Speak with your Airship account manager to determine the static or variable keywords that you want to route to your webhook.
<!-- this was already established in Getting Started? -->

Airship sends a payload to your webhook server at an `/inbound-sms` endpoint containing a `mobile_originated_id` that represents an individual MO message. You will use this ID and send a response using the `/sms/custom-response` API. Because you are responding to a message sent to you by a member of your audience, custom responses do not require users to opt in. However, the `mobile_originated_id` has a 10-minute lifespan; you have 10 minutes from the time a mobile-originated message is received to issue a response, after which the `mobile_originated_id` expires and you will be unable to respond to the inbound message.

```mermaid
sequenceDiagram
Audience->>Airship: Sends MO with Keyword
rect rgba(0, 179, 6, .2)
Airship->>Webhook: Forwards MO to Webhook
Webhook-->>Airship: Respond HTTP 200, process asynchronously
note over Airship, Webhook: Airship retries on 429/503 up to 4x
end
Webhook->>Airship: Issue custom response < 10 min
Airship->>Audience: Sends custom response
```


> **Note:** You can test your inbound webhook and trigger keyword interactions on behalf of your audience, without receiving a mobile originated message, using the Airship API. See the [Trigger Keyword Interaction](https://www.airship.com/docs/developer/rest-api/ua/operations/sms/#triggersmskeywordinteraction) endpoint for more information.


## SMS Webhook Requirements

Your webhook server must:

* Have a public URL. Airship server IPs regularly change and must be able to reach your webhook.
* Support an `/inbound-sms` (POST) endpoint to receive SMS inbound message payloads from Airship. Your webhook should immediately respond with HTTP `200 OK` and process responses asynchronously. Long-lived connections can cause performance problems on both systems.
* Support a `/validate` (GET) endpoint. You must respond to a validation request with the *Validation Code* issued when you set up your webhook in Airship.
* Issue responses (to Airship's `/sms/custom-response` endpoint) within 10 minutes of the `received_timestamp` in the `/inbound-sms` payload.
* Accept HTTPS connections. Airship uses TLSv1.2 with the following accepted cipher suites:
   * TLS_CHACHA20_POLY1305_SHA256
   * TLS_AES_256_GCM_SHA384
   * TLS_AES_128_GCM_SHA256
   * TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
   * TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
   * TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

**Additional Recommendations**

Your webhook server should accept up to 100 concurrent connections. Airship will establish concurrent connections with your webhook when concurrent incoming messages require processing.

### Retries

Airship will retry connections to your webhook when your webhook responds with **429** (Too Many Requests) or **503** (Service Unavailable) HTTP codes.

When Airship receives a retryable error, Airship will retry up to 4 times (5 total attempts) over 30 seconds. After the fourth retry (the fifth request), Airship will drop the request.

Airship **does not** retry on other 4xx or 5xx HTTP codes or HTTP timeouts; Airship's timeout duration is 10 seconds. Our approach to retries is designed to prevent your users from receiving duplicate messages.

## Registering your SMS Webhook

When you register a webhook in the Airship dashboard, Airship returns a *Validation Code*. You must set up your webhook to respond to GET requests to a `/validate` endpoint with a `confirmation_code` key containing this value before you enable the webhook in Airship.

1. Next to your project name, select the dropdown menu (▼), then **Settings**.
1. Under **Channels**, select **SMS Webhooks**.
1. Click **+ Configure New SMS Webhook**.
1. Enter a name for the webhook. This is just a friendly name to help you recognize your webhooks in Airship.
1. Enter the *Webhook URL*. This is the base URL of your webhook server. Your webhook server is expected to support `<base Url>/validate` and `<base URL>/inbound-sms` endpoints.
1. Select the *Authentication* mechanism for your webhook:
   * **Basic** — Enter the *Username* and *Password* that Airship will use to authenticate with your webhook server.
   * **Signature** — Enter the *Secret Key* that Airship will use as a part of an `X-UA-SIGNATURE` header to authenticate with your webhook server.
1. Click **Save**, and the page will update with a *validation code*.
   ![Validation code displayed after saving an SMS webhook](https://www.airship.com/docs/images/sms-webhook-validation_hu_7ecaa7c5aed17d91.webp)
   
   *Validation code displayed after saving an SMS webhook*
1. Configure your webhook to respond to GET requests to a `/validate` endpoint with a `confirmation_code` key containing the validation code value in a `200` response.
```http
GET <yourWebhookServer>/validate HTTP/1.1
Host: example.com
```

**Example response**

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
   "confirmation_code":"559384cd-6284-4e3e-9e4e-7c260019a251"
}
```

1. Select *Enabled*, then click **Update**.

When you enable the webhook, Airship issues a request to your webhook's `/validate` endpoint. If successful, your webhook will begin receiving requests at the `/inbound-sms` endpoint.

> **Note:** Before you disable a webhook, check with your Airship account manager to make sure that you aren't sending any keywords to the webhook.


## Accepting Inbound SMS Messages

Your webhook server must accept `POST` requests to an `<yourWebhookServer>/inbound-sms` endpoint. Each request contains a payload representing a mobile-originated message containing specific keyword or an unrecognized keyword (as set up through your Airship account manager).
```http
POST <yourWebhookServer>/inbound-sms HTTP/1.1
Host: example.com
Authorization: Basic <configured user:pass>
Content-Type: application/json

{
   "msisdn": "15035551234",
   "sender": "28444",
   "app_key": "YOUR_APP_KEY",
   "channel_id": "a828de17-b315-4e80-9d2d-35a906afeacf",
   "mobile_originated_message": "balance",
   "mobile_originated_id": "28883743-4868-4083-ab5d-77ac4542531a",
   "received_timestamp": "2019-04-29T12:00:01.492",
   "operator_timestamp": "2019-04-29T11:58:13.100"
}
```


* `msisdn` (string) – The [MSISDN](https://www.airship.com/docs/reference/glossary/#msisdn) of the audience member (mobile device) who sent the mobile-originated message.

* `sender` (string) – The [Sender ID](https://www.airship.com/docs/reference/glossary/#sender_id) that received the mobile-originated message. This is important if you have more than one sender.

* `app_key` (string) – The app key that the sender is configured for.

* `channel_id` (string) – (Optional) The channel ID associated with the MSISDN/sender. You can use this value to make opt-in, opt-out, or tag changes. If a channel does not exist for the MSISDN/sender and the keyword is not configured to create a channel if none exists, this field is absent.

* `mobile_originated_message` (string) – The contents of the mobile-originated message; this message consists of, or contains, a keyword.

* `mobile_originated_id` (string) – A unique ID for the message. Use this ID to respond to the mobile-originated message.

* `received_timestamp` (string) — An ISO 8601 UTC timestamp of the current time (the time of the webhook request). This represents the beginning of a 10-minute window to send a response to the `mobile_originated_id`.

* `operator_timestamp` (string) — An ISO 8601 UTC timestamp of when the mobile-originated message was originally sent, according to the carrier or aggregator.

> **Note:** Due to carrier maintenance and delays outside of Airship's control, mobile-originated messages can arrive at the webhook significantly after they are sent from the device (represented by the `operator_timestamp`). You may want to alter your messaging if a mobile-originated message is not received in a timely manner.


### Webhook Signature Hash Security {#signature-security}

<p>Rather than basic authentication, you can configure
a signature that your webhook server can use to verify that requests come from Airship. To enable this signature, select <strong>Signature Hash</strong> authorization and set a <code>secret_key</code> when configuring your webhook or open channel.</p>
<p>When you enable and set a <code>secret_key</code>, outgoing requests include a hash-based
authentication code computed using the sha256 hash function in an <code>X-UA-SIGNATURE</code> header. You can use this same algorithm to verify the signature
on the receiving server.</p>
<p><code>X-UA-SIGNATURE</code> is composed of the <code>secret_key</code> and a <code>message</code>, both of
which must be UTF-8 encoded. The <code>message</code> is a concatenation of the following
string values:</p>
<ul>
<li>The <code>X-UA-TIMESTAMP</code> header — the unix timestamp when the request was sent.</li>
<li>The <code>:</code> character.</li>
<li>The JSON request body.</li>
</ul>
<p>To prevent replay attacks, you should validate the <code>X-UA-TIMESTAMP</code> within a threshold of the current time. We recommend that you use a 5-minute threshold to account for time drift, though Airship uses NTP and we recommend that your webhook server does the same. To prevent timing attacks, you should employ a constant time-compare function when checking signatures.</p>
**Request headers with secret key**

```http
POST /yourWebhookServer/push HTTP/1.1
Content-Type: application/vnd.urbanairship+json; version=3
Content-encoding: gzip
X-UA-TIMESTAMP: 1536947409
X-UA-SIGNATURE: 68688b9dbd5c381851d3cd51dba3093c6633ceef58e6fee6ad4757f857f59aea
Data-Attribute: values
```

## Sending Custom Responses to Mobile-Originated Messages

You can issue custom SMS or MMS responses to mobile-originated messages using the `mobile_originated_id`. You have 10 minutes from the `received_timestamp` to respond to a mobile-originated message; the `mobile_originated_id` expires after 10 minutes.

The `/sms/custom-response` API uses Bearer Token authorization. You must create a token with the **All Access** role to send custom responses. See [Creating bearer tokens](https://www.airship.com/docs/guides/getting-started/developers/api-security/#creating-bearer-tokens) in *Airship API Security*.

```http
POST /api/sms/custom-response HTTP/1.1
Authorization: Bearer <bearer token>
X-UA-Appkey: <app key>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "sms" : {
      "alert": "Your balance is $12.34"
   },
   "mobile_originated_id" : "28883743-4868-4083-ab5d-77ac4542531a"
}
```


<!-- /PAGE: SMS Keyword Webhooks -->

<!-- PAGE: SMS Senders, PATH: https://www.airship.com/docs/developer/api-integrations/sms/senders/ -->

# SMS Senders

> {{< glossary_definition "sender_id" >}}## Sender types

There are various types of SMS senders, each with their own advantages and disadvantages.

Primary differences between sender types:

| Sender type | Description | Example | Communication | Best use | Provisioning time |
| --- | --- | --- | --- | --- | --- |
| **Short code** (Dedicated or Shared) | Numeric, 3-8 digits, typically 5-6 digits | 56582 | Two-way<sup>1</sup> | Notifications, alerts, marketing | Dedicated: Weeks to months<br>Shared: Days to weeks |
| **Long code** | Numeric, a standard phone number, 10 digits in most countries  | 15556059987 | Two-way and voice | Communication with one recipient at a time | Hours to weeks |
| **Alphanumeric code** |  Alphanumeric, 2-11 characters and can include spaces, also known as an "alpha" code | AIRSHIP, BrandName, PSA123 | One-way | Notifications, alerts, marketing | Days to weeks |

<sup>1. Support for two-way communication varies by country.</sup>

### Short codes

Short codes have several advantages that make them the superior sender type, including:

* Designed to send high volumes of messages at high throughput
* Short in length, making them easy for consumers to recall
* Capable of two-way messaging, so you can effectively manage opt-in and compliance workflows with keyword responses

However, they are the most expensive sender type and can take months to provision.

There are two short code types: dedicated and shared. In 2021, US mobile carriers discontinued approval for new shared short codes. Airship does not support shared short codes for outbound messaging.

Primary differences between short code types:

| | Dedicated short code | Shared short code |
| --- | --- | --- |
| **Operation** | Used by a single brand to communicate with consumers | Used by multiple brands to communicate with consumbers, where permitted |
| **Region support** | Available in all countries with SMS service | Not approved for use in all countries with SMS service |
| **Lease** | Must be leased from a service provider for a period of three, six, or 12 months | No lease requirement, but Airship may or may not have a shared short code available in your desired country |
| **Provisioning time** | Weeks to months | Days to weeks |

### Long codes

Long code advantages:

* Less expensive and shorter provisioning time than short codes
* Support both voice and text
* May be recognizable to consumers if otherwise associated with your business
* Capable of two-way messaging, so you can effectively manage opt-in and compliance workflows with keyword responses

They are generally used for lower volume, transactional messaging and at lower throughput than short codes or alpha codes.

Primary differences between long code types:

|  | Virtual number | 10-digit long code (10DLC) | Toll-free number (TFN) |
| --- | --- | --- | --- |
| **Format** | International standard or local number | US or CA standard or local number | Business number beginning with a recognizable prefix: 800, 888, 877, 866, 855, 844, or 833 |
| **Region support** | Available in most countries with SMS service | Available in US and Canada | Available in US and Canada |
| **Traffic** | Reserved for person-to-person (P2P) traffic, can be used for limited application-to-person (A2P) interactions | Reserved for A2P traffic | Reserved for A2P traffic |
| **Throughput** | Low: 1 MPS | Varies by carrier, use case and brand score, starts at 1 MPS |  Varies by use case, starts at 10 MPS |
| **Daily message limit** | Varies by country | Varies by carrier | Varies by carrier |
| **Provisioning time** | Days | Days to weeks, requires campaign registration  | Hours to days, requires sender verification | 

### Alpha codes

Alpha codes have become a common sender type for SMS marketers throughout the world, largely because of their advantages:

* Can be a brand name or other recognizable term
* Shorter provisioning time than short codes
* Lower in cost than dedicated short codes since they don't require leasing and may not require registration
* Capable of high volume messaging

However, they are a one-way sender, so cannot receive inbound SMS (mobile originating, or MO) messages. This can be a problem for brands required to maintain regulatory compliance with SMS keywords. The next section explains how to maintain keyword compliance when using alpha senders.

## Message forwarding

Brands may be required use a two-way sender in order to receive inbound (MO) messages so they can maintain regulatory compliance with SMS keywords. Maintaining compliance is not possible when using only a one-way sender, for example an [alpha sender](#alpha-codes).

The main compliance concerns are opting users out of commercial messaging and providing a way to contact the sender for more information. Example keywords for compliance: STOP, HELP, CONTACT.

You can maintain compliance by forwarding messages from a two-way sender to an alpha sender.

* **Inbound message handling** — Inbound messages (MO) are forwarded to whichever associated alpha sender sent the last outbound (MO) message to the corresponding MSISDN within the last 72 hours.

   If an alpha sender has not sent an outbound (MT) message to a MSISDN within the last 72 hours, the inbound (MO) message will not be forwarded, and the subscriber will receive a generic response telling them that their request cannot be processed.

<!-- Tony/team  will clarify later

   * **Opting in** — Users can opt in using the forwarding sender, but [Double Opt-In](https://www.airship.com/docs/reference/glossary/#double_opt_in) is required. Since forwarding senders require a previous outbound (MT) message from the alpha sender, the double opt-in process must be initiated with an initial outbound (MT) message from the alpha sender. The message must contain instruction for the user to send an opt-in keyword to the forwarding sender. For example: `Text SIGNUP to <forwarding sender ID>`. See [Opt-In/Out Handling](https://www.airship.com/docs/developer/api-integrations/sms/opt-in-out-handling/).

-->

   * **Multiple alpha senders** — You can use a single forwarding sender for multiple alpha senders. Inbound message forward to the alpha sender that last sent an outbound (mobile terminated, or MT) message to the recipient [MSISDN](https://www.airship.com/docs/reference/glossary/#msisdn). This behavior is significant when using the same forwarding sender for multiple projects or using a shared short code as a forwarding sender.

* **Keyword responses and actions** — The alpha sender handles all keyword processing of requests and actions, such as triggering a text response, opting in a user, or applying a tag for segmentation. Keyword responses are also sent from the alpha sender, as if it had received the inbound (MO) message without forwarding. See [SMS Keywords](https://www.airship.com/docs/guides/messaging/features/sms-keywords/).

Any sender capable of receiving inbound (MO) messages can be configured as a forwarding sender. Forwarding senders operate in the same country of origin as the alpha sender.

See also [SMS Compliance](https://www.airship.com/docs/developer/api-integrations/sms/compliance/).

### Setting up message forwarding

Airship configures forwarding senders for your project, however the forwarding sender cannot be configured to handle any keywords. Remove keywords for that sender before making your request. See [SMS Keywords](https://www.airship.com/docs/guides/messaging/features/sms-keywords/).

[Contact Support](https://support.airship.com/) or your account manager with your request and include these identifiers:

| Identifier | Description | Where to find it in your Airship project |
| --- | --- | --- |
| **Project app key** | The identifier for the project you want enabled for forwarding SMS messages | Go to **Settings** and copy the app key from the sidebar. |
| **Forwarding sender** | The sender ID for the two-way sender that should forward messages to your alpha code | See instructions that follow this table. If you do not have a two-way sender to use as your forwarding sender, instead request that Airship provision one for you. |
| **Alpha sender** | The sender ID for the alpha code that should receive the forwarded messages | See instructions that follow this table. If you do not have an alpha code, instead request that Airship provision one for you. |

If you do not know what senders are already configured for your project, you can find them in the Airship dashboard:

1. Go to **Messages**, then **SMS Keywords**.
1. Select **+ Create new keyword**.
1. Select **Settings**, then the **SMS Sender** menu. You will see all the long codes and short codes for your project. Each sender in the list is formatted as a 2-character country code followed by the actual long or short code. 
1. Note the long and short codes, then leave the page without saving a new keyword.

If you need forwarding senders for multiple projects, you may want to make a separate request per project for easier tracking.

---

Support or your account manager will tell you when configuration is complete and you can start including the forwarding sender ID in your SMS messages.

### Setting up keywords

Outbound messages should include instructions explaining how your SMS subscribers can respond. For example, you might include `Text STOP to <forwarding sender ID> to opt out`. See [SMS Keywords](https://www.airship.com/docs/guides/messaging/features/sms-keywords/) to set up keywords for your alpha sender.



<!-- /PAGE: SMS Senders -->

<!-- PAGE: RCS branded senders, PATH: https://www.airship.com/docs/developer/api-integrations/sms/rcs/ -->

# RCS branded senders

> Set up an RCS branded sender to send branded, professional messages that recipients recognize and trust.## What is RCS and why use a branded sender?

Rich Communication Services (RCS) is an advanced messaging protocol that enables interactive, media-rich communications. RCS messages automatically fall back to SMS/MMS when not supported.

Using an RCS branded sender solves a key problem with traditional text messaging: recipients often don't know who's contacting them, leading to lower engagement and higher opt-out rates. Instead of messages appearing from an unfamiliar phone number, RCS displays your business name, logo, custom color, and a Verified badge with every message.

![RCS branded messaging provides immediate sender recognition compared to SMS](https://www.airship.com/docs/images/rcs-branded-sender_hu_9a5a5d880eb1d0cb.webp)

*RCS branded messaging provides immediate sender recognition compared to SMS*

With an RCS branded sender, you get the following:

* **A branded identity that builds trust** — Recipients immediately recognize who's contacting them, which typically results in higher open and response rates. The verified badge confirms your business identity has been authenticated, reducing concerns about spam or fraudulent messages.

* **Better engagement insights** — RCS provides read receipts that show when recipients have seen your messages, giving you visibility into message performance that standard SMS delivery reports can't provide. This helps you understand actual engagement, not just delivery.

* **A seamless user experience** — RCS works within the same messaging apps people already use on their phones — no downloads, new accounts, or app switching required.

* **More effective communication** — RCS is particularly useful for messages where recognition and trust matter most:
   * Appointment reminders and confirmations
   * Delivery and shipping notifications  
   * Account alerts and updates
   * Customer service communications

   These types of messages see the biggest improvement in engagement when recipients can immediately identify the sender as a legitimate business rather than wondering about an unknown number.

## How RCS works with Airship

Because RCS is not supported by all devices and carriers, we pair your RCS branded sender with an [SMS sender](https://www.airship.com/docs/developer/api-integrations/sms/senders/) to handle fallback.

* **Automatic routing** — When you send a message, Airship determines if the recipient can receive RCS.
* **RCS delivery** — If RCS is available, your message displays with full branding.
* **SMS fallback** — If RCS isn't available, the message sends as SMS/MMS instead.
* **No workflow changes** — You create and send messages exactly as you do now.

**The paired sender setup:**
* Your RCS branded sender handles the branded messaging experience.
* Your SMS sender handles fallback delivery.
* Keywords configured for your SMS sender also apply to the RCS branded sender.
* Airship manages the routing between them automatically.

### RCS event reporting

An RCS read report event occurs when an RCS message is read. See [RCS read report](https://www.airship.com/docs/developer/rest-api/connect/schemas/custom-sms-events/#rcs-read-report) in the Custom Events information in the [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds) API reference.

You can also access information about RCS reads in [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa). The Message Delivery field includes the Dimension **SMS Deliveries — Is RCS (Yes / No)** and the Measure **RCS Read Count**. See [SMS in Performance Analytics](https://www.airship.com/docs/guides/reports/analytics/sms/).

### Availability and support

RCS is available to US data center-hosted customers. RCS capability varies per carrier.

**Device support:**
* iOS 18.1 and later
* Android devices with RCS-capable messaging clients

## Setting up an RCS branded sender

To get started, contact your Airship account manager or [contact Support](https://support.airship.com/) and request adding RCS to your plan.

Airship will:

1. Help you register an RCS branded sender
1. Pair your RCS branded sender with a new or existing [SMS sender](https://www.airship.com/docs/developer/api-integrations/sms/senders/), which can be a short code, long code, or toll‑free number
1. Confirm when RCS routing and fallback are enabled for your account

Once enabled, your messages will automatically display with RCS branding when available and fall back to SMS/MMS when not.

## Related documentation

See the following for information about setting up and using SMS with Airship:

* [Getting started](https://www.airship.com/docs/developer/api-integrations/sms/getting-started/) for the SMS platform
* [SMS/MMS/RCS content](https://www.airship.com/docs/guides/messaging/messages/content/sms/)
* [SMS keywords](https://www.airship.com/docs/guides/messaging/features/sms-keywords/) and opt‑in handling
* [SMS compliance](https://www.airship.com/docs/developer/api-integrations/sms/compliance/)


<!-- /PAGE: RCS branded senders -->

<!-- PAGE: Link Shortening, PATH: https://www.airship.com/docs/developer/api-integrations/sms/link-shortening/ -->

# Link Shortening

> Use shortened links and tag actions in your SMS messages.Airship can shorten links in your SMS messages, saving valuable characters for your message and helping you track engagement with your SMS messages. When you enable link shortening, Airship replaces your URL with unique, shortened URLs for each member of your audience.

Shortened URLs:

* Reduce the total number of characters in your messages — Shortened links using the default `airsp.co` and `airsp.eu` domains consume exactly 25 characters.

* Track engagement with SMS messages — Airship generates `short_link_click` events in the [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds) (RTDS), and generates engagement reports based on short-link usage to help you track the effectiveness of your messages and engagement down to individual audience members.

* Support adding or removing tags from your audience when they tap or click a link by adding query parameters to your URL — `?ua-tag-add=tag_group:tag` or `?ua-tag-remove=tag_group:tag`.

* Expire 60 days after they are sent.

For Airship to recognize and shorten your links, your URLs must:

* Begin with `http://` or `https://`.
* Begin and end with a space. Your URL cannot contain beginning or trailing punctuation or space characters; spaces determine the beginning and end of the URL.

You can use custom domains for your shorten links, e.g., `mysite.co`, or use the default `airsp.co` or `airsp.eu` domains. [Contact Airship Support](https://support.airship.com/) if you want to use a custom domain for shortened links. To support a custom domain, [you must configure your web server appropriately](https://www.airship.com/docs/developer/api-integrations/sms/custom-short-link/).

> **Note:** You may not want to use shortened links for static, easily recognizable URLs, e.g, links to your terms and conditions. If you want to use a persistent shortened link like `https://example.com/help`, you must provide the URL yourself. You can enable or disable link shortening whenever you send a message using the Airship dashboard.


## Using Shortened Links

In the dashboard, you enable link shortening in the *Content* step in a composer:
   ![Link shortening option in the SMS composer](https://www.airship.com/docs/images/shorten-links-sms_hu_e05d5bddfea0bcd8.webp)
   
   *Link shortening option in the SMS composer*

You can also set your project to automatically shorten links in all messages created using the dashboard:

1. Next to your project name, select the dropdown menu (▼), then **Settings**.
1. Under **Project settings**, select **Dashboard Settings**.
1. Enable **SMS Link Shortening**.

> **Note:** Your project's link shortening setting does not affect operations in the API.


Using the API, add `"shorten_links": true` to your payload. See the [SMS Object](https://www.airship.com/docs/developer/rest-api/ua/schemas/platform-overrides/#smsoverrideobject) for more information.

```http
POST /api/templates/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
   "named_user": "user"
   },
   "notification": {
   "sms": {
      "alert": "An alert with a link for SMS users https://www.example.com/long_url?ua-tag-add=my_tag_group:cool_tag",
      "expiry": 172800,
      "shorten_links": true
   }
   },
   "device_types": [ "sms" ]
}
```


## Tag Actions with Shortened Links {#tag-actions}

You can add or remove tags from users who engage with Airship-shortened links in your SMS messages. Shortened links with tag actions are the same length as URLs without. You can also use tag change events to kick off automation rules or sequences, making it easier to integrate SMS messaging campaigns into your larger messaging strategy. You can perform up to 100 total tag actions (add and remove) per SMS message.

In the dashboard, a **Set tags** button appears when you add a URL in your SMS text (or SMS fallback text) and enable link shortening. Tag actions add query parameters to your URL, but users will still see the shortened URL in your SMS messages.

Using the API, you add query parameters to your URLs:

* Add a tag: `?ua-tag-add=my_tag_group:tag_to_add`
* Remove a tag: `?ua-tag-remove=my_tag_group:tag_to_remove`

The following payload is a simple example in which Airship would apply the `blazers` tag and remove the `no_preference` tag in the `fav_team` tag group for anybody who engages with the link.

**Add and Remove a tag in an SMS Notification**

```http
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
      "AND": [
         {
            "tag": "basketball",
            "group": "interests"
         },
         {
            "tag": "portland",
            "group" "metro_area"
         }
      ]
   },
   "notification": {
      "sms": {
         "alert": "Vote for the Blazers as your favorite team! https://www.example.com/long_url?ua-tag-add=fav_team:blazers&ua-tag-remove=fav_team:no_preference",
         "expiry": 172800,
         "shorten_links": true
      }
   },
   "device_types": [ "sms" ]
}
```



<!-- /PAGE: Link Shortening -->

<!-- PAGE: Custom Domains for Short Links, PATH: https://www.airship.com/docs/developer/api-integrations/sms/custom-short-link/ -->

# Custom Domains for Short Links

> Take advantage of your highly-recognizable brand and increase conversions while saving characters in SMS messages using Airship-shortened links with a custom domain.You can replace Airship's standard `airsp.co` or `airsp.eu` domains for shortened links with your own **custom short link domain**. To take advantage of a shortened, custom domain, you must:

1. Register your short domain name with a Domain Name Registrar. Your custom short link domain can include a subdomain, but it cannot include a path.

   * **Supported**: `https://my.site.co`
   * **Not Supported**: `https://mysite.co/path`

   The links that you use in your messages can, of course, contain paths.
1. Host your domain. Airship supports custom short link domains using HTTP and HTTPS.

1. Implement a redirect configuration applicable to the web server you use. This document contains instructions for a few common web servers.
   * [nginx server configuration](#nginx)
   * [Apache server configuration](#apache)
   * [Microsoft IIS configuration](#microsoft-iis)
> **Note:** Sample configurations on this page may differ from your actual setup.

1. [Contact Airship Support](https://support.airship.com/) to enable your custom short link domain.

When you send an SMS/MMS message from Airship with link shortening enabled:

* Your end users will receive a shortened link, e.g., `http://mysite.co/abcd1234`.
* Your domain must forward `http://mysite.co/abcd1234` to `https://airsp.co/abcd1234` or `https://airsp.eu/abcd1234` (depending on your Airship data center).
* Airship will handle the final redirect to the full URL that you provided in your original message, e.g., `http://myfullsite.example.com/longURL?query=1234`.

```mermaid
sequenceDiagram
Airship->>Audience: Send SMS with shortened link
Audience ->>Custom Domain: Clicks custom link
Custom Domain ->> Airship: Forwards custom domain to airsp.com or .eu with request_uri
Airship ->> Airship: Resolves short link to original URL
```


## Nginx Server Configuration {#nginx}

Use one of the following configurations to redirect your custom short link domain to Airship. The `request_uri` appended to your custom short link domain — e.g., `https://mysite.co/abcd1234` — passes through to Airship's short link domain — e.g., `https://airsp.co/abcd1234`. Airship then resolves the shortened link, redirecting the user to the original link in your message — e.g., `https://myfullsite.example.com/deals?cart=4321id=0987lkjh`.

**HTTP-only redirect:**

```nginx
server {
    listen 80;
    
    location / {
      return 303 https://airsp.co$request_uri;
    }
}
```


**HTTP and HTTPS redirect:**
 
```nginx
server {
	listen 80;
	    
    location / {
        return 303 https://airsp.co$request_uri;
    }
}

server {
	listen 443 ssl;
	ssl on;
	ssl_certificate 	/etc/nginx/ssl-certs/airsp.crt;
	ssl_certificate	/etc/nginx/ssl-certs/airsp.key;

	location / {
		return 303 https://airsp.co$request_uri;
	}
}
```


## Apache Server Configuration {#apache}

Use one of the following configurations to redirect your custom short link domain to Airship. The `request_uri` appended to your custom short link domain — e.g., `https://mysite.co/abcd1234` — passes through to Airship's short link domain — e.g., `https://airsp.co/abcd1234`. Airship then resolves the shortened link, redirecting the user to the original link in your message — e.g., `https://myfullsite.example.com/deals?cart=4321id=0987lkjh`.

**HTTP-only redirect:**

If the `mod_rewrite` module is enabled, add the following lines to your `sites-available/000-default.conf` file.

```apacheconf
<VirtualHost *:80>
	... other .conf code...
	<Location />
		Redirect 303 https://airsp.co%{REQUEST_URI}
	<Location>
</VirtualHost>
```


**HTTP and HTTPS redirect:**
 
In your `sites-available/default-ssl.conf` file, add a `Location` directive block containing the following:

```apacheconf
<VirtualHost _default_:443>
  ... other .conf code...
  <Location />
      Redirect 303 https://airsp.co%{REQUEST_URI}
  </Location>
</VirtualHost>
```


In your `sites-available/000-default.conf` file add the following two lines. This assumes that the `mod_rewrite` module is enabled for your server.

```apacheconf
<VirtualHost *:80>
	... other .conf code...
	<Location />
		Redirect 303 https://airsp.co%{REQUEST_URI}
	<Location>
</VirtualHost>
```


## Microsoft IIS Configuration {#microsoft-iis}

Use the following configuration to redirect your custom short link domain to Airship. The `request_uri` appended to your custom short link domain — e.g., `https://mysite.co/abcd1234` — passes through to Airship's short link domain — e.g., `https://airsp.co/abcd1234`. Airship then resolves the shortened link, redirecting the user to the original link in your message — e.g., `https://myfullsite.example.com/deals?cart=4321id=0987lkjh`.

1. Click **Default Web Site**.
1. In the *Feature View*, click **URL Rewrite**.
1. In the *Actions* panel, click **Add rules…**.
1. In the *Add Rules* dialog, select **Blank Rule** and click **OK**.
1. When defining the *Rewrite Rule*, set the following:
    * **Requested URL**: `Matches the Pattern`
    * **Using**: `Regular Expressions`
    * **Pattern**: `[^/]*$`, which matches the request URI through the end of the regex string
    * **Ignore Case**: unchecked 
    * **Action Type**: **Redirect**
    * **Redirect URL**: `https://airsp.co/{R:0}` where `{R:0}` specifies the request URI
    * **Append query string**: unchecked
    * **Redirect type**: **See Other (303)**

<!-- /PAGE: Custom Domains for Short Links -->

<!-- PAGE: Segmentation, PATH: https://www.airship.com/docs/developer/api-integrations/sms/segmentation/ -->

# Segmentation

> Target SMS devices based on tags, named users, test groups, and audience lists.Target SMS devices as you would any other supported channel, using [audience selectors](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/#audienceselector1000).

## Tags

When setting tags on an SMS channel, use the [Channel Tags](https://www.airship.com/docs/developer/rest-api/ua/operations/tags/#modifychanneltags) endpoint.

In the provided examples, we will first add a new tag to our SMS channel using tag groups, then send
a push to an audience defined by channels containing the new tag with the device type `sms`.

**Example Request: Add tag to SMS channel using tag groups**


```http
POST /api/channels/tags HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
      "channel": "34b3dfc1-d717-40fe-89e8-10584ed1c123"
   },
   "add": {
      "fish_numbers": [
         "one",
         "two"
      ],
      "fish_colors": [
         "red",
         "blue"
      ]
   }
}
```


**Example Request: Send to SMS using your new tag**


```http
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
      "tag": "blue",
      "group": "fish_colors"
   },
   "notification": {
      "alert": "This one has a little star."
   },
   "device_types": [
      "sms"
   ]
}
```


## Named Users

Named Users let you associate an ID of your choosing with a single user who is opted in across
multiple engagement channels. Typically a Named User ID is an internal identifier in your
CRM system.

Associate Named Users with individual SMS channels using the [Named Users API](#api-named-users).

In the provided examples, we take our new channel and associate it with a named user,
then use the Push API to deliver the SMS alert.

**Example Request: Associate Named User with SMS channel**


```http
POST /api/named_users/associate HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "channel_id": "adc9465c-68d6-481e-b5b4-6ab5a185b35f",
   "named_user_id": "erika_mustermann"
}
```


**Example Request: Send to SMS using your new tag**


```http
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
      "named_user": "erika_mustermann"
   },
   "notification": {
      "alert": "Test SMS to Named User"
   },
   "device_types": [
      "sms"
   ]
}
```


## Test Groups

Make testing easy by creating Test Groups for use in the Message Composer. Add your SMS
channels for testing in the [Test Group UI](https://www.airship.com/docs/guides/audience/preview-test-groups/).

## Audience Lists

Upload lists of Named Users or SMS channels via the [Static Lists API](https://www.airship.com/docs/developer/rest-api/ua/operations/static-lists/) or in the [dashboard](https://www.airship.com/docs/guides/audience/segmentation/audience-lists/uploaded/) and use those for targeting through the Push API or Message Composer.



<!-- /PAGE: Segmentation -->

<!-- PAGE: Analytics and Reporting, PATH: https://www.airship.com/docs/developer/api-integrations/sms/analytics-and-reporting/ -->

# Analytics and Reporting

> Airship provides reporting on messages sent.Sends from Airship systems are counted per message. Reporting on sends is available in:

* [Message reports](https://www.airship.com/docs/guides/reports/message/)
* [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds)
* [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa)

Opt in/out events are shown in the
[Devices report](https://www.airship.com/docs/guides/reports/engagement/#devices) and message reports.  Message reports also include delivery events and errors.


<!-- /PAGE: Analytics and Reporting -->

<!-- PAGE: SMS Delivery Report Error Codes, PATH: https://www.airship.com/docs/developer/api-integrations/sms/sms-error-codes/ -->

# SMS Delivery Report Error Codes

> Delivery reports track the status of SMS messages from Airship's third-party providers to your audience and may contain an `error_code` to describe why your message was not delivered.Airship's standard error codes for the most common errors encountered:

| Error code | Description |
| --- | ---- |
| 0   | Unknown error |
| 10  | Landline or unreachable carrier |
| 16  | Message blocked |
| 61  | Message filtered |
| 64  | Error, blocked due to exceeded quota |
| 150 | Unknown destination handset |
| 152 | Numeric Sender ID Not Provisioned on Carrier |
| 300 | Unreachable destination handset |

Some codes aren't necessarily errors and indicate that a message has not yet been delivered, most notably `400` (queued) and `401` (dispatched).

The following example shows one of many `error_code` values relevant to SMS delivery report events:

**Example SMS Delivery Report**

```json
{
  "body": {
    "interaction_type": "delivery_report",
    "name": "dispatched",
    "properties": {
      "error_code": "401",
      "sender": 18587323362,
      "vendor": "CLX",
      "vendorDeliveryId": "ZLOiTjmZfV6r0-Eo"
    },
    "source": "API",
    "triggering_push": {
      "push_id": "7764f7bd-a206-4219-9933-a9bcb7dc9979"
    }
  },
  "device": {
    "channel": "73c29b53-a00a-4567-9ccd-1d726013699d",
    "delivery_address": "19712754475",
    "device_type": "SMS",
    "identifiers": {
      "sender": "18587323362"
    }
  },
  "id": "0f7d521f-dc6c-4530-9623-91fb8d370db5",
  "occurred": "2020-06-01T18:26:12.575Z",
  "offset": "1000032182771",
  "processed": "2020-06-01T18:26:13.558Z",
  "type": "CUSTOM"
}
```


In addition to these common errors, other errors might be returned, depending on your delivery service provider, Sinch or Twilio. Review the following sections relevant to your service provider to determine the meanings of error codes.

## Sinch (CLX) Error Codes

Sinch was formerly known as CLX. For all `error_code` values that apply when a delivery report's `vendor` property is `CLX`, see [Message Error Specification](https://developers.sinch.com/docs/sms/other/sms-other-http-basic/#message-error-specification) in Sinch's *HTTP Basic for SMS* documentation.

### Sinch (CLX) MMS Result/Error Codes

The following `error_code` and `report_code` values are most common and relevant for MMS messages when a delivery report's `vendor` property is `CLX`:

| Error or report code | Description |
| --- | --- |
| N101 | Message Sent |
| N102 | Message Sent/Delivered |
| E101 | Message Failed |
| E102 | Message Sent/Expired, Sent/Rejected, Sent/Failed or, Sent/Not Supported |

For all Sinch MMS error codes, see [](https://developers.sinch.com/docs/mms/xml-service/appendix/) in Sinch's *XML Service Appendix*.

## Twilio Error Codes

For `error_code` values that apply when a delivery report's `vendor` property is `TWILIO`, see Twilio's [Error and Warning Dictionary](https://www.twilio.com/docs/api/errors).


<!-- /PAGE: SMS Delivery Report Error Codes -->

<!-- PAGE: SMS Compliance, PATH: https://www.airship.com/docs/developer/api-integrations/sms/compliance/ -->

# SMS Compliance

> Airship supports SMS notifications best practices.> **Important:** Please note that this content is provided for information purposes only and is not intended to be nor should be relied on as legal or compliance advice.
> 
> Different locations may have varying legal and privacy requirements for SMS/MMS/RCS notifications, so please verify with your legal or regulatory compliance team that your SMS/MMS/RCS usage, proposed use cases, and messaging configuration are compliant with applicable local laws and regulations.


The Airship Service provides customers with a platform for building successful SMS marketing programs by supporting compliance with laws and industry best practices as summarized in this document. These guidelines represent our current understanding of common compliance requirements generally applicable to Airship and our customers and do not constitute legal advice.

## Some Background on SMS Regulation

Meeting regulatory requirements and maintaining best practices to support customer relationships are critical for brands that use SMS in their marketing strategy. Regulations such as the US Telephone Consumer Protection Act of 1991 (TCPA), the Canadian Anti-Spam Law (CASL), the General Data Protection Regulation (GDPR), the Directive on Privacy and Electronic Communications (the EU's ePrivacy Directive), and a variety of local US state laws and individual EU countries' regulations include strict requirements for sending SMS marketing messages.

In addition to country- and state-specific laws and regulations that govern SMS messaging, wireless industry groups publish best practice guidelines for companies engaged in SMS marketing. These include key standards from the wireless industry association CTIA:

* [CTIA Messaging Principles and Best Practices](https://api.ctia.org/wp-content/uploads/2019/07/190719-CTIA-Messaging-Principles-and-Best-Practices-FINAL.pdf)
* [CTIA Short Code Monitoring Handbook](https://api.ctia.org/wp-content/uploads/2024/01/CTIA-Short-Code-Monitoring-Handbook-v1.9-FINAL.pdf)

Certain telecommunications providers may also have their own Code of Conduct to govern traffic through their services, such as T-Mobile's Code of Conduct and Mobile Marketing Association's [Consumer Best Practices for Messaging](https://www.mmaglobal.com/files/bestpractices.pdf).


## General Requirements

You must obtain consent and provide disclosure.

### Prior Express Written Consent

TCPA in the US, and other applicable laws around the world, a business must provide clear and conspicuous information about its practices and get the recipient's express written consent to receive text messages before sending an automated message. Brands should never send messages to opt-in lists that have been shared or sold. Also, brands should check for the legal age of consent and the types of disclosures required based on their use case and where the recipient is located. In addition, brands should verify their use cases and numbers against local Do Not Call (DNC) registries to ensure no other restrictions may apply. Because considerations regarding DNC registries are highly specific to each use case, Airship cannot apply number filtering or automated channel uninstall for mobile numbers that appear on a DNC, in the US or any other known DNC.

### Clear and Conspicuous Disclosure

Brands must be clear, concise and upfront in the call to action that prompts the consumer to opt in to receive SMS messages:

   * Identify the business to whom consent is being provided
   * Identify the consumer's phone number
   * Include a description of the recurring text messaging program and types of messages the consumer will receive (e.g., account alerts, news alerts, promotional alerts, coupons, reminders, etc.)
   * Disclose that texts will be sent using automated technology
   * Disclose that the consumer is not required to provide consent as a condition of a purchase
   * Disclose specific message frequency or that "message frequency varies"
   * Disclose that message and data rates may apply
   * Provide Customer Care and Opt-Out instructions
   * Provide links to applicable Terms of Use and Privacy Policy. 
   * Terms of Use should include a section that details the SMS program, including program description and opt-in, opt-out, and help information
   * Privacy Policy must explicitly state that mobile opt-in data will not be shared or sold  

   **Example of a call to action (e.g., on a website, store display, etc.)**

   ```text
Text JOIN to 22255 to receive recurring autodialed
   offers and information from {BRAND NAME} Terms and
   Privacy Policy at [brand.example.com/sms-terms]. Message
   frequency varies with use. No purchase required.
   Reply HELP for help, STOP to end, Msg&data rates
   may apply.
```


### Canada (CWTA) — Link Disclosure Requirement

For SMS programs operating in Canada under Canadian Wireless Telecommunications Association (CWTA) guidance, if a message contains a clickable link, include the disclosure "Std msg & data rates may apply." in that message. This requirement helps satisfy carrier and CWTA expectations for clear consumer disclosures related to messages that drive to the web. Apply this disclosure alongside existing HELP/STOP language as appropriate.

### Written Consent (Opt-In)

Brands may obtain digital consent via text message, email, website form, voice recording, etc. with the
following requirements:

   * Cannot use a pre-checked box
   * Cannot require consent to receive SMS messages as a condition of sale 
   * Should keep records of consent for at least four years (the statute of limitation for TCPA claims is four years)
   * Double opt-in, while not strictly required, is supported and recommended by Airship as a best practice
   * With single or double opt-in, the first text message should be a compliance message confirming opt-in and reiterating important information:
      * Identifying the brand
      * Message frequency, if not already provided
      * What types of messages
      * Message and data rates may apply
      * Customer Care and Opt-Out instructions
      * Provide links to terms and privacy policy, if not already provided
      
      Some jurisdictions may have additional consent requirements, including requirements around obtaining express written consent, which may need to include the consumer's phone number, express authorization to receive the message, and other notifications. Brands should check with their legal or regulatory compliance teams for the types of disclosures required based on their use case and where the recipient is located. 


   **Example of confirmation message**

   ```text
{BRAND NAME}: You've subscribed to receive recurring
   promotional msgs. Reply HELP for help, STOP to end.
   Msg&data rates may apply.
```


### Time of Day Guidelines

Brands should schedule their SMS notifications to account for carrier delivery delays, especially in locations with time of day requirements, including those required under TCPA and local state laws, which may be more restrictive. 

The TCPA prohibits telephone solicitation (including text messages) before 8 AM and after 9 PM in the recipient's time zone. A best practice is to send SMS notifications between 9 AM and 8 PM in the recipient's time zone. Local restrictions may be more stringent than the 8 AM to 9 PM TCPA standard. Brands should confirm time of day requirements for each location of operation. If brands have recipients in different time zones, then multiple time zones should be taken into consideration. 

In addition, if brands are targeting large audiences, scheduling further in advance of the prohibited period is advisable. Otherwise, the volume of messages may cause additional delivery delays.

### Customer Care and Opt-Out Instructions

SMS programs should promote customer care contact and opt-out instructions in initial SMS program disclosures and then with every recurring message or at least once per month.

   ```text
Reply HELP for help, STOP to end
```


### Special Considerations for Transactional SMS

SMS cannot be the only method for transactional messaging. Mobile carriers require an alternative method such as email or a phone call. An example of a common transactional SMS message is a one-time password.

## State-Specific Requirements

Some US states have "mini-TCPA" or similar telemarketing laws that differ from federal requirements. Variations may include:

- Consent standards for automated sales texts
- Restricted contact hours based on recipients' local time
- Frequency or attempt limits within a defined period
- Pre-suit cure requirements, such as STOP and grace periods, and private rights of action
- Content and identification expectations, such as disclosures and return-call capabilities
- Registration, record keeping, and other program obligations
- Presumptions tied to area codes or residency
- Requirements to regularly include a callback-capable phone number in outbound messages

Recommended approach:

- Consult counsel to determine which state rules apply to your audience and use cases.
- Configure opt-in flows and unsubscribe handling
- Schedule sends to comply with the most restrictive applicable sending hours.
- Maintain auditable consent and suppression records, and monitor state-level changes.

Because state requirements evolve, verify current obligations and enforcement trends before launching campaigns. Airship does not enforce state-by-state rules automatically. Brands are responsible for the appropriate configuration and scheduling.

## Opt-In Methods

Airship SMS supports two opt-in methods. Based on local regulatory requirements, additional consents may be needed as described above. Brands should check with their legal or regulatory compliance teams for the types of disclosures required based on their use case and where the recipient is located to complement the Airship Service configuration. 

### Mobile-Originated Opt-In

In response to a call to action from the brand, a consumer texts `JOIN` from their mobile device or responds through another form — i.e., a website, app, or any means other than sending a text with an opt-in keyword. This triggers the Airship SMS channel to send a double opt-in request (example message below, customizable for your brand):

```text
{BRAND NAME}: Reply Y to agree to receive recurring
autodialed {type of messages/alerts} and to our Terms
of Service [insert TOS hyperlink] and Privacy Policy
[insert PP hyperlink]. No purchase rqd. Message
frequency varies. Reply HELP for help, STOP to end.
Msg&data rates may apply.
```


In the Airship SMS channel, the consumer will not get added to the opt-in list until they reply with the keyword `Y`. Once added to the list, Airship SMS sends an automatic confirmation alert:

```text
{BRAND NAME}: You've subscribed to receive
recurring {type of messages/alerts}. Message
frequency varies. Reply HELP for help, STOP
to end. Msg&data rates may apply.
```


### Brand-Managed Opt-In

Opt-in owned by the brand and uploaded to Airship SMS via API or CSV file
: The consumer uses the brand's website, app, paper form or other means to opt in to receiving SMS messages. The phone number and opt-in date/ time are then passed to Airship by the brand via the Airship API or uploaded via the Airship platform, and Airship SMS tracks the opt-in date/time in our database along with the phone number.

   If the number is not already in the Airship opt-in database for that brand, the number is automatically added to that opt-in database. If uploading via CSV, any number on the uploaded list that does not include an opt-in date/time is not added to the opt-in database and no message is sent to that number.
   
   Brands must make sure that the call to action for the opt-in clearly provides all necessary information under applicable law and that the consent meets applicable legal requirements.

Transactional messages
: Transactional messages are messages that are directly related to the service being provided, such as delivery updates for a package or appointment reminders. Once the consumer provides the brand with legally appropriate consent to receive transactional messages, the brand triggers the sending of the transactional message by providing the phone number and opt-in date to Airship SMS via our API as described above.

   It is important to note that consent to receive a transactional SMS notification cannot be used for sending any marketing SMS messages. Each opt-in database for a brand will have the same scope of messages, such as promotional alerts or account update alerts.

   A separate code will be required to add another type of campaign. Brands should make sure that written consents from legacy or existing customers include all legally required elements of a consent, and if in doubt, obtain new consents from existing consumers covering any missing requirements.

## Opt-Out Methods

Under the TCPA in the US, and other applicable laws around the world, a consumer may revoke consent through any reasonable method, including verbal communication or, in the context of text messaging with keyword such as `STOP`. The brand should confirm that it is able to process requests received (1) via text, using words other than STOP (i.e., unsubscribe, cancel, etc.), and (2) via other channels, for example if a customer contacts customer support and asks to be opted-out of text messages. The business should unsubscribe that consumer out of all recurring text messaging programs and cease text messaging to that consumer, unless that consumer subsequently opts-in.

### Mobile-Originated Opt-Out

When a consumer texts the brand with a keyword like STOP (or any of the other opt-out keywords specified by law or best practices), Airship SMS automatically responds with a confirmation and adds an opt-out date/time to our database (example message below, marketers can tailor the content of this opt-out confirmation message to fit their workflow and brand requirements):

```text
{BRAND NAME}: You have opted-out and will no longer
receive messages. Reply HELP for help
```


Airship does not send messages to any numbers that have opt-out dates associated with them. If the consumer decides to opt in again, the Double Opt-In or Brand Managed Opt-In methods described above will register a new opt-in date.

### Website- or App-Originated Opt-Out

If a consumer changes their preferences in a Preference Center—or in some other way via the brand's website or app—the brand must pass the opt-out information to the Airship platform using the Airship API. Airship then adds the opt-out date/time to our database.

### Brand-Managed Opt-Out

If you choose to manage SMS opt-outs outside of Airship, it is your responsibility to ensure that the opt-out status remains synchronized between your systems and Airship. Airship does not automatically track or enforce opt-out compliance unless explicitly configured to do so. To ensure users who have opted out in your environment are also suppressed within Airship, you must automate opt-out synchronization or maintain it manually.

For automated management, you configure your external systems to notify Airship when a user opts out. For example, you would forward STOP messages or user opt-out actions to Airship's [Opt-out of SMS messages API endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/sms/#optoutsmschannel). 

For individual channels, you can change opt-in status manually in the dashboard. See [Viewing channel details](https://www.airship.com/docs/guides/audience/contact-management/#viewing-channel-details) in *Contact Management*.

Without either automated management or regular manual updates, Airship will continue to treat those SMS channels as opted-in, and may continue sending messages. In this case, Airship bears no responsibility for message delivery to users you have marked as opted out in your system.

### Carrier Deactivation

Mobile network operators in the USA (like AT&T, Verizon, etc.) provide Airship with a list of deactivated phone numbers on a daily basis (i.e., consumers who have disconnected service with that operator). Airship SMS automatically uninstalls these numbers (removes them from our database entirely) so that the brands don't inadvertently message the wrong person if that number gets reassigned. 

### National Do Not Call Registry (DNC)

Airship does not apply number filtering or automated channel uninstall for mobile numbers that appear on a DNC, in the US or any other known DNC registry.

## Reporting and Records

Airship [SMS reports](https://www.airship.com/docs/guides/reports/engagement/#sms) give brands the ability to view opt-in and opt-out status for consumers who have provided consent to receive SMS messages from the brand.

Brands should also maintain all consent records that provide relevant details. Various locations will have different requirements for how long a brand should maintain opt-in and opt-out records for SMS. Airship retains opt-in date/time records and opt-out date/time records for a mobile phone number in our database for four years. Airship customers can download their full channel listing via the [Channel Listing API](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#getchannels), which includes channel created-on date, the [MSISDN](https://www.airship.com/docs/reference/glossary/#msisdn), associated [Sender ID](https://www.airship.com/docs/reference/glossary/#sender_id) (short code or long code), current opt-in or opt-out status, and opt-in or opt-out date for all SMS channels. You can also send opt-in and opt-out events into other business systems via [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds).

Mobile numbers that are uninstalled through Carrier Deactivation numbers will have their SMS message history purged from Airship.

## RCS Compliance Guidelines

Rich Communication Services (RCS) is an advanced messaging protocol that enables interactive, media-rich communications. RCS messages automatically fall back to SMS/MMS when not supported.

### General Requirements

You must obtain consent and provide disclosure.

- All rules applicable to SMS/MMS also apply to RCS. Review this SMS Compliance document and the [Airship Acceptable Use Policy](https://www.airship.com/legal/acceptable-use/).
- Obtain explicit, documented consent from each recipient before sending RCS messages. Consent must clearly indicate the types of messages the recipient will receive and must not be bundled with other consents.
- Consent must be specific to the brand and campaign and cannot be transferred, bought, sold, or obtained from third‑party lists.
- Maintain records of consent — including timestamps, consent method, and scope — for at least four years or as required by local law.
- If you do not send the first message within a reasonable period after consent is obtained, reconfirm consent in the initial message.

### Consent and Opt‑In

Consent must be obtained via a clear call to action, for example a website form, app, SMS, or other digital means. Do not use pre‑checked boxes or require consent as a condition of purchase. The call to action must:

- Identify the brand
- Specify the recipient’s phone number
- Describe the types and frequency of RCS messages
- Disclose that messages may be sent using automated technology
- State that consent is not required for purchase
- Provide links to Terms of Use and Privacy Policy
- Include [opt‑out instructions](#optout-and-revocation-of-consent)

### Sender Identification

Every RCS message must clearly identify the sender, which is the party that obtained consent, except for follow‑up messages in an ongoing conversation thread.

### Opt‑Out and Revocation of Consent

Regarding consent:

- Recipients must be able to revoke consent at any time by replying with standard opt‑out keywords such as STOP, UNSUBSCRIBE, CANCEL, END, QUIT.
- The initial RCS message must include opt‑out instructions, such as "Reply STOP to unsubscribe."
- When a recipient opts out, you may send one final confirmation message. No further messages may be sent unless new consent is obtained.
- Opt‑out requests must be processed promptly and applied across all recurring RCS messaging programs.

### Content Restrictions

Do not send RCS messages containing:
* Counterfeit goods
* Dangerous products or services
* Products, services, or content that enable dishonest behaviors
* Dangerous or derogatory content
* Shocking content
* Capitalizing on sensitive events
* Animal cruelty
* Adult or sexual content
* Tobacco
* Political content
* Unauthorized content
* Gambling or gambling-related activities
* Firearms/weapons
* Cannabis
* Prescription drugs/medications
* Alcohol

For additional information, see Google's [Acceptable Use Policy](https://developers.google.com/business-communications/rcs-business-messaging/terms-and-policies/aup) in their *RCS for Business* documentation.

### Country‑Specific Requirements

Always review and comply with country‑specific RCS messaging requirements, which may include additional consent, content, or technical restrictions.

### Recordkeeping and Reporting

Maintain records of opt‑in and opt‑out status, including timestamps and consent method, for at least four years or as required by local law. Be prepared to provide proof of consent and compliance upon request from Airship or regulators.

### Enforcement and Violation Handling

Violations of these RCS requirements may result in suspension or removal of messaging capabilities by Airship or its providers. Report suspected violations to Airship immediately by contacting your account manager or [Airship Support](https://support.airship.com).

<!-- /PAGE: SMS Compliance -->

<!-- /SECTION: SMS, MMS, and RCS -->

<!-- SECTION: Open Channels, PATH: https://www.airship.com/docs/developer/api-integrations/open/ -->

## Open Channels

Deliver notifications to any platform that can accept a JSON payload, without requiring an Airship SDK.

<!-- PAGE: Getting Started, PATH: https://www.airship.com/docs/developer/api-integrations/open/getting-started/ -->

# Getting Started

> Set up your webhook server and Airship before sending your first push notification.*Open Channels* support notifications to any medium that can accept a JSON payload, through
either the Airship API or web dashboard.

Unlike natively supported channels such as iOS, Android and web, Open Channels are not
backed by an Airship SDK. In the absence of an SDK, it's up to you, the developer,
to **A)** register end users with our [Open Channels API](https://www.airship.com/docs/developer/rest-api/ua/operations/open-channels/) and **B)** determine how to parse and display the notification payloads in the available interface. Registering a user returns a [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id).

Leverage features such as segmentation, scheduling,
and local time delivery, while sending notifications to any messaging channels
you choose. You can send to natively supported channels, e.g., Android or iOS,
and open messaging channels in combination or in isolation, using our familiar
`device_types` selector and platform-specific payloads.

Open Channels is an extension of the Channels API. See the
[Intro to Channels](https://www.airship.com/docs/guides/getting-started/developers/channels-intro/)
for more information.

> **Tip:** If you use an AI coding assistant, you can connect it to Airship with Skills and an MCP server. See [Airship AI Tools](https://www.airship.com/docs/developer/ai-tools/ai-tools/).

## API Resources

* [Intro to Channels](https://www.airship.com/docs/guides/getting-started/developers/channels-intro/)
* [Open Channels API Reference](https://www.airship.com/docs/developer/rest-api/ua/operations/open-channels/)
* [Open Channels Platform Override API Reference](https://www.airship.com/docs/developer/rest-api/ua/schemas/platform-overrides/)

These are the steps to setting up your open channels integration:

1. Set up your webhook server.
1. Configure your new webhook in the Airship dashboard.
1. Register a channel to your Open Platform.
1. Send a push.


## Set Up Your Webhook Server

> **Important:** You need to do this first because the Open Channel configuration in the next
> step requires your webhook URL.


**The webhook server must:**

1. Accept HTTPS connections. Accepted Cipher Suites:
      * TLS_CHACHA20_POLY1305_SHA256
      * TLS_AES_256_GCM_SHA384
      * TLS_AES_128_GCM_SHA256
      * TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      * TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      * TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

1. When receiving an authorized `GET` request to `<webhook_root>/validate`:
   * Return a 200 response code.
   * Return a `Content-Type` of `"application/json"`.
   * Return a JSON body with the form: `{"confirmation_code":"559384cd-6284-4e3e-9e4e-7c260019a251"}`.

1. When receiving an authorized POST request to `<webhook_root>/push`:
   * Return a 200 response code.

**The webhook server should:**

1. Expect to process payloads in the format of the samples below.
1. Point to an array of Send Objects with the top level `"values"` key.

**Send Object:**

`"send_id"`
: Required, UUID uniquely identifying the send. Can be used for de-duplication in the event of a retry, logging, or tracing.

`"app_key"`
: Required, the 22-character identifier of the Airship project associated with the open channel.

`"target"`
: Required, a Target Object with the following attributes:
  * `"address"` Required, string. The address of the open channel.
  * `"channel_id"` Required, the Airship Channel ID of the Open Channel.
  * `"identifiers"` Optional, an Object with up to 100 string:string identifiers associated with the Open Channel.

`"payload"`
: Required, a Payload Object with the following attributes:
   * `"alert"` Required, string. The alert message for the notification.
   * `"title"` Optional, string. Optional title, useful for email subject lines or headers.
   * `"extra"` Optional, an object of user-supplied string:string key:value pairs associated with the push.

**Sample Payload**


```json
{
   "values": [
      {
         "send_id": "ff76bb85-74bc-4511-a3bf-11b6117784db",
         "app_key": "YOUR_APP_KEY",
         "target": {
            "address": "SOME_INTERNAL_ID",
            "channel_id": "a61448e1-be63-43ee-84eb-19446ba743f0",
            "identifiers": {
               "cid": "1234567",
               "com.example.token": "a61448e1-be63-43ee-84eb-19446ba743f0"
            }
         },
         "payload": {
            "alert": "Giant StayPuft Marshmallow Man On a Rampage",
            "title": "Breaking News!",
            "extra": {
               "url": "https://www.example.com/"
            }
         }
      },
      {
         "send_id": "647e799e-3b15-46f0-b4f1-12360d51ce4a",
         "app_key": YOUR_APP_KEY",
         "target": {
            "address": "SOME_OTHER_INTERNAL_ID",
            "channel_id": "5b7e9f63-df28-43f4-8182-b762c628c4c4",
            "identifiers": {
               "cid": "7654321",
               "com.example.token": "503640e8-88f7-4dee-9245-7479ac1a8501"
            }
         },
         "payload": {
            "alert": "Giant StayPuft Marshmallow Man On a Rampage",
            "title": "Breaking News!",
            "extra": {
               "url": "https://www.example.com/"
            }
         }
      }
   ]
}
```



### Signature Hash and Security {#signature-security}

<p>Rather than basic authentication, you can configure
a signature that your webhook server can use to verify that requests come from Airship. To enable this signature, select <strong>Signature Hash</strong> authorization and set a <code>secret_key</code> when configuring your webhook or open channel.</p>
<p>When you enable and set a <code>secret_key</code>, outgoing requests include a hash-based
authentication code computed using the sha256 hash function in an <code>X-UA-SIGNATURE</code> header. You can use this same algorithm to verify the signature
on the receiving server.</p>
<p><code>X-UA-SIGNATURE</code> is composed of the <code>secret_key</code> and a <code>message</code>, both of
which must be UTF-8 encoded. The <code>message</code> is a concatenation of the following
string values:</p>
<ul>
<li>The <code>X-UA-TIMESTAMP</code> header — the unix timestamp when the request was sent.</li>
<li>The <code>:</code> character.</li>
<li>The JSON request body.</li>
</ul>
<p>To prevent replay attacks, you should validate the <code>X-UA-TIMESTAMP</code> within a threshold of the current time. We recommend that you use a 5-minute threshold to account for time drift, though Airship uses NTP and we recommend that your webhook server does the same. To prevent timing attacks, you should employ a constant time-compare function when checking signatures.</p>
**Request headers with secret key**

```http
POST /yourWebhookServer/push HTTP/1.1
Content-Type: application/vnd.urbanairship+json; version=3
Content-encoding: gzip
X-UA-TIMESTAMP: 1536947409
X-UA-SIGNATURE: 68688b9dbd5c381851d3cd51dba3093c6633ceef58e6fee6ad4757f857f59aea
Data-Attribute: values
```

## Airship Setup

Begin by configuring your new webhook in the dashboard.

1. Next to your project name, select the dropdown menu (▼), then **Settings**.
1. Under **Channels**, select **Open Channels**.
1. Click **+ Configure new Open Channel** and complete the form. All fields are required.
   * **Display Name:** Enter a user-friendly name for the channel, e.g.,
      "Alexa," "Smart Toaster Dev." This is the name of the channel as it will appear in the Airship dashboard.
   * **Name:** Enter a name indicative of the platform, e.g., `slack`
      or `sms`. This is the canonical name that will be used for programmatic use through our API. 20-character maximum. A-Z, a-z, 0-9, _, and - only.
   * **Webhook URL:** Enter the URL + path to which we will deliver message payloads, e.g., `https://example.com/api/channels/production`.
   * **Authentication:** Select the authentication mechanism for your webhook server.
      * **None**
      * **Basic:** Enter the username and password for the webhook server.
      * **Signature Hash:** Enter a secret key for use as a part of the
         `X-UA-SIGNATURE` header. See [Signature Hash and Security](https://www.airship.com/docs/developer/api-integrations/open/getting-started/#signature-security) for more information.
1. Click **Save**.
   After saving, a Validation Code field appears, containing a 36-character UUID. This code must be returned by the webhook server at `<webhook_root>/validate`. See: [Set Up Your Webhook Server](#set-up-your-webhook-server).
   ![Validation code displayed after saving an open channel configuration](https://www.airship.com/docs/images/services-open-channels-code_hu_ed7ff784ac293292.webp)
   
   *Validation code displayed after saving an open channel configuration*
1. Check the *Enabled* box to enable the open channel for use, then click **Update**.
> **Important:** If the channel
> is not enabled, you will be able to register a new open
> channel with the corresponding platform type, but you will not be able to
> send a push to that platform using our API.


> **Note:** We do not validate the endpoint until you enable and save the configuration. We will revalidate it each time you update the configuration, as long as it remains enabled.



## Register a Channel to Your Open Platform

Next, you'll need to populate your audience in our system. This registration step is handled automatically in our mobile and web SDKs, but you are responsible for populating the Airship system with users on open platforms.

You can register channels using [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send) or by sending a request to the [Open Channel Registration API](https://www.airship.com/docs/developer/rest-api/ua/operations/open-channels/#createorupdateopenchannel).

When using the Open Channel Registration API, the request body must contain the following keys:

`"type"`
: Required, string. Currently the only only valid value for `type` is `"open"`.

`"opt_in"`
: Required, boolean. A flag to determine if the owner of this device still wants to receive notifications. If false, no open channels payloads will be delivered to the webhook for this channel.

`"address"`
: Required, string. The primary identifier of a record. For example, in an SMS integration, it could be the end user's phone number. 128 character maximum.

`"tags"`
: Optional, array of strings. Can be used for audience segmentation.

`"timezone"`
: Optional, string. An IANA tzdata identifier for the timezone as a string, e.g., `"America/Los Angeles"`. Will set the `timezone` tag group tag with the specified value.

`"locale_country"`
: Optional, string. The two-letter country locale short code. Will set the `ua_locale_country` tag group to the specified value.

`"locale_language"`
: Optional, string. The two-letter language locale short code. Will set the `ua_locale_language` tag group to the specified value.

`"open"`
: Required, object. Open Platform Options Object. Contains the following keys:

  * `"open_platform_name"`: Required, string. The name of the open platform to which you are registering this channel.
  * `"identifiers"` - Optional map of string values. These will be delivered in open channels payloads, but cannot be used for segmentation. Maximum of 100 pairs of string values. This map should be exhaustive whenever this key is present. Values will not be unioned with existing identifiers; they will replace them.

**Sample Payload**


```json
{
   "channel": {
      "type": "open",
      "opt_in": true,
      "address": "Number Four",
      "tags": [
         "toaster",
         "caprica"
      ],
      "timezone": "America/Los_Angeles",
      "locale_country": "US",
      "locale_language": "en",
      "open": {
         "open_platform_name": "cylon",
         "identifiers": {
            "model": "4"
         }
      }
   }
}
```


## Push To Your New Channel

To push to your channel, simply push like you would to any other channel,
using the `open_channel` identifier as your audience selector. See
[Audience Selection](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/#audienceselector1000)
for more detail.

The key difference in an Open Channels API push is the namespacing of the `device_types` identifier for
your configured platform. Prepend the new `device_types` identifier with `open::`, e.g., for
your new toaster's channel, use `"open::toaster"`.

**Example Request**


```json
{
   "notification": {
      "alert": "Pop!"
   },
   "audience": {
      "open_channel": "32c99a88-0df1-4eed-9ac3-abc8ee5314ed"
   },
   "device_types": [
      "open::toaster"
   ]
}
```


### Associate a Named User

You can also associate your channel with a [Named User](https://www.airship.com/docs/reference/glossary/#named_user) using the [Association](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#associatenameduser) endpoint, and then use that for targeting.

**Associate Channel ID with Named User**


```http
POST /api/named_users/associate HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "channel_id": "5b7e9f63-df28-43f4-8182-b762c628c4c4",
   "named_user_id": "igorstravinsky"
}
```


### Fan out

Now that you have registered your channel, and mapped a Named User to it, you need only target the named
user and enumerate the configured `device_types` on which you would like to reach your Named User.
The Named User mapping will fan out to all devices on supported platforms for the given Named User.

**Fan out a message to all devices associated with the Named User**


```json
{
   "notification": {
      "alert": "Pop!"
   },
   "audience": {
      "named_user": "igorstravinsky"
   },
   "device_types": [
      "ios",
      "android",
      "open::toaster"
   ]
}
```


### View Send Counts

After you've sent a push notification to your open channel, use the
[Push Response Report](https://www.airship.com/docs/guides/reports/engagement/#push-response) endpoint to retrieve send counts broken out by
open platform.

**Example Push Response. Use the ``push_id`` in your request**


```json
{
    "ok": true,
    "operation_id": "6b5e94f5-9c85-486a-a76e-67d18b3eaf05",
    "push_ids": [
        "362b7e8d-af82-4a67-ac76-49e5ea2f7f59"
    ],
    "message_ids": [],
    "content_urls": []
}
```


**Response API request, using ``push_id`` from previous example**


```http
GET /api/reports/responses/362b7e8d-af82-4a67-ac76-49e5ea2f7f59 HTTP/1.1
Authorization: Basic <master authorization string>
```



**Example response returns the ``open_channels_sends``, broken out by open platform**


```json
{
    "push_uuid": "362b7e8d-af82-4a67-ac76-49e5ea2f7f59",
    "push_time": "2017-08-08 16:41:59",
    "push_type": "SEGMENTS_PUSH",
    "direct_responses": 0,
    "sends": 0,
    "open_channels_sends": {
        "platforms": [
            {
                "id": "sms",
                "sends": 1
            },
            {
                "id": "toaster",
                "sends": 1
            }
        ]
    }
}
```



<!-- /PAGE: Getting Started -->

<!-- PAGE: Use Cases, PATH: https://www.airship.com/docs/developer/api-integrations/open/use-cases/ -->

# Use Cases

> Explore common use cases for Open Channels.<p>The simplest use case for a notification is the one we are all familiar with: displaying
the text of an alert. But there are many other uses for a notification payload, which,
depending on the target interface or OS, may be handled in different ways. For example,
our SDKs for iOS and Android support the interactive features of those operating systems
through our API. Our API also supports an <code>extra</code> field, which lets you to pass any
key/value pair to handle how you see fit, e.g., update a config file or trigger a different
process.</p>
<p>An open channel can be any non-native
platform or interface where you&rsquo;d like to reach users, or for that matter any client
capable of receiving a payload over the Internet. The end message doesn&rsquo;t need to be
human-readable alert text as you might see on an iPhone. Alerts are usually intended
for people, but in the case of a machine, you could tell it to update its firmware,
increment a counter in a database, or perform some other action. Use cases include:</p>
<ul>
<li>Automated Slack Message using Slack incoming webhooks</li>
<li>Chatbot notifications</li>
<li>Firmware updates for IOT devices</li>
<li>Integrate with third-party messaging APIs, e.g., Twitter</li>
</ul>


<!-- /PAGE: Use Cases -->

<!-- PAGE: Integration Points, PATH: https://www.airship.com/docs/developer/api-integrations/open/integration-points/ -->

# Integration Points

> A new Open Channel requires three integration points.There are three integration points required to set up a new Open Channel:

1. **Webhook Server**<br>
   Accepts the Airship Open Channels payload, translates and routes your request.

1. **Channel Registration API**<br>
   Because Open Channels aren't supported by a client SDK, you must register new
   open channels in the Airship system directly.

1. **Push API**<br>
   Deliver message payloads using our [API](https://www.airship.com/docs/developer/rest-api/ua/),
   specifying open channels in your request.


<!-- /PAGE: Integration Points -->

<!-- PAGE: Open Delivery Payload, PATH: https://www.airship.com/docs/developer/api-integrations/open/open-delivery-payload/ -->

# Open Delivery Payload

> View webhook request body examples and details for Open Channels.## Webhook POST Request Body

The request body itself is a JSON object containing a single top level key, `"values"`, pointing to an array of up to 1,000 JSON objects. Airship will break up large pushes into groups of 1,000.

Keys for each object in the array:

* `"send_id"` — Required, a UUID version 4 string. Uniquely identifies the object.
* `"app_key"` — Required, a 22-character string containing the characters: [-_A-Za-z0-9].
* `"payload"` — Required, a push payload with all `"open"` overrides for the delivery type applied.
* `"target"` — Required, a target object containing the `address` and a string->string map of alternative identifiers.
* `"push_id"` — Optional, a UUID version 4 string. Uniquely identifies the push.

**An example request body with two objects, each containing all possible keys**


```http
POST /hooks/ua/example_hook/push HTTP/1.1
Content-encoding: gzip
Data-Attribute: values
Content-Type: application/vnd.urbanairship+json; version=3

{
   "values": [
      {
         "send_id": "ff76bb85-74bc-4511-a3bf-11b6117784db",
         "app_key": "YOUR_APP_KEY",
         "target": {
            "address": "221B Baker Street",
            "channel_id": "a61448e1-be63-43ee-84eb-19446ba743f0",
            "identifiers": {
               "cid": "1234567",
               "com.example.test_token": "a61448e1-be63-43ee-84eb-19446ba743f0"
            }
         },
         "payload": {
            "alert": "Giant StayPuft Marshmallow Man On a Rampage",
            "title": "Breaking News!",
            "extra": {
               "url": "https://www.example.com/"
            }
         }
      },
      {
         "send_id": "647e799e-3b15-46f0-b4f1-12360d51ce4a",
         "app_key": "YOUR_APP_KEY",
         "target": {
            "address": "1600 Pennsylvania Avenue",
            "channel_id": "5b7e9f63-df28-43f4-8182-b762c628c4c4",
            "identifiers": {
               "cid": "7654321",
               "com.example.test_token": "503640e8-88f7-4dee-9245-7479ac1a8501"
            }
         },
         "payload": {
            "alert": "Giant StayPuft Marshmallow Man On a Rampage",
            "title": "Breaking News!",
            "extra": {
               "url": "https://www.example.com/"
            }
         }
      }
   ]
}
```


**An example request body with one object, containing only the required keys**


```http
POST /hooks/ua/example_hook/push HTTP/1.1
Content-encoding: gzip
Data-Attribute: values
Content-Type: application/vnd.urbanairship+json; version=3

{
   "values": [
      {
          "send_id": "ff76bb85-74bc-4511-a3bf-11b6117784db",
          "app_key": "YOUR_APP_KEY",
          "target": {
              "address": "test@example.com",
              "channel_id": "a61448e1-be63-43ee-84eb-19446ba743f0",
          },
          "payload": {
              "alert":"Giant StayPuft Marshmallow Man On a Rampage",
          }
      }
  ]
}
```


## Target Object

Information pertaining to the target related to a webhook payload is defined under the `"target"` key in each response item.

Keys for each target object:

* `"channel_id"` — Required, string. The channel identifier for the target.
* `"address"` —  Required, string. The customer-provided delivery address for the target.
* `"identifiers"` — Optional, a JSON object with identifiers specified by the app. Common uses are IDFA or the primary key in your CMS. The values of the keys and values in this object are up to you, however Airship may make additional functionality available using keys prefixed with "com.urbanairship." so keys using that prefix should be avoided.
* `"opt_in"` — Optional, boolean. True if the target has opted in, false otherwise.

**Example target object**


```json
{
   "identifiers": {
      "com.urbanairship.aaid": "94b0c28e-0f00-4601-af28-e70322f46a75",
      "friend": "ship",
      "ice": "cream",
      "session_id": "5abe6b52-7dcf-4fec-b0a5-d24cb4deaafe",
      "com.urbanairship.limited_ad_tracking_enabled": "false"
   },
   "channel_id": "1e215090-e692-4d89-ab7f-1f2ace2a229b",
   "address": "+1 5558675309"
}
```


## Payload Object

The payload to deliver to the target. Possible keys:

* `"alert"` — Required, string. The primary message to deliver to the target.
* `"title"` — Optional, string. The title of the payload. A good example use case would be an email header for an open email notification.
* `"extra"` — Optional, a string-to-string map of additional values to deliver to the target. Can contain any additional information that users want to deliver to the target.
* `"summary"` — Optional, string. A text summary of the payload contents, as supplied in the push.
* `"media_attachment"` — Optional. A URL for an image or video to include with the payload.
* `"interactive"` — Optional. An interactive payload object.


<!-- /PAGE: Open Delivery Payload -->

<!-- /SECTION: Open Channels -->