# 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/in-app-experiences/configuration/content/#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 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 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 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 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 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.