Getting Started

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

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:

Example Request — Registration
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/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. :

Example Request — User Association
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.
 Note

For /api/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 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:

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.

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

Example Request — Lookup channel by email address
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:

Example Request — Replace
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/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 UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual. , 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. 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.

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.

 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.