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.
A user can sign up for Email messages through an opt-in form you can add to your website.
You can generate an email channel for an individual user by using the Email Channel Registration API.
You can also register addresses in bulk when sending a message using the Create and Send feature. Create-and-send registers email channels and sends a message simultaneously. See: Inline ListAn ad-hoc, CSV-formatted list of email, SMS, or open channel addresses that you want to register and/or 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 your message. . If using the API, see the Create and Send API.
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 contact:
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 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.
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:
- 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.
- Airship sends a confirmation email to the address used to sign up. — You set up the email in the dashboard or using the API.
- The user follows the confirmation link in the email, and Airship updates their contact as opted in.
- 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 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 thedouble_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 content: Double opt-in.
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.
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.
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
When updating an email address for a contact, you will:
- Register a new address.
- Associate the new address to the same contact associated with the email address you want to remove.
- Opt out the previous email address.
First, register the new address.
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": "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": "924a0c8c-5d58-4401-8a35-13440EXAMPLE"
}
Next, associate the channel with the existing contact. In this example we use named user.
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": "924a0c8c-5d58-4401-8a35-13440EXAMPLE",
"device_type": "email",
"named_user_id": "example-named-user-id"
}
Last, opt out the previous email address.
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_out": "2022-04-07T18:51:00",
"transactional_opted_out": "2022-04-07T18:51:00"
}
}
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.
Suppress
When Airship sends an email on your behalf we may receive feedback for a delivery address, such as a hard bounce or a spam complaint. When this occurs, Airship will suppress future deliveries to this address. However Airship may not be your exclusive email service provider, and you may collect the same feedback via another mechanism.
When this occurs, you should update the suppression record using the suppression endpoint.
Once an email channel is suppressed, there is no API endpoint provided to remove that suppression state. Should you need a suppression state removed, you may contact Airship support to have this request processed.
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.
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.
Categories