User Registration

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

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.

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

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

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

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-01T1225",
        "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.

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

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.