Getting Started

Overview

Getting started with Airship email is a 3-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.

Provision Account

To get started using Airship email, contact your account manager or Airship Support  to provision your project for email notifications.

Register Users

Registering an email address returns an Airship 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:

• Opt-in form — A user can sign up for email messages through an opt-in form 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.
• Bulk registration when sending a message — This can be done using the Create and Send API or the Upload users option in the Message composer. See: Inline ListAn ad-hoc, CSV-formatted list of email, SMS, app, web, or open channel addresses that you want to register and send a message to. Unlike static lists or segments, you upload this list when creating your message. Airship registers new addresses in the list as channels when you send the message. and Create and Send API.
• SDK — Register an email channel through the Mobile SDKs.
• CSV Upload — You can upload email addresses in a CSV file to set TagsMetadata that you can associate with channels or Named Users for audience segmentation. Generally, they are descriptive terms indicating user preferences or other categorizations, e.g., wine_enthusiast or weather_alerts_los_angeles. Tags are case-sensitive. or AttributesMetadata used for audience segmentation and personalization. They extend the concept of Tags by adding comparison operators and values to determine whether or not to target a user, helping you better evaluate your audience.. Airship registers new channels for addresses that are new to your project. See:
  • Setting attributes using a CSV file
  • Setting tags using a CSV file

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"
   }
}

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 UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual.:

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 messsages. 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.

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 FormA form you can add to your website, where your users can sign up for email or SMS messaging. to your website.
2. Airship sends a confirmation email to the address used to sign up. — You set up the email in the dashboard or using the API.
3. The user follows the confirmation link in the email, and Airship updates their channel as opted in.
4. The user can now receive commercial emails.

To set up the confirmation email:

• From the dashboard, create an automation using the Double Opt-In TriggerA trigger that initiates an Automation or Sequence when a member of your audience opts in to commercial email messaging. You must provide an opt-in link in the body of the message, and users must follow the link to confirm opting in..
• For the API, use the /api/pipelines endpoint with the double_opt_in event.

You can filter the trigger by using properties attached to the opt-in event, and you can reference the properties using HandlebarsHandlebars is Airship’s templating language for personalization. Handlebars expressions use double curly braces wrapped around a content template, ranging from a simple variable, e.g., {{first_name}}, to complex evaluations of personalization data. to 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.

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: Email Content: Sender Information.
• For the API, set "message_type": "transactional" and "bypass_opt_in_level": "true". See: Email Overrides.

Next, set "opt_in_mode": "double" 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 trigger and for personalizing the message content using HandlebarsHandlebars is Airship’s templating language for personalization. Handlebars expressions use double curly braces wrapped around a content template, ranging from a simple variable, e.g., {{first_name}}, to complex evaluations of personalization data..

Updating Registration

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

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.

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.

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:

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"
   }
}

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

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

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. 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.

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: Create a message and Email content.
• API — Use the Push API; you must set email platform overrides such as sender_name, sender_address, etc.

You can also create templates for your email notifications. You create templates in the dashboard, then send using the dashboard or API. In the API, send a template using the /create-and-send or /pipelines APIs.