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.
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"
}
}
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.
Updating Addresses and Registration
You can update the email address for a channel or the opted_in
and opted_out
values
using a PUT call for the channel.
PUT /api/channels/email/251d3318-b3cb-4e9f-876a-ea3bfa6e47bd 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-11-01T12:00:25",
"address": "new.name@new.domain.com",
}
}
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%40domain.com HTTP/1.1
Authorization: Basic <master secret authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
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.
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