Email

Email is one of Urban Airship's native messaging channels, supporting both commercial and transactional messages.

Unlike app and web channels, email Channel IDs are not generated for you via an SDK. You must manually register email addresses directly with Urban Airship.

This document explains how to register email channels, set up templates, and send email notifications via the dashboard and API.

Resources

Configure Your Project

Before you can use Urban Airship email capabilities with your project, you must setup email-specific IPs and sending domains. Contact Urban Airship Support or your Account Manager to provision your project for email notifications and complete the configuration.

Register users

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:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
Location: https://go.urbanairship.com/api/channels/df6a6b50-9843-0304-d5a5-743f246a4946

{
    "ok": true,
    "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}
Important

You must register all recipient email addresses, not just recipients of commercial messages.

Registering an email address returns an Urban Airship channel ID. You will typically reference your audience of email addresses by channel IDs or other abstractions within Urban 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. This feature is reflected as an inline list in the dashboard. If using the API, see the Create and Send API.

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

Example Request - Update email address:

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

Example Request - Lookup channel by email address:

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

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

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.

Create Templates

In most cases, you will create a template for your email notifications through the Personalization API. Templates support variables, so you can personalize emails for each individual recipient.

To create templates using the dashboard, follow the the Email Templates Tutorial.

Note

You can provide your own HTML email without using a template. However, you cannot personalize emails using merge fields without using a template.

Send Email

To send email using the dashboard, follow the steps in the Email Notification Tutorial.

For the API, you can send a message using a template via the Personalization API, or by sending the complete message via the Push API.

Send Email Using a Template

Example Request With a Template

POST /api/templates/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "device_types": [
      "email"
   ],
   "audience": {
      "named_user": "aandersson"
   },
   "merge_data": {
      "template_id": "bde1d200-e68d-4230-bd9a-34a1939b18ff",
      "substitutions": {
         "FIRST_NAME": "Anders",
         "LAST_NAME": "Andersson"
      }
   }
}

Using the Personalization API endpoint, you can send an email specifying a template ID. The substitutions object contains the variable names (as keys) and the values you want to substitute in the template, for the audience.

Important

If your template contains merge fields, you must include all merge fields in your request or none at all.

In this example, we are targeting the named user aandersson and providing values for FIRST_NAME AND LAST_NAME keys included in the template.

Send Email Without a Template

Example Request Without a Template

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "audience": {
      "named_user": "jane_doe"
   },
   "device_types": [
      "email",
      "android"
   ],
   "notification": {
      "android": {
        "alert": "Hello Android user!"
      },
      "email": {
        "subject": "Winter Sale!",
        "html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
        "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
        "message_type": "commercial",
        "sender_name": "Urban Airship",
        "sender_address": "team@urbanairship.com",
        "reply_to": "no-reply@urbanairship.com"
      }
   }
}

When sending an email via the Push API, you must set email platform overrides such as sender_name, sender_address, etc.

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

Event Reporting

See: Engage Reports: Email.