1. Home
  2. /Developer
  3. /REST APIs
  4. /Airship API

Airship API

Airship’s REST APIs for messaging, content personalization and audience management.

Libraries

Airship maintains open source server libraries to support your integrations with our APIs in multiple languages. Click below for library documentation.

Introduction

Airship provides a number of REST API endpoints collectively known as the Airship API Version 3, in support of our messaging product lines and related features. Version 3 is the current and only supported version of the Airship API.

API Request Format

All API requests are HTTP requests. For all requests with a body, the body may be in JSON  format or other formats like CSV as specified for the endpoint. The proper Content-Type for JSON is application/json and the proper content type for CSV is text/csv.

Date-Time Format

All date-time values are represented as a string according to ISO 8601  in UTC.

  • The string must be in the format YYYY-MM-dd['T']hh:mm:ss['Z'] where the T can be replaced by a space and the Z is optional.
  • A T separator is preferred but not required. It will be included in all date-time values generated by the API. For example:
    • 2023-11-13T09:42:30Z
    • 2023-11-13T09:42:30
    • 2023-11-13 09:42:30Z
    • 2023-11-13 09:42:30
  • A trailing time zone identifier or offset should not be included.
  • UTC is implicit.

Color Format

All color values are represented by a string format reminiscent of CSS color values used for web programming. The format is #rrggbb, a literal # character followed by 6 hexadecimal digits representing 3 values in the range 00 to FF. The values are red, green, and blue color components.

API Response Format

All API responses are HTTP responses, making use of appropriate HTTP response codes. When a body is present, it SHALL be in JSON  format, except in certain cases where reporting data MAY be returned in CSV format. The body of all JSON responses SHALL consist of a single JSON object, which SHALL contain a boolean ok attribute indicating overall success or failure. When a request results in a return value containing multiple entities, they SHALL be contained in an array-valued attribute, the name of which MAY vary by endpoint. For example, /api/tag will return a list of tags in the tags attribute, while /api/schedules will return a list of schedules in the schedules attribute. The name of the response object attribute containing the list of returned entities SHALL be contained in the Data-Attribute HTTP header.

Operation ID

All API calls that create or modify resources, or cause side effects, SHALL generate an operation ID. An operation ID is an opaque unique string that identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs. For example, the batch push API call can be used to send multiple pushes in one call. Each push has a unique push ID, but they will all share a common operation ID. This enables roll-ups of multiple related operations (such as push to local time or push to language) and better end-to-end tracing in the push pipeline. Operation IDs are returned in the JSON body of the response, in the operation_id attribute of the root response object. An operation ID will be generated even for error responses.

Response Codes

The API makes use of standard HTTP response codes, with standard HTTP semantics. Response codes in the 200 range indicate success. Codes in the 400 range indicate errors of a correctable nature. Codes in the 500 range indicate system errors.

This table lists general response definitions. Refer to the actual response definition per endpoint.

Response codeDescription
200 OKThe payload was accepted.
201 CreatedAn API request to create a new entity or entities was successful, and the entities were created.
202 AcceptedAn API request was successfully accepted into a processing queue to be processed later.
204 No ContentAn entity was successfully deleted.
400 Bad RequestParsing or validating the request failed.
401 UnauthorizedAuthentication information (the app key and secret) was either incorrect or missing.
403 ForbiddenAuthentication was correct, but the user does not have permission to access the requested API. This can happen if a feature is not included in the user’s Airship plan.
404 Not FoundA request was made for a non-existent entity.
405 Method Not AllowedA request was made using an HTTP method not supported by the endpoint. For example, sending a DELETE to /api/schedules.
406 UnacceptableThe client requested a version of the API that cannot be satisfied, because no compatible version is currently deployed.
409 ConflictAn entity could not be updated due to state conflict.
429 Too Many RequestsA request was denied because the app made too many requests to an API in a short period of time.

Validation

All requests must be validated. Proper validation at the API level can prevent invalid pushes from using resources in our delivery pipeline and educate API users about their own mistakes without involving Support. In the event of an error processing the request, the response body will contain one or more error objects. Parsing errors, arising from syntactically invalid JSON, should return an HTTP 400 Bad Request response. Semantic errors, arising from requests that are syntactically valid but otherwise malformed (for example, missing required fields), should return an HTTP 400 response, with a JSON body indicating details about the validation failure.

Some examples of specific validation cases that cause pushes to be rejected with an HTTP 400 error:

  • Invalid attributes — Any additional JSON keys that are not explicitly allowed by the spec will result in an HTTP 400 error, except where arbitrary keys are explicitly allowed (for example, the extra sections of a push payload).
  • Unconfigured open platform — Any open platform specified in the device_types array must be configured and active for the appKey. If the open platform is not configured, we will return an HTTP 400.
  • Missing payload — A push that specifies delivery to a platform but does not supply a payload for that platform is invalid.
  • Device identifier/restriction mismatch — A push that includes a device identifier in the audience selection but does not include the corresponding platform in the device_types specifier is invalid.
  • Schedule times — Requests to schedule pushes for times that have already passed will return an HTTP 400 response. However, requests to schedule local time pushes for a time that has elapsed in a local time zone will be accepted.
  • Unsupported platform feature — A push that includes features not supported on all platforms must explicitly target the supported platforms. Location is the only feature not supported across all platforms. This includes location expressions in predefined segments. Location pushes must specify device_types : [ ios, android ], or either iOS or Android explicitly.

Pagination

Some resource collections, such as tags and segments, may have a very large number of items, necessitating iterating through them in chunks (or pages) if an API consumer wishes to retrieve them all.

Request Parameters

There are two methods for pagination results:

  • start and limit
  • page and page_size

Using a non-unique identifier for the start parameter is unsound and will not paginate correctly. For endpoints that support sorting, if sorting is applied to a non-unique field, a secondary sort on a unique field must be used internally to ensure stable pagination results.

  • start — Optional string or integer. Identifies the starting element for paginating results. It can be either a unique string identifier or a zero-based offset, depending on the API.
  • limit — Optional integer. The maximum number of elements to return.
  • page — Optional integer. Specifies which page to retrieve, starting with 1.
  • page_size — Optional integer. The number of elements to return per page. The last page may have fewer elements.
  • sort — Optional string. The name of the field to sort results by. This is not necessarily supported by all endpoints.
  • order — Optional asc or desc. If the sort parameter is available, this parameter may be used to specify the direction of the sort as ascending or descending.

Link Header

Collections of entities SHALL be paginated by specifying a start point and a limit on the number of returned items as parameters of the request. The response SHALL include the requested items and a link to the next page of results. A link to the previous page MAY also be included if the underlying service supports it. For example, the Segments API supports previous page links. The links SHALL be provided in the Link HTTP header, as per RFC 5988 Web Linking , using the relations next and prev.

Count and Total

The number of items in the response SHALL be returned in the custom HTTP header Count, as well as in the "count" field of the response object. The total number of items in the collection MAY be returned in the custom HTTP header Total-Count, as well as in the "total_count" field of the response object, if the collection is countable and the total number of items is known.

Version Syntax

You must specify the version of the API you are using with the Accept HTTP header. If you do not specify an API version in the Accept header, a 406 is returned.

The content type used is a vendor-specific media type (see RFC 4288 Media Type Specifications and Registration Procedures ) and must be specified as: application/vnd.urbanairship+json; version=3.

Transport Layer Security

As of October 6, 2020, Airship supports only Transport Layer Security (TLS) versions 1.2 and 1.3 in our APIs, in accordance with PCI Security Standards Council  recommendations.

If your API integration uses TLS 1.0 or 1.1, contact our Support team  for assistance migrating to TLS 1.2 or 1.3.

Delivery Speed Options

The Airship push API is designed for extremely high throughput to ensure delivery to your entire audience as fast as possible. Depending on the size and/or complexity of your audience and the urgency of the message, you may find that you need to either slow down or speed up the delivery. To that end, we offer the following add-on services: Boost and Throttling.

If you are interested in enabling Boost or Throttling, contact Support .

Boost

Boost optimizes your segmented messages through parallel processing. Consider adding Boost if your notifications are extremely time-sensitive. Boost is a paid add-on. Contact your Account Manager for details.

Throttling

For less time-sensitive messages, our standard delivery speed may cause undue pressure on your internal systems or APIs, for example, when millions of users open your app at the same time. Use Throttling to tune delivery to a level that doesn’t put strain on those systems.

Complex segments can cause delays in processing

When creating segments or pushes with logical expressions, keep in mind that one or more NOT statements may cause latency when sending notifications, as NOT operations are inherently more expensive to perform than OR or AND operations. For example, tag_a AND NOT tag_b is basically the same speed as tag_a AND tag_b, but just NOT tag_b is likely to be slower than just tag_b.

Latency is more significant with larger audiences. We recommend using AND statements in place of NOT statements whenever possible as a best practice.

Device changes can take a few minutes

Some requests to register or unregister information about a device may take a few minutes to process before you are able to see the changes. Keep this in mind when performing PUT or POST requests.

Base URL

Select the domain associated with your Airship project.

  • https://go.urbanairship.com - The base URL for Airship's North American cloud site when using HTTP authentication
  • https://go.airship.eu - The base URL for Airship's European cloud site when using HTTP authentication
  • https://api.asnapius.com - The base URL for Airship's North American cloud site when using OAuth authentication
  • https://api.asnapieu.com - The base URL for Airship's European cloud site when using OAuth authentication

Authentication

For additional information, including steps for creating bearer tokens and OAuth client credentials, see Airship API Security. See also the Airship API Authorization Reference.

  • Basic Auth (App) HTTP (basic)
    Authorization header containing the word Basic followed by a space and a Base64-encoded string generated from your App Key and App Secret in appKey:appSecret format. For example, Basic YXBwX2tleTphcHBfc2VjcmV0.
  • Basic Auth (Master) HTTP (basic)
    Authorization header containing the word Basic followed by a space and a Base64-encoded string generated from your App Key and Master Secret in appKey:masterSecret format. For example, Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0.
  • Basic Auth (OAuth) HTTP (basic)
    Authorization header containing the word Basic followed by a space and a Base64-encoded string generated from your OAuth Client ID and Client Secret in client_id:client_secret format. For example, Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0. Used only for requesting OAuth tokens. See OAuth.
  • Bearer Token HTTP (bearer)
    Authorization header containing the word Bearer followed by a space and a bearer token generated from the Airship dashboard. You can generate tokens for different roles. If your role does not grant you access to a feature, the endpoint will respond with a 401 status code. Tokens can be revoked at will.
  • OAuth 2.0 OAuth
    Authorization header containing the word Bearer followed by a space and an OAuth 2.0 JWT bearer token provided by our authorization server. See OAuth. Make sure your requests are using the appropriate domain.

OAuth

Request an OAuth 2.0 token using Basic Auth or an assertion.

Request token

POST /token

Example request token with Basic Auth

POST /token HTTP/1.1
Host: oauth2.asnapius.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Basic <base64 encoded string of "client_id:client_secret">

grant_type=client_credentials&sub=app:JQIMcndxIHWy2QISpt1SpZ&scope=chn&scope=nu&ipaddr=24.20.40.0/24&ipaddr=2001:4860:4860::8888/32

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "scope": "chn nu",
  "expires_in": 3600
}

OAuthCredentials oAuthCredentials = OAuthCredentials.newBuilder("<client_id>")
        .setClientSecret("<client_secret>")
        .setSub("<sub>")
        .setScopes(Arrays.asList("<scope1>","<scope2>","<...>"))
        .setIpAddresses(Arrays.asList("<IP1>","<IP2>",<...>))
        .build();

UrbanAirshipClient oAuthClient = UrbanAirshipClient.newBuilder()
        .setKey("yourAppKey")
        .setOAuthCredentials(oAuthCredentials)
        .build();

Example request token with assertion

POST /token HTTP/1.1
Host: oauth2.asnapius.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Basic <base64 encoded string of "client_id:client_secret">

grant_type=client_credentials&sub=app:JQIMcndxIHWy2QISpt1SpZ&scope=chn&scope=nu&ipaddr=24.20.40.0/24&ipaddr=2001:4860:4860::8888/32

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "scope": "chn nu",
  "expires_in": 3600
}

OAuthCredentials oAuthCredentials = OAuthCredentials.newBuilder("<client_id>")
        .setClientSecret("<client_secret>")
        .setSub("<sub>")
        .setScopes(Arrays.asList("<scope1>","<scope2>","<...>"))
        .setIpAddresses(Arrays.asList("<IP1>","<IP2>",<...>))
        .build();

UrbanAirshipClient oAuthClient = UrbanAirshipClient.newBuilder()
        .setKey("yourAppKey")
        .setOAuthCredentials(oAuthCredentials)
        .build();

POST /token HTTP/1.1
Host: oauth2.asnapius.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=client_credentials&assertion=<encoded_jwt>

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "scope": "chn nu",
  "expires_in": 3600
}

OAuthCredentials oAuthCredentials = OAuthCredentials.newBuilder("<client_id>")
        .setAssertionJWT("<encoded_jwt>")
        .build();

UrbanAirshipClient oAuthClient = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setOAuthCredentials(oAuthCredentials)
        .build();

# The python OAuth client handles JWT creation 
# and token refresh automatically.
# Once instantiated, this can be used as any other Airship client.

airship_client = OAuthClient(
  client_id="<client_id>",
  private_key="<private_key>",
  key="<project_key>",
  scope=["<scopes>",],
  id_addr=["<ip list>",],
  timeout="<timeout seconds int>",
  retries="<attempts on failure int>"
)

require 'urbanairship'

UA = Urbanairship
app_key = '<application_key>'

oauth = UA::Oauth.new(
  client_id: '<client_id>',
  key: app_key,
  assertion_private_key: '<your_private_key>',
  scopes: ['psh', 'chn'], # Optional
  ip_addresses: ['23.74.131.15/22'], # Optional
  oauth_server: 'api.asnapieu.com' # Optional
)

airship = UA::Client.new(key: app_key, oauth: oauth)

Request an OAuth access token with Basic Auth or an assertion. When making a request with an assertion, do not provide the Basic Auth header. See also OAuth 2.0 in the API Security documentation.

Use oauth2.asnapius.com for Airship’s North American cloud site and oauth2.asnapieu.com for Airship’s European cloud site when requesting an OAuth token.

 Note

When using the OAuth token for Airship API endpoints, make sure your requests are using the appropriate domain.

This example uses the OAuth token to list channels on Airship’s North American cloud site:

 curl --location 'https://api.asnapius.com/api/channels/' \
 --header 'Accept: application/vnd.urbanairship+json; version=3;' \
 --header 'Authorization: Bearer {OAUTH_ACCESS_TOKEN}'

Security:

Request headers:

  • Content-Type stringREQUIRED
    The request must have a Content-Type of application/x-www-form-urlencoded.

Request body:

  • Content-Type: application/x-www-form-urlencoded

    One of
    • Request token with Basic Auth object
      OBJECT PROPERTIES
      • grant_type stringREQUIRED

        Possible values: client_credentials

      • ipaddr string

        A list of CIDR representations of valid IP addresses to which the issued token is restricted. IP addresses can be sent as a URL-encoded, space-delimited list (example: ipaddr=24.20.40.0%2F24%202001%3A4860%3A4860%3A%3A8888%2F32) or as a list as expected in a query parameter form (example: ipaddr=24.20.40.0/24&ipaddr=2001:4860:4860::8888/32).

      • scope object<OAuth Scope>

        A list of scopes to which the issued token will be entitled. Scopes can be sent as URL-encoded, space-delimited list (example: scope=chn%20nu) or as a list as expected in a query parameter form (example: scope=chn&scope=nu).

        The value of the scope parameter is a list of space-delimited, case-sensitive strings. If multiple scopes are specified, their order does not matter. Each string adds an additional access range to the requested scope.

        • att: Attachments
        • chn: Channels
        • evt: Events
        • lst: Lists
        • nu: Named Users
        • pln: Pipelines
        • psh: Push
        • sch: Schedules

      • sub object<Subject>REQUIRED

        A space-delimited set of identifiers for which subjects a token is allowed. An app subject is required. Example: app:JQIMcndxIHWy2QISpt1SpZ.

        A space-delimited set of identifiers for which subjects a token is allowed. Example: app:JQIMcndxIHWy2QISpt1SpZ

        • app: May operate on the given app

    • Request token with assertion object
      OBJECT PROPERTIES
      • assertion object<Assertion JWT>REQUIRED

        An encoded JWT that contains the required headers and claims and is signed with the client credentials’ private key.

        A JSON Web Token (JWT) used for authorization in OAuth token requests. The JWT must be signed with the private key corresponding to the client_id in the kid header using the ES384 algorithm.

      • grant_type stringREQUIRED

        Possible values: client_credentials

Responses

  • 200

    Returned on token request success.

    Response headers:

    • Cache-Control string

      Possible values: no-store

    • Content-Type string

      Possible values: application/json

    • Pragma string

      Possible values: no-cache

    Response body:

    • Content-Type: application/json

      Issued access token.

      OBJECT PROPERTIES
      • access_token string

        The issued token that can be used for all endpoints as allowed by set scopes.

      • expires_in integer

        The number of seconds from the time the token is generated until it expires.

      • scope object<OAuth Scope>

        A space-delimited list of scopes of the issued token. There may be undocumented scopes in this list.

        The value of the scope parameter is a list of space-delimited, case-sensitive strings. If multiple scopes are specified, their order does not matter. Each string adds an additional access range to the requested scope.

        • att: Attachments
        • chn: Channels
        • evt: Events
        • lst: Lists
        • nu: Named Users
        • pln: Pipelines
        • psh: Push
        • sch: Schedules

      • token_type string

        The type of issued token.

        Possible values: Bearer

  • 400

    Token not generated.

    Response body:

    • Content-Type: application/json

      Token request error.

      OBJECT PROPERTIES
      • error stringREQUIRED

        Error code.

        Possible values: invalid_scope, invalid_request, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_client

      • error_description string

        A plain-text description of the error.

  • 401

    Unauthorized.

    Response headers:

    • WWW-Authenticate string

      The HTTP authentication methods that can be used to request an access token.

    Response body:

    • Content-Type: application/json

      Authentication via the Authorization request header failed.

      OBJECT PROPERTIES
      • error stringREQUIRED

        Error code.

        Possible values: invalid_client

      • error_description string

        A plain-text description of the error.

  • 406

    Not acceptable.

    Response body:

    • Content-Type: application/json

      Unsupported Accept header. The request only supports application/json, application/x-www-form-urlencoded, text/plain.

      OBJECT PROPERTIES
      • error stringREQUIRED

        Error code.

        Possible values: invalid_request

      • error_description string

        A plain-text description of the error.

Key verification

GET /verify/public_key/{kid}

Example key verification

GET /verify/public_key/8817e96 HTTP/1.1
Host: oauth2.asnapius.com
Accept: text/plain

HTTP/1.1 200 OK
Content-Type: application/x-pem-file
Cache-Control: max-age=600, must-revalidate

-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE7tcTz03ypC7PSPa73Cbgl7AbDDo+92eH
DWgjAi6vt1gmlHE35e+GhpcwbywBByOiooY+5bvfUHkc0aKy4R8VbBK0rYwlp8B+
fxyDr9Ye/oiUewMwwlp0z5AMPjgBUIKS
-----END PUBLIC KEY-----

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PublicKeyVerificationRequest request = PublicKeyVerificationRequest.newRequest("<kid>");
Response<String> response = client.execute(request);

require 'urbanairship'

UA = Urbanairship
app_key = '<application_key>'

oauth = UA::Oauth.new(
  client_id: '<client_id>',
  key: app_key,
  assertion_private_key: '<your_private_key>',
  scopes: ['psh', 'chn'], # Optional
  ip_addresses: ['23.74.131.15/22'], # Optional
  oauth_server: 'api.asnapieu.com' # Optional
)

public_key = oauth.verify_public_key('<key_id>')

Retrieve the public key of a key ID. Use oauth2.asnapius.com for Airship’s North American cloud site and oauth2.asnapieu.com for Airship’s European cloud site when when verifying an OAuth public key.

Path parameters:

  • kid stringREQUIRED
    The private key ID used to sign the token. Example: 8817e96

Responses

  • 200

    Returned on success with the public key for the given kid.

    Response headers:

    • Cache-Control string

      The response contains a Cache-Control header which must be respected.

    Response body:

    • Content-Type: application/x-pem-file

      Type: string

      The PEM-formatted public key.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/json

      Type: object

      The error includes as much information as possible to help you understand the reason for the failure.

Push

Send notifications or rich messages to supported channels, or validate JSON payloads.

Send a push

POST /api/push

Example

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

{
    "audience": {
        "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
    },
    "notification": {
        "alert": "Hello!"
    },
    "device_types": [ "ios" ]
}

HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078"
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PushPayload payload = PushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("9c36e8c7-5a73-47c0-9716-99fd3d4197d5"))
        .setNotification(Notifications.alert("Hello!"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .build();

PushRequest request = PushRequest.newRequest(payload);
Response<PushResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Push
)

client = BasicAuthClient(
    key="<app key>",
    secret="<master secret>"
)

push = Push(client)
push.audience = {'ios_channel': '9c36e8c7-5a73-47c0-9716-99fd3d4197d5'}
push.notification = {'alert': 'Hello!'}
push.device_types = ['ios']
push.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.or( UA.ios_channel('9c36e8c7-5a73-47c0-9716-99fd3d4197d5'))
push.notification = UA.notification(alert: 'Hello!')
push.device_types = UA.device_types(['ios'])
push.send_push

Example push with localizations

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

{
    "audience": {
        "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
    },
    "notification": {
        "alert": "Hello!"
    },
    "device_types": [ "ios" ]
}

HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078"
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PushPayload payload = PushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("9c36e8c7-5a73-47c0-9716-99fd3d4197d5"))
        .setNotification(Notifications.alert("Hello!"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .build();

PushRequest request = PushRequest.newRequest(payload);
Response<PushResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Push
)

client = BasicAuthClient(
    key="<app key>",
    secret="<master secret>"
)

push = Push(client)
push.audience = {'ios_channel': '9c36e8c7-5a73-47c0-9716-99fd3d4197d5'}
push.notification = {'alert': 'Hello!'}
push.device_types = ['ios']
push.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.or( UA.ios_channel('9c36e8c7-5a73-47c0-9716-99fd3d4197d5'))
push.notification = UA.notification(alert: 'Hello!')
push.device_types = UA.device_types(['ios'])
push.send_push

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

{
   "device_types": [ "ios", "android" ],
   "audience": {
      "tag": "needs_a_greeting",
      "group": "new_customer"
   },
   "notification": {
      "alert": "Hi!"
   },
   "localizations": [
       {
          "language": "de",
          "country": "AT",
          "notification": {
             "alert": "Grüss Gott"
          }
       },
       {
          "language": "de",
          "country": "DE",
          "notification": {
             "alert": "Guten Tag"
          }
       }
    ]
 }

HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078",
        "1cbfbfa2-08d1-92c2-7119-f8f7f670f5f6",
        "939c3796-a755-413b-a36b-3026b1f92df8"
    ],
    "localized_ids": [
       "1a38a2ba-c174-d32f-d01b-481a5d241934"
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Localization localization = Localization.newBuilder()
        .setCountry("AT")
        .setLanguage("de")
        .setNotification(Notifications.alert("Grüss Gott"))
        .build();

PushPayload payload = PushPayload.newBuilder()
        .setAudience(Selectors.or(Selectors.tagWithGroup("needs_a_greeting", "new_customer")))
        .addLocalization(localization)
        .setNotification(Notifications.alert("Hi!"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
        .build();

PushRequest request = PushRequest.newRequest(payload);
Response<PushResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Push
)

client = BasicAuthClient(
    key="<app key>",
    secret="<master secret>"
)

push = Push(client)
push.audience = {
    'tag': 'needs_a_greeting',
    'group': 'new_customer'
}
push.notification = {'alert': 'Hi!'}
push.localizations = [
    {
        'country': 'at',
        'language': 'de',
        'notification': {'alert': "Grüss Gott"}
    },
    {
        'country': 'de',
        'language': 'de',
        'notification': {'alert': "Guten Tag"}
    }
]
push.device_types = ['ios', 'android']
push.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.tag("needs_a_greeting", group:'new_customer')
push.notification = UA.notification(alert: 'Hi!')
push.device_types = UA.device_types(['ios'])
push.localizations = {
  "language": "de",
  "country": "AT",
  "notification": {
  "alert": "Grüss Gott"
  }
}
push.send_push

Example email being sent using Push API with template ID

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

{
    "audience": {
        "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
    },
    "notification": {
        "alert": "Hello!"
    },
    "device_types": [ "ios" ]
}

HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078"
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PushPayload payload = PushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("9c36e8c7-5a73-47c0-9716-99fd3d4197d5"))
        .setNotification(Notifications.alert("Hello!"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .build();

PushRequest request = PushRequest.newRequest(payload);
Response<PushResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Push
)

client = BasicAuthClient(
    key="<app key>",
    secret="<master secret>"
)

push = Push(client)
push.audience = {'ios_channel': '9c36e8c7-5a73-47c0-9716-99fd3d4197d5'}
push.notification = {'alert': 'Hello!'}
push.device_types = ['ios']
push.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.or( UA.ios_channel('9c36e8c7-5a73-47c0-9716-99fd3d4197d5'))
push.notification = UA.notification(alert: 'Hello!')
push.device_types = UA.device_types(['ios'])
push.send_push

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

{
   "device_types": [ "ios", "android" ],
   "audience": {
      "tag": "needs_a_greeting",
      "group": "new_customer"
   },
   "notification": {
      "alert": "Hi!"
   },
   "localizations": [
       {
          "language": "de",
          "country": "AT",
          "notification": {
             "alert": "Grüss Gott"
          }
       },
       {
          "language": "de",
          "country": "DE",
          "notification": {
             "alert": "Guten Tag"
          }
       }
    ]
 }

HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078",
        "1cbfbfa2-08d1-92c2-7119-f8f7f670f5f6",
        "939c3796-a755-413b-a36b-3026b1f92df8"
    ],
    "localized_ids": [
       "1a38a2ba-c174-d32f-d01b-481a5d241934"
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Localization localization = Localization.newBuilder()
        .setCountry("AT")
        .setLanguage("de")
        .setNotification(Notifications.alert("Grüss Gott"))
        .build();

PushPayload payload = PushPayload.newBuilder()
        .setAudience(Selectors.or(Selectors.tagWithGroup("needs_a_greeting", "new_customer")))
        .addLocalization(localization)
        .setNotification(Notifications.alert("Hi!"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
        .build();

PushRequest request = PushRequest.newRequest(payload);
Response<PushResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Push
)

client = BasicAuthClient(
    key="<app key>",
    secret="<master secret>"
)

push = Push(client)
push.audience = {
    'tag': 'needs_a_greeting',
    'group': 'new_customer'
}
push.notification = {'alert': 'Hi!'}
push.localizations = [
    {
        'country': 'at',
        'language': 'de',
        'notification': {'alert': "Grüss Gott"}
    },
    {
        'country': 'de',
        'language': 'de',
        'notification': {'alert': "Guten Tag"}
    }
]
push.device_types = ['ios', 'android']
push.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.tag("needs_a_greeting", group:'new_customer')
push.notification = UA.notification(alert: 'Hi!')
push.device_types = UA.device_types(['ios'])
push.localizations = {
  "language": "de",
  "country": "AT",
  "notification": {
  "alert": "Grüss Gott"
  }
}
push.send_push

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

{
    "audience": {
        "tag": "needs_a_greeting",
        "group": "new_customer"
    },
    "device_types": [
        "email"
    ],
    "notification": {
      "email": {
        "message_type": "commercial",
        "reply_to": "no-reply@airship.com",
        "sender_address": "team@airship.com",
        "sender_name": "Airship",
        "template": {
            "template_id": "876624ff-0120-4364-bf02-dba3d0cb5b85"
        }
      }
    }
}

HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "be97b696-8d6b-4aec-ac50-c9cfc4be57d6",
    "push_ids": [
        "72ce9ade-aa71-4fbe-b960-246f1a2ca9ee"
    ],
    "message_ids": [],
    "content_urls": [],
    "localized_ids": []
}

Send a push notification to a specified audience. The body of the request must be a Push object or an array of push objects.

Security:

Request body:

A single push object or an array of push objects.

  • Content-Type: application/json

    One of
    • Push Object

      A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

    • Array of Push Objects. array<Push Object>

      A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

      Min items: 1, Max items: 100

Responses

  • 202

    The push notification has been accepted for processing. The response contains push_id, message_id, and/or content_url arrays based on the type of push.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      A push response contains a list of identifiers for the notifications sent in the request.

      OBJECT PROPERTIES
      • content_urls array[string]

        An array of URLs where the push payload contains a landing page action.

      • localized_ids array[string]

        An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).

      • message_ids array[string]

        An array of message IDs, each uniquely identifying a Message Center message.

      • ok boolean

        Success.

      • operation_id string

        A unique string identifying the operation, useful for reporting and troubleshooting.

      • push_ids array[string]

        An array of push IDs, each uniquely identifying a push.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 429

    Too many requests hit the API too quickly. For example, if we are not ready to create a channel for this payload; e.g., it is rate limited. You should wait before retrying the channel creation.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate a push

POST /api/push/validate

Example

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

{
    "audience": {
        "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
    },
    "notification": {
        "alert": "Hello!"
    },
    "device_types": [ "ios" ]
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PushPayload payload = PushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("9c36e8c7-5a73-47c0-9716-99fd3d4197d5"))
        .setNotification(Notifications.alert("Hello!"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .build();

PushRequest request = PushRequest.newRequest(payload).setValidateOnly(true);
Response<PushResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Push
)
from urbanairship.push.payload import notification, ios, android, web

client = BasicAuthClient(
    key="<app key>",
    secret="<master secret>"
)

push = Push(client)
push.audience = {'ios_channel': '9c36e8c7-5a73-47c0-9716-99fd3d4197d5'}
push.notification = notification(alert='Hello!')
push.device_types = ['ios']
push.validate()

Accept the same range of payloads as POSTing to /api/push, but parse and validate only, without sending any pushes. The body of the request must be a Push Object or an array of push objects.

Security:

Request body:

A single push object or an array of push objects.

  • Content-Type: application/json

    One of
    • Push Object

      A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

    • Array of Push Objects. array<Push Object>

      A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

      Min items: 1, Max items: 100

Responses

  • 200

    The payload was valid.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete multiple messages from inbox

POST /api/user/messages/batch-delete

Example

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

{
    "message_ids": [
        "drKa4OdxEeyhSwJC9TkdtQ",
        "W5ersOdxEeyvwAJCxz92iA"
    ]
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "deleted_message_ids": [
        "W5ersOdxEeyvwAJCxz92iA",
        "drKa4OdxEeyhSwJC9TkdtQ"
   ],
   "errors": []
}

HTTP/1.1 404 Not Found
Content-Type: application/vnd.urbanairship+json; version=3

{
    "deleted_message_ids": [],
    "errors": [
        {
            "message_id": "drKa4OdxEeyhSwJC9Tkdt1",
            "error_message": "Message not found.",
            "error_code": 40404
        },
        {
            "message_id": "W5ersOdxEeyvwAJCxz92i1",
            "error_message": "Message not found.",
            "error_code": 40404
        }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();
        
 List<String> arrayList = new ArrayList<>();
 arrayList.add("9dWD3LBIS5iZ51Y1GwOi4Q");
 arrayList.add("lsDtpTBJTN6KpQTwfOSNbw");

 InboxBatchDeleteRequest inboxBatchDeleteRequest = InboxBatchDeleteRequest.newRequest(arrayList);
 Response<InboxBatchDeleteResponse> response = client.execute(inboxBatchDeleteRequest);

Deletes multiple Message Center messages (up to 50 messages per request) completely, removing them from every user’s inbox. This is an asynchronous call; a success response means that the deletion has been queued for processing.

It is not possible to delete Message Center messages generated by an automation, a recurring message, or a Sequence.

Security:

Request body:

A request body containing an array of message IDs to be deleted.

  • Content-Type: application/json

    An array of message IDs, each uniquely identifying a Message Center message.

    OBJECT PROPERTIES
    • message_ids array[string]REQUIRED

      Array of Message IDs.

Responses

  • 202

    The request has been accepted for processing.

    Response body:

    • Content-Type: application/json
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete message from inbox

DELETE /api/user/messages/{push_id}

Example

DELETE /api/user/messages/(push_id) HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

 InboxDeleteRequest request = InboxDeleteRequest.newRequest("68b2d71f-1c10-4592-bd96-2725aee0ae57");
 Response<GenericResponse> response = client.execute(request);

from urbanairship import BasicAuthClient, Push

client = BasicAuthClient(
   key='<app_key>',
   secret='<master_secret>'
)

Push.message_center_delete(airship=client, push_id="941086fd-f7db-493b-a8a7-1f5a7dc6aae4")

Delete a Message Center message completely, removing it from every user’s inbox. This is an asynchronous call; a success response means that the deletion has been queued for processing.

This delete call will work with either the message_id or the push_id of the accompanying push notification.

This endpoint will not work with a group_id from an automated message or a push to local time delivery. To delete a rich message that was part of an automated or local time delivery, you must use the relevant push_id from the operation.

 Note

For time-sensitive messages, consider including an expiry time as detailed in the In-App Message Object. Setting an expiry value eliminates the need to manually remove messages.

Security:

Path parameters:

  • push_id stringREQUIRED
    The push_id or message_id of the Rich Message you want to delete from users` inboxes.

Responses

  • 202

    The request has been accepted for processing.

    Response body:

    • Content-Type: application/json
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedules

Schedule notifications.

List schedules

GET /api/schedules

Example

GET /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Count: 2
Data-Attribute: schedules
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "count": 2,
    "total_count": 4,
    "next_page": "https://go.urbanairship.com/api/schedules/?start=5c69320c-3e91-5241-fad3-248269eed104&limit=2&order=asc",
    "schedules": [
        {
            "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109",
            "schedule": { },
            "push": { }
        },
        {
            "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed10A",
            "schedule": { },
            "push": { }
        }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleListingRequest request = ScheduleListingRequest.newRequest();
Response<ListAllSchedulesResponse> response = client.execute(request);
List<SchedulePayloadResponse> schedules = response.getBody().get().getSchedules();

from urbanairship import BasicAuthClient, ScheduledList

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

for schedule in ScheduledList(client):
    print(
        schedule.name, schedule.url, schedule.push_ids,
        schedule.schedule, schedule.push
    )

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

scheduled_push_list = UA::ScheduledPushList.new(client: airship)
scheduled_push_list.each do |schedule|
    puts(schedule)
end

List all existing schedules. Returns an array of schedule objects in the schedules attribute.

Security:

Query parameters:

  • start string
    An optional string ID of the starting element for paginating results.
  • limit integer
    An optional integer as maximum number of elements to return. The default limit is 200 Schedule Objects per request. Set the limit to 200 or fewer in your API calls.

Responses

  • 200

    Returned on success, with the JSON representation of the scheduled pushes in the body of the response.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      Type: object

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedule a notification

POST /api/schedules

Example

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

[
  {
    "name": "Morning People",
    "schedule": {
        "scheduled_time": "2020-06-03T09:15:00"
    },
    "push": {
        "audience": { "tag": "earlyBirds" },
        "notification": { "alert": "Good Day Sunshine" },
        "device_types": [ "ios", "android" ]
    }
  },
  {
    "name": "Everybody Else",
    "schedule": {
        "best_time": {
          "send_date": "2020-06-03"
        }
    },
    "push": {
        "audience": { "tag": "normalPeople" },
        "notification": { "alert": "Stay Up Late" },
        "device_types": [ "ios", "android" ]
    }
  }
]

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SchedulePayload schedulePayload = SchedulePayload.newBuilder()
        .setName("Morning People")
        .setSchedule(Schedule.newBuilder()
                .setScheduledTimestamp(DateTime.parse("2020-06-03T09:15:00Z"))
                .build())
        .setPushPayload(PushPayload.newBuilder()
                .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
                .setNotification(Notifications.alert("Good Day Sunshine"))
                .setAudience(Selectors.tag("earlyBirds"))
                .build())
        .build();

ScheduleRequest scheduleRequest = ScheduleRequest.newRequest(schedulePayload);
Response<ScheduleResponse> response = client.execute(scheduleRequest);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, ScheduledPush, Push,
    tag, notification, scheduled_time
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Create the push payload
push = Push(client)
push.audience = tag('earlyBirds')
push.notification = notification(alert='Good Day Sunshine')
push.device_types = ['ios', 'android']

# Create the schedule
sched = ScheduledPush(client)
sched.name = 'Morning People'
sched.schedule = scheduled_time(datetime(2020, 6, 3, 9, 15, 0))
sched.push = push

# Send the scheduled push
response = sched.send()
print('Created schedule. URL:', response.schedule_url)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.tag('earlyBirds')
push.notification = UA.notification(alert: 'Morning People')
push.device_types = UA.device_types(['ios','android'])

schedule = airship.create_scheduled_push
schedule.push = push
schedule.name = "Morning People"
schedule.schedule = UA.scheduled_time(Time.now.utc + 60)
response = schedule.send_push
print ("Created schedule. url: " + response.schedule_url)

Example schedule with localizations

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

[
  {
    "name": "Morning People",
    "schedule": {
        "scheduled_time": "2020-06-03T09:15:00"
    },
    "push": {
        "audience": { "tag": "earlyBirds" },
        "notification": { "alert": "Good Day Sunshine" },
        "device_types": [ "ios", "android" ]
    }
  },
  {
    "name": "Everybody Else",
    "schedule": {
        "best_time": {
          "send_date": "2020-06-03"
        }
    },
    "push": {
        "audience": { "tag": "normalPeople" },
        "notification": { "alert": "Stay Up Late" },
        "device_types": [ "ios", "android" ]
    }
  }
]

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SchedulePayload schedulePayload = SchedulePayload.newBuilder()
        .setName("Morning People")
        .setSchedule(Schedule.newBuilder()
                .setScheduledTimestamp(DateTime.parse("2020-06-03T09:15:00Z"))
                .build())
        .setPushPayload(PushPayload.newBuilder()
                .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
                .setNotification(Notifications.alert("Good Day Sunshine"))
                .setAudience(Selectors.tag("earlyBirds"))
                .build())
        .build();

ScheduleRequest scheduleRequest = ScheduleRequest.newRequest(schedulePayload);
Response<ScheduleResponse> response = client.execute(scheduleRequest);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, ScheduledPush, Push,
    tag, notification, scheduled_time
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Create the push payload
push = Push(client)
push.audience = tag('earlyBirds')
push.notification = notification(alert='Good Day Sunshine')
push.device_types = ['ios', 'android']

# Create the schedule
sched = ScheduledPush(client)
sched.name = 'Morning People'
sched.schedule = scheduled_time(datetime(2020, 6, 3, 9, 15, 0))
sched.push = push

# Send the scheduled push
response = sched.send()
print('Created schedule. URL:', response.schedule_url)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.tag('earlyBirds')
push.notification = UA.notification(alert: 'Morning People')
push.device_types = UA.device_types(['ios','android'])

schedule = airship.create_scheduled_push
schedule.push = push
schedule.name = "Morning People"
schedule.schedule = UA.scheduled_time(Time.now.utc + 60)
response = schedule.send_push
print ("Created schedule. url: " + response.schedule_url)

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

[
  {
    "name": "Greetings",
    "schedule": {
        "best_time": {
          "send_date": "2020-11-15"
        }
    },
    "push": {
        "device_types": [
          "ios",
          "android"
        ],
        "audience": {
          "tag": "needs_a_greeting",
          "group": "new_customer"
        },
        "notification": {
          "alert": "Hi!"
        },
        "localizations": [
          {
              "language": "de",
              "country": "AT",
              "notification": {
                "alert": "Grüss Gott"
              }
          },
          {
              "language": "de",
              "country": "DE",
              "notification": {
                "alert": "Guten Tag"
              }
          }
        ]
    }
  }
]

HTTP/1.1 201 Created
Data-Attribute: schedule_urls
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "operation_id": "efb18e92-9a60-6689-45c2-82fedab36399",
   "schedule_urls": [
        "https://go.urbanairship.com/api/schedules/eac2ace6-349a-41a2-b874-5496d7bf0100",
        "https://go.urbanairship.com/api/schedules/6c7c9bf5-cb2b-47cb-b27f-f85981391c4e"
    ],
    "schedule_ids": [
        "eac2ace6-349a-41a2-b874-5496d7bf0100",
        "6c7c9bf5-cb2b-47cb-b27f-f85981391c4e"
    ],
   "schedules": [
      {
         "url": "https://go.urbanairship.com/api/schedules/eac2ace6-349a-41a2-b874-5496d7bf0100",
         "schedule": {
            "scheduled_time": "2020-06-03T09:15:00"
         },
         "name": "Morning People",
         "push": {
            "audience": { "tag": "earlyBirds" },
            "notification": { "alert": "Good Day Sunshine" },
            "device_types": [ "ios", "android" ]
         },
         "push_ids": [ "83046227-9b06-4114-9f23-0df349792bbd" ]
      }
      {
          "url": "https://go.urbanairship.com/api/schedules/6c7c9bf5-cb2b-47cb-b27f-f85981391c4e",
          "schedule": {
            "best_time": {
              "send_date": "2020-06-03"
            }
          },
          "name": "Everybody Else",
          "push": {
            "audience": { "tag": "normalPeople" },
            "notification": { "alert": "Stay Up Late" },
            "device_types": [ "ios", "android" ]
         },
         "push_ids": [ "8438e81-bb31-82a9-5feb-e7fd5b21ca7e" ]
      }
   ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Localization one = Localization.newBuilder()
        .setCountry("AT")
        .setLanguage("de")
        .setNotification(Notifications.alert("Grüss Gott"))
        .build();

Localization two = Localization.newBuilder()
        .setCountry("DE")
        .setLanguage("de")
        .setNotification(Notifications.alert("Guten Tag"))
        .build();

SchedulePayload schedulePayload = SchedulePayload.newBuilder()
        .setName("Greetings")
        .setSchedule(Schedule.newBuilder()
                .setBestTime(BestTime.newBuilder()
                        .setSendDate(DateTime.parse("2020-11-15T00:00:00Z"))
                        .build())
                .build())
        .setPushPayload(PushPayload.newBuilder()
                .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
                .setNotification(Notifications.alert("Hi!"))
                .setAudience(Selectors.tagWithGroup("needs_a_greeting", "new_customer"))
                .addLocalization(one)
                .addLocalization(two)
                .build())
        .build();

ScheduleRequest scheduleRequest = ScheduleRequest.newRequest(schedulePayload);
Response<ScheduleResponse> response = client.execute(scheduleRequest);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, ScheduledPush, Push,
    tag_group, notification, best_time,
    localization
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Create the push payload
push = Push(client)
push.audience = tag_group('new_customer', 'needs_a_greeting')
push.notification = notification(alert='Hi!')
push.device_types = ['ios', 'android']
push.localizations = [
    localization(
        country='AT',
        language='de',
        notification=notification(alert='Grüss Gott')
    ),
    localization(
        country='DE',
        language='de',
        notification=notification(alert='Guten Tag')
    )
]

# Create the schedule
sched = ScheduledPush(client)
sched.name = 'Greetings'
sched.schedule = best_time(send_date=datetime(2020, 11, 15))
sched.push = push

# Send the scheduled push
response = sched.send()
print('Created schedule. URL:', response.schedule_url)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.tag('needs_a_greeting', group:'new_customer')
push.notification = UA.notification(alert: 'Hi!')
push.device_types = UA.device_types(['ios', 'android'])
push.localizations = {
  "language": "de",
  "country": "AT",
  "notification": {
  "alert": "Grüss Gott"
  }
}

schedule = airship.create_scheduled_push
schedule.push = push
schedule.name = "Greetings"
schedule.schedule = UA.scheduled_time(Time.now.utc + 60)
response = schedule.send_push
print ("Created schedule. url: " + response.schedule_url)

Scheduled notifications are created by POSTing to the schedule URI. The body of the request must be one of a single schedule object or an array of one or more schedule objects.

Security:

Request body:

A single schedule object or an array of schedule objects. For Local Time Delivery, include no more than 100 Schedule Objects in your batch request.

  • Content-Type: application/json

    One of
    • array<Schedule Object>

      A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.

      Max items: 1000

    • Schedule Object

      A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.

Responses

  • 201

    The response body will contain an array of response objects with the created resource URIs.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      Type: object

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List a specific schedule

GET /api/schedules/{schedule_id}

Example

GET /api/schedules/5cde3564-ead8-9743-63af-821e12337812 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "name": "I would like to subscribe to your newsletter",
   "schedule": {
      "scheduled_time": "2020-04-01T18:45:30"
   },
   "push": {
      "audience": {
         "tag": [
            "intriguing",
            "ideas"                       ]
      },
      "notification": {
         "alert": "Check your inbox!"
      },
      "device_types": [ "ios", "android" ]
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleListingRequest request = ScheduleListingRequest.newRequest("5cde3564-ead8-9743-63af-821e12337812");
Response<ListAllSchedulesResponse> response = client.execute(request);
SchedulePayloadResponse schedule = response.getBody().get().getSchedules().get(0);
// Get the schedule's name
Optional<String> name = schedule.getName();
// Get the push IDs
Set<String> pushIds = schedule.getPushIds();
// Get the scheduled time
Schedule sched = schedule.getSchedule();
// Get the associated push payload
PushPayload payload = schedule.getPushPayload();
// Get the URL
Optional<String> url = schedule.getUrl();

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

schedule = airship.create_scheduled_push
scheduled_push = UA::ScheduledPush.new(airship)
schedule_details = scheduled_push.list(schedule_id: '5cde3564-ead8-9743-63af-821e12337812')
puts(schedule_details)

Fetch the current definition of a single schedule resource. Returns a single schedule object.

Security:

Path parameters:

  • schedule_id stringREQUIRED
    The ID of a schedule.

Responses

  • 200

    A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update schedule

PUT /api/schedules/{schedule_id}

Example

PUT /api/schedules/5cde3564-ead8-9743-63af-821e12337812 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "name": "I would like to subscribe to your newsletter",
   "schedule": {
      "scheduled_time": "2020-04-01T18:45:30"
   },
   "push": {
      "audience": {
         "tag": [
            "intriguing",
            "ideas",
            "thought_leadership"
         ]
      },
      "notification": {
         "alert": "Check your inbox!"
      },
      "device_types": [ "ios", "android" ]
   }
}

HTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "7c56d013-5599-d66d-6086-6205115d85e2",
    "schedule_urls": [ "https://go.urbanairship.com/api/schedules/0af1dead-e769-4b78-879a-7c4bb52d7c9e" ],
    "schedules": [
        {
            "url": "https://go.urbanairship.com/api/schedules/0af1dead-e769-4b78-879a-7c4bb52d7c9e",
            "schedule": {
                "scheduled_time": "2020-04-01T18:45:30"
            },
            "name": "I would like to subscribe to your newsletter",
            "push": {
                "audience": {"tag": ["intriguing", "ideas", "thought_leadership"] },
                "notification": {"alert": "Check your inbox!"},
                "device_types": [ "ios", "android" ]
            },
            "push_ids": [ "48fb8e8a-ee51-4e2a-9a47-9fab9b13d846" ]
        }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SchedulePayload schedulePayload = SchedulePayload.newBuilder()
        .setName("I would like to subscribe to your newsletter")
        .setSchedule(Schedule.newBuilder()
                .setScheduledTimestamp(DateTime.parse("2020-04-01T18:45:00Z"))
                .build())
        .setPushPayload(PushPayload.newBuilder()
                .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
                .setNotification(Notifications.alert("Check your inbox!"))
                .setAudience(Selectors.tag("intriguing"))
                .build())
        .build();

ScheduleRequest scheduleRequest = ScheduleRequest.newUpdateRequest(schedulePayload, "5cde3564-ead8-9743-63af-821e12337812");
Response<ScheduleResponse> response = client.execute(scheduleRequest);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, ScheduledPush, Push,
    tag, notification, scheduled_time
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
schedule = ua.ScheduledPush.from_url(client, 'https://go.urbanairship.com/api/schedules/5cde3564-ead8-9743-63af-821e12337812')

# change scheduled time to tomorrow
schedule.schedule = scheduled_time(datetime.datetime.utcnow() + datetime.timedelta(days=1))
resp = schedule.update()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

schedule = airship.create_scheduled_push
schedule = UA::ScheduledPush.from_url(client: airship, url: 'https://go.urbanairship.com/api/schedules/5cde3564-ead8-9743-63af-821e12337812')
# change scheduled time to tomorrow
schedule.schedule = UA.scheduled_time(Time.now.utc + (60 * 60 * 24))
schedule.update

Update the state of a single schedule resource. The body must contain a single schedule object. A PUT cannot be used to create a new schedule; it can only be used to update an existing one. A push to local time schedule cannot be updated once it has begun sending pushes to a time zone.

Security:

Path parameters:

  • schedule_id stringREQUIRED
    The ID of a schedule.

Request body:

A single schedule object.

  • Content-Type: application/json

    Schedule object

    A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.

Responses

  • 200

    Returned if the scheduled push has been successfully updated.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      Type: object

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 409

    Returned if the local time scheduled push is in progress.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete schedule

DELETE /api/schedules/{schedule_id}

Example

DELETE /api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 204 No Content

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleDeleteRequest request = ScheduleDeleteRequest.newRequest("b384ca54-0a1d-9cb3-2dfd-ae5964630e66");
Response<GenericResponse> response = client.execute(request);

from urbanairship import BasicAuthClient, ScheduledPush

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
schedule = ScheduledPush.from_url(client, 'https://go.urbanairship.com/api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66')

# Cancel schedule
schedule.cancel()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

schedule = airship.create_scheduled_push
schedule = UA::ScheduledPush.from_url(client: airship, url: 'https://go.urbanairship.com/api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66')
schedule.cancel

Delete a schedule resource, which will result in no more pushes being sent. If the resource is successfully deleted, the response does not include a body.

Security:

Path parameters:

  • schedule_id stringREQUIRED
    The ID of a schedule.

Responses

  • 204

    An API request was successful, but there is no response body to return.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Pause a schedule

POST /api/schedules/{schedule_id}/pause

Example

POST /api/schedules/5cde3564-ead8-9743-63af-821e12337812/pause HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleStatusRequest pauseRequest = ScheduleStatusRequest.pauseScheduleRequest("68b2d71f-1c10-4592-bd96-2725aee0ae57");
Response<GenericResponse> pauseResponse = client.execute(pauseRequest);      

from urbanairship import BasicAuthClient, ScheduledPush

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

sched = ScheduledPush(client)
sched.url = "http://go.urbanairship/api/schedules/5cde3564-ead8-9743-63af-821e12337812"

sched.pause()

Pause a recurring scheduled message, preventing Airship from sending messages on a recurring scheduled message interval. Use the /resume endpoint to resume a schedule. The pause operation cannot be completed for recurring schedules that have schedule end times in the past.

 Note

Paused schedules bear a "paused": true boolean.

Security:

Path parameters:

  • schedule_id stringREQUIRED
    The ID of the schedule you want to pause.

Request body:

A pause request is empty.

  • Content-Type: application/json

    Type: object

Responses

  • 204

    An API request was successful, but there is no response body to return.

  • 400

    Returned if the schedule end time for a recurring schedule is in the past.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 500

    Occurs if a schedule fails to pause. The error includes a list of failed_triggers, detailing the schedule triggers that caused this operation to fail.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • error string

        A description of the error.

      • error_code integer

        An error code representing the HTTP status and a more specific Airship error, if known.

      • failed_triggers array[object]
      • ok boolean

        If false, an error occurred.

Resume a schedule

POST /api/schedules/{schedule_id}/resume

Example

POST /api/schedules/5cde3564-ead8-9743-63af-821e12337812/resume HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleStatusRequest resumeRequest = ScheduleStatusRequest.resumeScheduleRequest("68b2d71f-1c10-4592-bd96-2725aee0ae57");
Response<GenericResponse> resumeResponse = client.execute(resumeRequest);

from urbanairship import BasicAuthClient, ScheduledPush

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

sched = ScheduledPush(client)
sched.url = "http://go.urbanairship/api/schedules/5cde3564-ead8-9743-63af-821e12337812"

sched.resume()

Resume a recurring schedule that you previously paused, beginning with the next scheduled interval. The resume operation cannot be completed for recurring schedules that have schedule end times in the past.

 Note

Paused schedules bear a "paused": true boolean.

Security:

Path parameters:

  • schedule_id stringREQUIRED
    The ID of the schedule you want to resume.

Request body:

A resume request is empty.

  • Content-Type: application/json

    Type: object

Responses

  • 204

    An API request was successful, but there is no response body to return.

  • 400

    Returned if the schedule end time is in the past.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 500

    Occurs if a schedule fails to resume. The error includes a list of failed_triggers, detailing the specific schedule IDs that caused the operation to fail.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • error string

        A description of the error.

      • error_code integer

        An error code representing the HTTP status and a more specific Airship error, if known.

      • failed_triggers array[object]
      • ok boolean

        If false, an error occurred.

Automation

Manage Automated notifications using the /api/pipelines endpoints.

List existing pipelines

GET /api/pipelines

Example

GET /api/pipelines/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "pipelines": [
      {
          "creation_time": "2020-03-20T18:37:23",
          "enabled": true,
          "immediate_trigger": {
            "tag_added": { "tag": "bought_shoes" }
          },
          "last_modified_time": "2020-03-20T19:35:12",
          "name": "Shoe buyers",
          "outcome": {
            "push": {
                "audience": "triggered",
                "device_types": [ "android" ],
                "notification": { "alert": "So you like shoes, huh?" }
            }
          },
          "status": "live",
          "uid": "3987f98s-89s3-cx98-8z89-89adjkl29zds",
          "url": "https://go.urbanairship.com/api/pipelines/3987f98s-89s3-cx98-8z89-89adjkl29zds"
      },
      {
          "..."
      }
    ]
}

from urbanairship import (
    BasicAuthClient, Automation
)
from urbanairship.automation.pipeline import Pipeline

client = BasicAuthClient(
    key='<app key>',
    secret='<master secret>'
)
automation = Automation(client)

for pipeline in automation.list_automations():
    print(pipeline)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

automation = UA::Automation.new(client: airship)
automation.limit = 5
automation.list_automations

List existing pipelines. Pipelines are ordered by creation_date from newest to oldest.

Security:

Query parameters:

  • limit integer
    The maximum number of results to return. This is effectively the page size for the response. No default limit. For maximum performance, set your limit between 25 and 100.

    Min: 1

  • enabled boolean
    If true, limits the listing to enabled pipelines ("enabled": true). If false or omitted, lists all pipelines, whether enabled is true or false.
  • offset integer
    The first result you want to return. This parameter assists in pagination.

Responses

  • 200

    Returned on success, with a JSON representation of pipelines matching your query parameters.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      Type: object

      The response body for a pipelines request.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create pipeline (automated message)

POST /api/pipelines

Example

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

{
    "name":"The Darkest Pipeline",
    "enabled":true,
    "immediate_trigger":"first_open",
    "outcome":{
      "push":{
          "audience":"triggered",
          "device_types":[
            "ios",
            "android",
            "web"
          ],
          "notification":{
            "alert":"Cool goatee, Abed"
          }
      }
    },
    "timing":{
      "delay":{
          "seconds":7200
      },
      "schedule":{
          "type":"local",
          "miss_behavior":"wait",
          "dayparts":[
            {
                "days_of_week":[
                  "thursday"
                ],
                "allowed_times":[
                  {
                      "preferred":"21:30:00"
                  }
                ]
            }
          ]
      }
    }
}

HTTP/1.1 201 Created
Content-Length: 123
Data-Attribute: pipeline_urls
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
    "pipeline_urls": [
      "https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
    ]
}

from urbanairship import (
    BasicAuthClient, Automation
)
from urbanairship.automation.pipeline import Pipeline

client = BasicAuthClient(
    key='<app key>',
    secret='<master secret>'
)
automation = Automation(client)

pipeline = Pipeline(
    name='The Darkest Pipeline',
    enabled=True,
    immediate_trigger='first_open',
    outcome={
        'push': {
            'audience': 'triggered',
            'device_types': ['ios', 'android', 'web'],
            'notification': {'alert': 'Cool goatee, Abed'}
        }
    },
    timing={
        'delay': {'seconds': 7200},
        'schedule': {
            'type': 'local',
            'miss_behavior': 'wait',
            'dayparts': [{
                'days_of_week': ['thursday'],
                'allowed_times': [
                    {'preferred': '21:30:00'}
                ]
            }]
        }
    }
)
response = automation.create(pipeline.payload)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

pipeline = UA::Pipeline.new(client: airship)
pipeline.enabled = true
pipeline.immediate_trigger = "first_open"
pipeline.outcome = {
    "push": {
        "audience": "triggered",
        "device_types": ['ios','android','web'],
        "notification": {
            "alert": "Cool goatee, Abed"
        }
    }
}
automation = UA::Automation.new(client: airship)
automation.pipeline_object = pipeline.payload
details = automation.create_automation
puts(details)

Create one or more pipelines. You can provide a single pipeline object or an array of pipeline objects.

Security:

Request body:

A single pipeline object or an array of pipeline objects.

  • Content-Type: application/json

    One of
    • Pipeline Object

      A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

    • array<Pipeline Object>

      A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

Responses

  • 201

    If creating more than one pipeline, pipeline URIs are returned in the same order as the pipeline objects in the request.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      Type: object

      The response body for a create pipeline request.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 409

    The request conflicts with another request.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List pipelines constraints

GET /api/pipelines/constraints

Example

GET /api/pipelines/constraints/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "constraints" : [
        {
            "rate" : {
                "pushes" : 30,
                "lifetimes" : 1
            }
        },
        {
            "rate" : {
                "pushes" : 15,
                "days" : 3
            }
        },
        {
            "rate" : {
                "pushes" : 4,
                "hours" : 6
            }
        }
    ]
}

Returns an array of cross-pipeline rate limit constraints. These are the rates that the combination of all pipelines for an app may not exceed.

Security:

Responses

  • 200

    Returns an array of cross-pipeline rate limit constraints.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • constraints array[object]

        An array of rate objects determining the maximum number of messages each audience member can receive over a period of time.

      • ok boolean

        Success.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update pipelines constraints

PUT /api/pipelines/constraints

Example

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

{
    "constraints" : [
        {
            "rate" : {
                "pushes" : 15,
                "days" : 3
            }
        },
        {
            "rate" : {
                "pushes" : 4,
                "hours" : 6
            }
        }
    ]
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

Update the pipelines constraints.

Security:

Request body:

An array of no more than 5 cross-pipeline rate limit constraints.

  • Content-Type: application/json

    OBJECT PROPERTIES
    • constraints array[object]

      An array of rate objects determining the maximum number of messages each audience member can receive over a period of time.

    • ok boolean

      Success.

Responses

  • 200

    Everything worked as expected.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List deleted pipelines

GET /api/pipelines/deleted

Example

GET /api/pipelines/deleted/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "pipelines": [
      {
          "deletion_time": "2020-03-31T20:54:45",
          "pipeline_id": "0sdicj23-fasc-4b2f-zxcv-0baf934f0d69"
      },
      {
          "..."
      }
    ]
}

from urbanairship import (
    BasicAuthClient, Automation
)
from urbanairship.automation.pipeline import Pipeline

client = BasicAuthClient(
    key='<app key>',
    secret='<master secret>'
)
automation = Automation(client)
response = automation.list_deleted_automations()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

automation = UA::Automation.new(client: airship)
automation.start = 2020-11-23
automation.list_deleted_automations

Produces a list of all deleted pipelines starting with the most recently deleted entry.

Security:

Query parameters:

  • start string
    The date-time of the starting element for paginating results.
  • limit integer
    The maximum number of elements to return.

Responses

  • 200

    Returns an array of deleted pipeline objects.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        Success.

      • pipelines array[object]

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List filtered pipelines

GET /api/pipelines/filtered

Lists all pipelines, which fulfill the provided filter criteria. Returns a response container, which contains an array of pipeline objects in the pipelines attribute. The response container also provides total count and links to the next page next_page and previous page prev_page, if applicable. We also always apply a sort order. By default we apply an ascending sort order on the name name field, but we also support a sort order on the started date started_date field. Pagination is always applied, which means that the pipeline result list is not the complete list of pipelines if the total count is greater than the page limit.

Security:

Query parameters:

  • start integer
    Non-negative zero-based index of the starting element for paginating results. Default value 0.

    Min: 1

  • limit integer
    The maximum number of results to return. This is effectively the page size for the response.

    Min: 1

  • enabled boolean
    If true, limits the listing to enabled pipelines. If false or omitted, lists all pipelines, whether enabled is true or false.
  • started_date_mills integer
    Limits the listing to only pipelines that were started after the specified date in milliseconds.
  • prefix string
    Search term, which is used as a prefix search term.
  • triggers string
    0 or more trigger types. The triggers filter limits the listing of pipelines by the specified trigger types. For example, if you specify REGION_EXITED and REGION_ENTERED, only pipelines that are associated with region entry and region exit triggers will be shown. If no trigger types are specified, no triggers filter will be applied and all pipelines will be listed.

    Possible values: TAG_ADDED, TAG_REMOVED, FIRST_REG, FIRST_OPT_IN, ACTIVITY, REGION_ENTERED, REGION_EXITED, CUSTOM_EVENT, SUBSCRIPTION_ADDED, SUBSCRIPTION_REMOVED

  • sort string
    Specifies the field, which should be sorted. Two fields are supported: name and started_date. If you omit the sort parameter, the default value name is used. If you provide an unknown field name, we will default to the name field.

    Possible values: name, started_date

  • order string
    Specifies the sort order as ascending (asc) or descending (desc). If you omit the order parameter, the default value asc is used.

    Possible values: asc, desc

Responses

  • 200

    Returned on success, with a JSON representation of pipelines matching your query parameters.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      Type: object

      The response body for a pipelines request.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List pipelines limits

GET /api/pipelines/limits

Example

GET /api/pipelines/limits/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "limits" : {
        "total_limit" : 50,
        "active_limit" : 20,
        "total_count" : 23,
        "active_count" : 7
    }
}

Return the currently configured limits for number of total and active pipelines, as well as the total and active counts.

Security:

Responses

  • 200

    Returns a JSON dictionary in the limits attribute.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • limits object
        OBJECT PROPERTIES
        • active_count integer

          An integer indicating the number of pipelines created by the application which are currently enabled.

        • active_limit integer

          An integer indicating the total number of active pipelines that the app is allowed to have.

        • total_count integer

          An integer indicating the total number of pipelines that currently exist for the application, regardless of their enabled state.

        • total_limit integer

          An integer indicating the total number of pipelines that the app is allowed to have, regardless of their enabled state.

      • ok boolean

        Success.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate pipeline

POST /api/pipelines/validate

Example

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

{
    "name":"The Darkest Pipeline",
    "enabled":true,
    "immediate_trigger":"first_open",
    "outcome":{
      "push":{
          "audience":"triggered",
          "device_types":[
            "ios",
            "android"
          ],
          "notification":{
            "alert":"Cool goatee, Abed"
          }
      }
    },
    "timing":{
      "delay":{
          "seconds":7200
      },
      "schedule":{
          "type":"local",
          "miss_behavior":"wait",
          "dayparts":[
            {
                "days_of_week":[
                  "thursday"
                ],
                "allowed_times":[
                  {
                      "preferred":"21:30:00"
                  }
                ]
            }
          ]
      }
    }
}

HTTP/1.1 200 OK
Content-Length: 11
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

from urbanairship import (
    BasicAuthClient, Automation
)
from urbanairship.automation.pipeline import Pipeline

client = BasicAuthClient(
    key='<app key>',
    secret='<master secret>'
)
automation = Automation(client)

pipeline = Pipeline(
    name='The Darkest Pipeline',
    enabled=True,
    immediate_trigger='first_open',
    outcome={
        'push': {
            'audience': 'triggered',
            'device_types': ['ios', 'android', 'web'],
            'notification': notification(alert='Cool goatee, Abed')
        }
    },
    timing={
        'delay': {'seconds': 7200},
        'schedule': {
            'type': 'local',
            'miss_behavior': 'wait',
            'dayparts': [{
                'days_of_week': ['thursday'],
                'allowed_times': [
                    {'preferred': '21:30:00'}
                ]
            }]
        }
    }
)
response = automation.validate(pipeline.payload)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

pipeline = UA::Pipeline.new(client: airship)
pipeline.enabled = true
pipeline.immediate_trigger = "first_open"
pipeline.outcome = {
    "push": {
        "audience": "triggered",
        "device_types": ['ios','android','web'],
        "notification": {
            "alert": "Cool goatee, Abed"
        }
    }
}
automation = UA::Automation.new(client: airship)
automation.pipeline_object = pipeline.payload
automation.validate_automation

This endpoint accepts the same range of payloads as a POST to /api/pipelines, but only parses and validates the payload, without creating the pipeline. The body of the request must be a single pipeline object or an array of pipeline objects.

Security:

Request body:

A single pipeline object or an array of pipeline objects.

  • Content-Type: application/json

    One of
    • Pipeline Object

      A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

    • Array of push templates array<Pipeline Object>

      A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

Responses

  • 200

    Everything worked as expected.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Individual pipeline lookup

GET /api/pipelines/{pipeline_id}

Example

GET /api/pipelines/4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "pipeline": {
      "creation_time": "2020-02-14T19:19:19",
      "enabled": true,
      "immediate_trigger": { "tag_added": "new_customer" },
      "last_modified_time": "2020-03-01T12:12:54",
      "name": "New customer",
      "outcome": {
          "push": {
            "audience": "triggered",
            "device_types": [ "ios", "android" ],
            "notification": { "alert": "Hello new customer!" }
          }
      },
      "status": "live",
      "uid": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
      "url": "https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
    }
}

from urbanairship import (
    BasicAuthClient, Automation
)
from urbanairship.automation.pipeline import Pipeline

client = BasicAuthClient(
    key='<app key>',
    secret='<master secret>'
)
automation = Automation(client)
pipeline = automation.lookup('4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

automation = UA::Automation.new(client: airship)
automation.pipeline_id = '4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4'
automation.lookup_automation

Fetch a single pipeline resource. Returns an array containing a single pipeline object in the pipeline attribute.

Security:

Path parameters:

  • pipeline_id stringREQUIRED
    The pipeline you want to return or modify.

Responses

  • 200

    Returned on success, with the JSON representation of the pipeline in the body of the response.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      Type: object

      The response body for a pipelines request.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update pipeline

PUT /api/pipelines/{pipeline_id}

Example

PUT /api/pipelines/0f927674-918c-31ef-51ca-e96fdd234da4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json;

{
    "enabled": true,
    "immediate_trigger": {
      "tag_added": "new_customer"
    },
    "outcome": {
      "push": {
          "audience": "triggered",
          "device_types": [
            "ios"
          ],
          "notification": {
            "alert": "Hello new customer!"
          }
      }
    }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

from urbanairship import (
    BasicAuthClient, Automation
)
from urbanairship.automation.pipeline import Pipeline

client = BasicAuthClient(
    key='<app key>',
    secret='<master secret>'
)
automation = Automation(client)

pipeline = Pipeline(
    enabled=True,
    immediate_trigger={
        'tag_added': 'new_customer'
    },
    outcome={
        'audience': 'triggered',
        'device_types': ['ios'],
        'notification': notification(alert='Hello new customer!')
    }
)
response = automation.update(
    pipeline_id='0f927674-918c-31ef-51ca-e96fdd234da4',
    pipeline=pipeline.payload
)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

pipeline = UA::Pipeline.new(client: airship)
pipeline.enabled = true
pipeline.immediate_trigger = {
  "tag_added": {
     "tag": "new_customer",
     "group": "crm"
    }
}
pipeline.outcome = {
  "push": {
     "audience": "triggered",
     "device_types": ["ios"],
     "notification": {
         "alert": "Hello new customer!"
        }
    }
}
automation = UA::Automation.new(client: airship)
automation.pipeline_id = '0f927674-918c-31ef-51ca-e96fdd234da4'
automation.pipeline_object = pipeline.payload
automation.update_automation

Update the state of a single pipeline resource. You must include the complete payload from a POST response, with changes you want to make to the resource. You cannot provide a partial payload. If you omit optional fields during this operation that were already set for the pipeline, they will be nullified.

Security:

Path parameters:

  • pipeline_id stringREQUIRED
    The pipeline you want to return or modify.

Request body:

A single pipeline object or an array of pipeline objects.

  • Content-Type: application/json

    Pipeline object

    A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

Responses

  • 200

    Returned if the pipeline has been successfully updated.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 409

    The request conflicts with another request.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete pipeline

DELETE /api/pipelines/{pipeline_id}

Example

DELETE /api/pipelines/0f927674-918c-31ef-51ca-e96fdd234da4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 204 No Content

from urbanairship import (
    BasicAuthClient, Automation
)
from urbanairship.automation.pipeline import Pipeline

client = BasicAuthClient(
    key='<app key>',
    secret='<master secret>'
)
automation = Automation(client)
response = automation.delete('0f927674-918c-31ef-51ca-e96fdd234da4')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

automation = UA::Automation.new(client: airship)
automation.pipeline_id = '0f927674-918c-31ef-51ca-e96fdd234da4'
automation.delete_automation

Delete a pipeline.

Security:

Path parameters:

  • pipeline_id stringREQUIRED
    The pipeline you want to return or modify.

Responses

  • 204

    An API request was successful, but there is no response body to return.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

A/B Tests

Create A/B Tests using the /api/experiments endpoint. An experiment or A/B test is a set of distinct push notification variants sent to subsets of an audience. You can create up to 26 notification variants and send each variant to an audience subset.

Experiment listing

GET /api/experiments

Example

GET /api/experiments HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: experiments
Count: 2
Total-Count: 2
Content-Type: application/vnd.urbanairship+json; version=3

 {
   "ok" : "true",
   "count" : 2,
   "total_count" : 2,
   "experiments" : [{
     "name" : "Experiment 1",
     "control" : 0.33,
     "audience" : "all",
     "device_types": [ "ios", "android" ],
     "variants" : [{
       "push" : {
         "notification" : {
           "alert" : "message 1"
         }
       },
       "id" : 0,
     },
     {
       "push" : {
           "notification" : {
             "alert" : "message 2"
           }
       },
       "id" : 1,
     }],
     "id" : "b5bc3dd1-9ea4-4208-b5f1-9e7ac3fe0502",
     "created_at" : "2020-03-03T21:08:05",
     "push_id" : "07cec298-6b8c-49f9-8e03-0448a06f4aac"
   }, {
     "name" : "Experiment 2",
     "description" : "The second experiment",
     "audience" : "all",
     "device_types": [ "ios", "android" ],
     "variants" : [{
       "push" : {
         "notification" : {
           "alert" : "message 1"
         }
       },
       "id" : 0,
     },
     {
       "push" : {
           "notification" : {
             "alert" : "message 2"
           }
       },
       "id" : 1,
     }],
     "id" : "e464aa7e-be40-4994-a290-1bbada7187d8",
     "created_at" : "2020-03-03T21:08:05",
     "push_id" : "07cec298-6b8c-49f9-8e03-0448a06f4aac"
   }]
}

from urbanairship import (
    BasicAuthClient, ABTest
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
ab_test = ABTest(airship=client)
response = ab_test.list_experiments()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

ab_test = UA::AbTest.new(client: airship)
ab_test.limit = 5
ab_test.list_ab_test

List experiments, sorted by created_at date-time from newest to oldest. Responses are paginated. Use optional limit and offset parameters to navigate results.

Security:

Query parameters:

  • limit integer
    Positive maximum number of elements to return per page. The default limit is 10 entries with a maximum of 100 entries.

    Min: 1

    Max: 100

  • offset integer
    A zero-based integer offset into the result set. If you do not use an offset, results will begin with the most recently sent experiment. If offset is greater than the number of queryable experiments, an empty result will be returned.

Responses

  • 200

    Returned on success, with the JSON representation of the experiments in the body of the response.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • count integer

        The number of items returned in this page of results.

      • experiments array

        Experiment objects sorted by either created_at from newest to oldest. The number of objects will never exceed the limit specified in the request.

      • next_page string

        A relative URL leading to the next page of results. If there are no more results, next_page is absent.

      • ok booleanREQUIRED

        If true, the call was successful.

      • total_count integer

        The total number of results.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create experiment (A/B Test)

POST /api/experiments

Example

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

{
    "name": "Experiment 1",
    "audience": {"tag": "earlyBirds"},
    "device_types": [ "ios", "android" ],
    "variants": [
        {
            "push": {
                "notification": {
                    "alert": "message 1"
                }
            }
        },
        {
            "push": {
                "notification": {
                    "alert": "message 2"
                }
            }
        }
    ]
}

HTTP/1.1 201 Created
Content-Length: 123
Location: https://go.urbanairship.com/api/experiments/0f7704e9-5dc0-4f7d-9964-e89055701b0a
Content-Type: application/vnd.urbanairship+json; version=3

  {
    "ok" : "true",
    "operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4",
    "experiment_id" : "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
    "push_id" : "7e13f060-594c-11e4-8ed6-0800200c9a66"
  }

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Schedule schedule = Schedule.newBuilder()
        .setScheduledTimestamp(DateTime.now().plusMinutes(5))
        .build();

Variant variantOne = Variant.newBuilder()
        .setPushPayload(VariantPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("message 1")
                .build()
        )
        .build())
        .setSchedule(schedule)
        .build();

Variant variantTwo = Variant.newBuilder()
        .setPushPayload(VariantPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("message 2")
                .build()
        )
        .build())
        .setSchedule(schedule)
        .build();

Experiment experiment = Experiment.newBuilder()
        .setName("Experiment 1")
        .setDescription("Testing description")
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
        .setAudience(Selectors.tag("earlyBirds"))
        .addVariant(variantOne)
        .addVariant(variantTwo)
        .build();

ExperimentRequest request = ExperimentRequest.newRequest(experiment);
Response<ExperimentResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, ABTest, Experiment, Variant
)
from urbanairship.push import notification

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Create push notifications for variants
push_1 = notification(alert='message 1')
push_2 = notification(alert='message 2')

# Create variants
variants = [
    Variant(push=push_1),
    Variant(push=push_2)
]

# Create experiment
experiment = Experiment(
    audience={'tag': 'earlyBirds'},
    device_types=['ios', 'android'],
    variants=variants,
    name='Experiment 1'
)

# Create and send experiment
ab_test = ABTest(airship=client)
response = ab_test.create(experiment=experiment)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

variant_one = UA::Variant.new(client: airship)
variant_one.push = {
    "notification": {
        "alert": "message 1"
    }
}
variant_two = UA::Variant.new(client: airship)
variant_two.push = {
    "notification": {
        "alert": "message 2"
    }
}
experiment = UA::Experiment.new(client: airship)
experiment.name = 'Experiment 1'
experiment.description = 'Example experiment'
experiment.audience = UA.tag('earlyBirds')
experiment.device_types = ['ios','android']
experiment.variants << variant_one.payload
experiment.variants << variant_two.payload
ab_test = UA::AbTest.new(client: airship)
ab_test.experiment_object = experiment.payload
ab_test.create_ab_test

Create an experiment. The body of the request should consist of a single experiment object. The experiment is processed and sent immediately unless a schedule is present.

Security:

Request body:

  • Content-Type: application/json

    Experiment object

    An experiment object describes an A/B test, including the audience and variant portions.

Responses

  • 201

    The experiment was created.

    Response headers:

    • Location string

      The newly created experiment.

    Response body:

    • Content-Type: application/json

      The response body for an experiment request.

      OBJECT PROPERTIES
      • experiment_id string

        Unique identifier for an experiment.

      • ok booleanREQUIRED

        If true, the experiment was successfully created. If false, the experiment was not created.

      • operation_id string

        A unique string that represents a single API call, used to identify the operation or side effects in reporting and troubleshooting logs.

      • push_id string

        Unique identifier for a push.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Scheduled experiment listing

GET /api/experiments/scheduled

Example

GET /api/experiments/scheduled HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: experiments
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": "true",
    "count": 2,
    "total_count": 2,
    "experiments": [
        {
            "id": "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
            "name": "Experiment 1",
            "audience": "all",
            "device_types": [ "ios", "android" ],
            "variants": [
                {
                    "id": 0,
                    "schedule": {
                        "scheduled_time": "2020-11-17T20:58:00Z"
                    },
                    "push": {
                        "notification": {
                            "alert": "message 1"
                        }
                    }
                },
                {
                    "id": 1,
                    "schedule": {
                        "scheduled_time": "2020-11-17T20:58:00Z"
                    },
                    "push": {
                        "notification": {
                            "alert": "message 2"
                        }
                    }
                }
            ]
        },
        {
            "id": "29705c10-5951-11e4-8ed6-0800200c9a66",
            "name": "Experiment 2",
            "audience": "all",
            "device_types": [ "ios", "android" ],
            "variants": [
                {
                    "id": 0,
                    "schedule": {
                        "scheduled_time": "2020-12-17T20:58:00Z"
                    },
                    "push": {
                        "notification": {
                            "alert": "message 1"
                        }
                    }
                },
                {
                    "id": 1,
                    "schedule": {
                        "scheduled_time": "2020-12-17T20:58:00Z"
                    },
                    "push": {
                        "notification": {
                            "alert": "message 2"
                        }
                    }
                }
            ]
        }
    ]
}

from urbanairship import (
    BasicAuthClient, ABTest
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
ab_test = ABTest(client)
response = ab_test.list_scheduled_experiment()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

ab_test = UA::AbTest.new(client: airship)
ab_test.list_scheduled_ab_test

List scheduled experiments in order, from closest to the current date-time to farthest (i.e., the experiments scheduled to occur soonest will appear at the top of the list). Responses are paginated, using optional limit and offset parameters.

Security:

Query parameters:

  • limit integer
    Positive maximum number of elements to return per page. The default limit is 10 entries with a maximum of 100 entries.

    Min: 1

    Max: 100

  • offset integer
    A zero-based integer offset into the result set. If you do not use an offset, results will begin with experiment scheduled to begin at the soonest date-time. If the offset is greater than the number of queryable experiments, the result set will be empty.

Responses

  • 200

    Returned on success, with the JSON representation of the experiments in the body of the response.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • count integer

        The number of items in this page of results.

      • experiments array

        Experiments listed by scheduled_time in ascending time order. The number of objects will never exceed the limit specified in the request.

      • next_page string

        A relative URL leading to the next page of results. If there are no more results, next_page is absent.

      • ok booleanREQUIRED

        If true, the operation completed successfully and returns an expected result set.

      • total_count integer

        The total number of results.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete experiment

DELETE /api/experiments/scheduled/{experiment_id}

Example

DELETE /api/experiments/scheduled/0f7704e9-5dc0-4f7d-9964-e89055701b0a HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : "true",
  "operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ExperimentDeleteRequest request = ExperimentDeleteRequest.newRequest("0f7704e9-5dc0-4f7d-9964-e89055701b0a");
Response<ExperimentResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, ABTest
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

ab_test = ua.ABTest(client)
ab_test.experiment_id = "0f7704e9-5dc0-4f7d-9964-e89055701b0a"

response = ab_test.delete()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

ab_test = UA::AbTest.new(client: airship)
ab_test.experiment_id = '0f7704e9-5dc0-4f7d-9964-e89055701b0a'
ab_test.delete_ab_test

Delete a scheduled experiment. You can only delete experiments before they start; attempting to delete an experiment that has already started or completed will return an HTTP 405 response (“Method not allowed”).

Security:

Path parameters:

  • experiment_id stringREQUIRED
    The unique identifier of the experiment.

Responses

  • 200

    Returned if the experiment has been successfully deleted.

    Response body:

    • Content-Type: application/json

      The response body for a pipeline’s deletion request.

      OBJECT PROPERTIES
      • ok booleanREQUIRED

        Success.

      • operation_id string

        A unique string that represents a single API call, used to identify the operation or side effects in reporting and troubleshooting logs.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 405

    Returned when a request is made using an HTTP method not supported by the endpoint. For example, sending a DELETE to /api/schedules.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate experiment

POST /api/experiments/validate

Example

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

{
    "name": "Experiment 1",
    "audience": {"tag": "earlyBirds"},
    "device_types": [ "ios", "android" ],
    "variants": [
        {
            "push": {
                "notification": {
                    "alert": "message 1"
                }
            }
        },
        {
            "push": {
                "notification": {
                    "alert": "message 2"
                }
            }
        }
    ]
}

HTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : "true",
  "operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Schedule schedule = Schedule.newBuilder()
        .setScheduledTimestamp(DateTime.now().plusMinutes(5))
        .build();

Variant variantOne = Variant.newBuilder()
        .setPushPayload(VariantPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("message 1")
                .build()
        )
        .build())
        .setSchedule(schedule)
        .build();

Variant variantTwo = Variant.newBuilder()
        .setPushPayload(VariantPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("message 2")
                .build()
        )
        .build())
        .setSchedule(schedule)
        .build();

Experiment experiment = Experiment.newBuilder()
        .setName("Experiment 1")
        .setDescription("Testing description")
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
        .setAudience(Selectors.tag("earlyBirds"))
        .addVariant(variantOne)
        .addVariant(variantTwo)
        .build();

ExperimentRequest request = ExperimentRequest.newRequest(experiment).setValidateOnly(true);
Response<ExperimentResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, ABTest, Experiment, Variant
)
from urbanairship.push import notification

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Create push notifications for variants
push_1 = notification(alert='message 1')
push_2 = notification(alert='message 2')

# Create variants
variants = [
    Variant(push=push_1),
    Variant(push=push_2)
]

# Create experiment
experiment = Experiment(
    audience={'tag': 'earlyBirds'},
    device_types=['ios', 'android'],
    variants=variants,
    name='Experiment 1'
)

# Validate experiment
ab_test = ABTest(airship=client)
response = ab_test.validate(experiment=experiment)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

variant_one = UA::Variant.new(client: airship)
variant_one.push = {
    "notification": {
        "alert": "message 1"
    }
}
variant_two = UA::Variant.new(client: airship)
variant_two.push = {
    "notification": {
        "alert": "message 2"
    }
}
experiment = UA::Experiment.new(client: airship)
experiment.name = 'Experiment 1'
experiment.description = 'Example experiment'
experiment.audience = UA.tag('earlyBirds')
experiment.device_types = ['ios','android']
experiment.variants << variant_one.payload
experiment.variants << variant_two.payload
ab_test = UA::AbTest.new(client: airship)
ab_test.experiment_object = experiment.payload
ab_test.validate_ab_test

Accepts the same range of payloads as /api/experiments, but only parses and validates the payload without creating the experiment. This does the same amount of validation as the creation endpoint, including platform-specific validation, e.g., APNs byte limit checks. While this operation ensures the experiment is technically valid, it does not guarantee that a resulting push will succeed. An experiment may validate and still fail to be delivered. For example, you may have a valid experiment with no devices in your audience.

Security:

Request body:

A single experiment object.

  • Content-Type: application/json

    Experiment object

    An experiment object describes an A/B test, including the audience and variant portions.

Responses

  • 200

    The experiment is valid.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • ok booleanREQUIRED

        If true, the operation completed successfully and returns an expected response.

      • operation_id string

        A unique string that represents a single API call, used to identify the operation or side effects in reporting and troubleshooting logs.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Experiment lookup

GET /api/experiments/{experiment_id}

Example

GET /api/experiments/0f7704e9-5dc0-4f7d-9964-e89055701b0a HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: experiment
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : "true",
   "experiment" : {
      "id" : "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
      "push_id": "d00f07b0-594c-11e4-8ed6-0800200c9a66",
      "name" : "Experiment 1",
      "audience" : "all",
      "device_types": [ "ios", "android" ],
      "variants" : [{
            "push" : {
               "notification" : {
                  "alert" : "message 1"
               }
            },
            "id" : 0,
         },
         {
            "push" : {
               "notification" : {
               "alert" : "message 2"
            }
         },
         "id" : 1,
     }]
   }
}

from urbanairship import BasicAuthClient, ABTest

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
ab_test = ABTest(client)
response = ab_test.lookup(experiment_id='0f7704e9-5dc0-4f7d-9964-e89055701b0a')

require 'urbanairship'
UA = Urbanairship

airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
ab_test = UA::AbTest.new(client: airship)

ab_test.experiment_id = '0f7704e9-5dc0-4f7d-9964-e89055701b0a'
ab_test.lookup_ab_test

Look up an experiment (A/B Test).

Security:

Path parameters:

  • experiment_id stringREQUIRED
    The ID of the experiment you want to look up.

Responses

  • 200

    Returned on success, with the JSON representation of the experiment in the body of the response.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • experiment object<Experiment object>

        An experiment object describes an A/B test, including the audience and variant portions.

      • ok booleanREQUIRED

        If true, the operation completed successfully and returns a result set.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Personalization

Use the /templates API to create templates and push templatized notifications.

List templates

GET /api/templates

Example

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

HTTP/1.1 200 OK
Data-Attribute: templates
Count: 1
Total-Count: 1
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "count": 1,
    "total_count": 1,
    "templates": [
        {
            "id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "created_at": "2020-08-17T11:10:01Z",
            "modified_at": "2020-08-17T11:10:01Z",
            "last_used": null,
            "name": "Welcome Message",
            "description": "Our welcome message",
            "variables": [
                {
                    "key": "TITLE",
                    "name": "Title",
                    "description": "e.g., Mr, Ms, Dr, etc.",
                    "default_value": ""
                },
                {
                    "key": "FIRST_NAME",
                    "name": "First Name",
                    "description": "Given name",
                    "default_value": null
                },
                {
                    "key": "LAST_NAME",
                    "name": "Last Name",
                    "description": "Family name",
                    "default_value": null
                }
            ],
            "push": {
                "notification": {
                    "alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
                }
            }
        }
    ],
    "next_page": null,
    "prev_page": null
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateListingRequest request = TemplateListingRequest.newRequest();
Response<TemplateListingRequest> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# List all templates
for template in TemplateList(client):
    print(
        f"Template ID: {template.template_id}\n"
        f"Created: {template.created_at}\n"
        f"Modified: {template.modified_at}\n"
        f"Last Used: {template.last_used}\n"
        f"Name: {template.name}\n"
        f"Description: {template.description}\n"
        f"Variables: {template.variables}\n"
        f"Push: {template.push}"
    )

List all existing templates. Returns an array of template objects in the templates attribute.

 Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

Query parameters:

  • page integer
    Specifies the desired page number. Defaults to 1.
  • page_size integer
    Specifies how many results to return per page. Has a default value of 25 and a maximum value of 100.
  • sort string
    Specifies the name of the field you want to sort results by. Defaults to created_at.

    Possible values: created_at, modified_at, last_used

  • order string
    Specifies the sort order as ascending (asc) or descending (desc). Defaults to asc.

    Possible values: asc, desc

Responses

  • 200

    Returned on success, with the JSON representation of the templates in the body of the response.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • count integer

        The number of templates in the current response; this is effectively the page size.

      • next_page string

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

      • ok booleanREQUIRED

        Success.

      • prev_page string

        Link to the previous page, if available.

      • templates array

        An array of template objects.

      • total_count integer

        The total number of templates.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create template

POST /api/templates

Example

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

{
    "name": "Welcome Message",
    "description": "Our welcome message",
    "variables": [
        {
            "key": "TITLE",
            "name": "Title",
            "description": "e.g., Mr, Ms, Dr, etc.",
            "default_value": ""
        },
        {
            "key": "FIRST_NAME",
            "name": "First Name",
            "description": "Given name",
            "default_value": null
        },
        {
            "key": "LAST_NAME",
            "name": "Last Name",
            "description": "Family name",
            "default_value": null
        }
    ],
    "push": {
        "notification": {
            "alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
        }
    }
}

HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "operation_id" : "9ce808c8-7176-45dc-b79e-44aa74249a5a",
    "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateVariable titleVariable = TemplateVariable.newBuilder()
        .setKey("TITLE")
        .setName("Title")
        .setDescription("e.g., Mr, Ms, Dr, etc.")
        .setDefaultValue("")
        .build();

TemplateVariable firstNameVariable = TemplateVariable.newBuilder()
        .setKey("FIRST_NAME")
        .setName("First Name")
        .setDescription("Given name")
        .setDefaultValue(null)
        .build();

TemplateVariable lastNameVariable = TemplateVariable.newBuilder()
        .setKey("LAST_NAME")
        .setName("Last Name")
        .setDescription("Family name")
        .setDefaultValue("")
        .build();

PartialPushPayload partialPushPayload = PartialPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("Hello {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!")
                .build()
        )
        .build();

TemplateRequest request = TemplateRequest.newRequest()
        .setName("Welcome Message")
        .setDescription("Our welcome message")
        .addVariable(titleVariable)
        .addVariable(firstNameVariable)
        .addVariable(lastNameVariable)
        .setPush(partialPushPayload);

Response<TemplateResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Create a new template
template = Template(client)
template.name = 'Welcome Message'
template.description = 'Our welcome message'
template.variables = [
    {
        'key': 'TITLE',
        'name': 'Title',
        'description': 'e.g., Mr., Ms., Dr., etc.',
        'default_value': ''
    },
    {
        'key': 'FIRST_NAME',
        'name': 'First Name',
        'description': 'Given name',
        'default_value': None
    },
    {
        'key': 'LAST_NAME',
        'name': 'Last Name',
        'description': 'Family name',
        'default_value': None
    }
]
template.push = {
    'notification': {
        'alert': 'Hello {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!'
    }
}
response = template.create()
print(f"Template ID: {template.template_id}")  # To get the template ID for future use

# List all templates
for template in TemplateList(client):
    print(
        f"Template ID: {template.template_id}\n"
        f"Created: {template.created_at}\n"
        f"Modified: {template.modified_at}\n"
        f"Last Used: {template.last_used}\n"
        f"Name: {template.name}\n"
        f"Description: {template.description}\n"
        f"Variables: {template.variables}\n"
        f"Push: {template.push}"
    )

# Send a push using a template
push = client.create_push()
push.device_types = ['ios']
push.audience = {
    'ios_channel': 'b8f9b663-0a3b-cf45-587a-be880946e881'
}
push.merge_data = merge_data(
    template_id='ef34a8d9-0ad7-491c-86b0-aea74da15161',
    substitutions={
        'FIRST_NAME': 'Bob',
        'LAST_NAME': 'Smith',
        'TITLE': ''
    }
)
response = push.send()

Create a new template.

 Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

Request body:

A single template object.

  • Content-Type: application/json

    Template object

    A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints.

Responses

  • 201

    The template was created.

    Response headers:

    • Location string

      The uri for the template, used for later updates or sends.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok booleanREQUIRED

        If true, the operation completed successfully and returns an expected response.

      • operation_id string

        A unique string identifying the operation, useful for reporting and troubleshooting.

      • template_id string

        A unique string identifying the template, used to call the template for pushing and other operations.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Push to template

POST /api/templates/push

Example

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": [ "ios" ],
    "audience": {
       "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    },
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "FIRST_NAME": "Bob",
            "LAST_NAME": "Smith",
            "TITLE": ""
        }
    }
}

HTTP/1.1 202 Accepted
Content-Length: 123
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "operation_id" : "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "1cbfbfa2-08d1-92c2-7119-f8f7f670f5f6"
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplatePushPayload payload = TemplatePushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("b8f9b663-0a3b-cf45-587a-be880946e881"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .setMergeData(TemplateSelector.newBuilder()
                .setTemplateId("ef34a8d9-0ad7-491c-86b0-aea74da15161")
                .addSubstitution("FIRST_NAME", "Bob")
                .addSubstitution("LAST_NAME", "Smith")
                .addSubstitution("TITLE", "Mr.")
                .build())
        .build();

TemplatePushRequest request = TemplatePushRequest.newRequest()
        .addTemplatePushPayload(payload);

Response<TemplateResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Send a push using a template
push = client.create_push()
push.device_types = ['ios']
push.audience = {
    'ios_channel': 'b8f9b663-0a3b-cf45-587a-be880946e881'
}
push.merge_data = merge_data(
    template_id='ef34a8d9-0ad7-491c-86b0-aea74da15161',
    substitutions={
        'FIRST_NAME': 'Bob',
        'LAST_NAME': 'Smith',
        'TITLE': ''
    }
)
response = push.send()

Send a push notification based on a template to a list of devices. The body of the request must be a single push template payload or an array of one or more push template payloads.

 Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

Request body:

A single push template payload or an array of push template payloads. Provide an override with any variable that has a null default value. For example, if you created a template with the variable FIRST_NAME, and that variable has null as a default value, you must provide a substitution for FIRST_NAME when pushing to that template.

  • Content-Type: application/json

    One of
    • Push Template Payload

      A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

    • Array of push templates array<Push Template Payload>

      A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

Responses

  • 202

    The push notification has been accepted for processing.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok booleanREQUIRED

        If true, the operation completed successfully and returns an expected response.

      • operation_id string

        A unique string identifying the operation, useful for reporting and troubleshooting.

      • push_ids array[string]

        An array of the push IDs for this operation.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate a template

POST /api/templates/push/validate

Example

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

{
    "device_types": [ "ios" ],
    "audience": {
       "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    },
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "FIRST_NAME": "Bob",
            "LAST_NAME": "Smith",
            "TITLE": ""
        }
    }
}

HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplatePushPayload payload = TemplatePushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("b8f9b663-0a3b-cf45-587a-be880946e881"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .setMergeData(TemplateSelector.newBuilder()
                .setTemplateId("ef34a8d9-0ad7-491c-86b0-aea74da15161")
                .addSubstitution("FIRST_NAME", "Bob")
                .addSubstitution("LAST_NAME", "Smith")
                .addSubstitution("TITLE", "Mr.")
                .build())
        .build();

TemplatePushRequest request = TemplatePushRequest.newRequest()
        .addTemplatePushPayload(payload)
        .setValidateOnly(true);

Response<TemplateResponse> response = client.execute(request);

This endpoint accepts the same range of payloads as /api/template/push, but only parses and validates the payload. It does not actually send a push.

Security:

Request body:

A single push template payload or an array of push template payloads.

  • Content-Type: application/json

    One of
    • Push Template Payload

      A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

    • array<Push Template Payload>

      A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

Responses

  • 200

    The payload was valid.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedule a templated push

POST /api/templates/schedules

Example

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

[
    {
        "name": "Hello Bob",
        "schedule": {
           "scheduled_time": "2020-05-02T22:00:00Z"
        },
        "device_types": [ "ios" ],
        "audience": {
           "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
        },
        "merge_data": {
            "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "substitutions": {
                "FIRST_NAME": "Bob",
                "LAST_NAME": "Takahashi",
                "TITLE": null
            }
        }
    },
    {
        "name": "Hello Joe",
        "schedule": {
           "scheduled_time": "2020-05-05T18:00:00Z"
        },
        "device_types": [ "android" ],
        "audience": {
           "android_channel": "df6a6b50-9843-0304-d5a5-743f246a4946"
        },
        "merge_data": {
            "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "substitutions": {
                "FIRST_NAME": "Joe",
                "LAST_NAME": "Smith",
                "TITLE": "Sir"
            }
        }
    }
]

HTTP/1.1 202 Accepted
Content-Length: 123
Data-Attribute: schedule_urls
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "operation_id" : "efb18e92-9a60-6689-45c2-82fedab36399",
    "schedule_urls" : [
        "http://go.urbanairship/api/schedules/a0cef4f9-1fcd-47ef-b459-01f432b64043",
        "http://go.urbanairship/api/schedules/fe2dab5e-f837-4707-8d0c-0e8c589ef4cf"
    ],
    "schedule_ids" : [
        "a0cef4f9-1fcd-47ef-b459-01f432b64043",
        "fe2dab5e-f837-4707-8d0c-0e8c589ef4cf"
    ],
    "schedules" : [
        {
            "url" : "http://go.urbanairship/api/schedules/a0cef4f9-1fcd-47ef-b459-01f432b64043",
            "name": "Hello Joe",
            "schedule" : { "..." },
            "push" : { "..." },
            "push_ids": [ "6a5ecb9c-46ee-4af4-9ced-9308121afaf9" ]
        },
        {
            "url" : "http://go.urbanairship/api/schedules/fe2dab5e-f837-4707-8d0c-0e8c589ef4cf",
            "name": "Hello Bob",
            "schedule" : { "..." },
            "push" : { "..." },
            "push_ids": [ "5162bbf8-7de7-4040-a64d-e018b71f02f6" ]
        }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateScheduledPushPayload payload = TemplateScheduledPushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("b8f9b663-0a3b-cf45-587a-be880946e881"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .setMergeData(TemplateSelector.newBuilder()
                .setTemplateId("ef34a8d9-0ad7-491c-86b0-aea74da15161")
                .addSubstitution("FIRST_NAME", "Bob")
                .addSubstitution("LAST_NAME", "Takahashi")
                .addSubstitution("TITLE", "Dr.")
                .build())
        .setSchedule(Schedule.newBuilder()
                .setScheduledTimestamp(DateTime.parse("2020-05-05T18:00:00Z"))
                .build())
        .build();

TemplateScheduledPushRequest request = TemplateScheduledPushRequest.newRequest()
                                          .addTemplateScheduledPushPayload(payload);
Response<ScheduleResponse> response = client.execute(request);

Schedule a push notification based on a template to a list of devices. Like a standard template-based push, the body of the request includes one or more push template payloads along with a schedule object determining when the template-based push should be sent.

Security:

Request body:

An array of scheduled pushes.

  • Content-Type: application/json

    array<object>
    ARRAY ITEM

    • A scheduled push template object defines a push by overriding the variables defined in a specific template object and the schedule determining when the push should be sent. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

      OBJECT PROPERTIES
      • audience object<Audience Selector1000>REQUIRED
        The audience for the template.
      • campaigns object<Campaigns Object>
      • device_types array[string]REQUIRED
        An array containing one or more strings identifying targeted platforms.
      • merge_data objectREQUIRED
        A template selector describing the template ID and variable substitutions to use with it.
      • name string
        An optional name for the scheduled push operation.
      • schedule object<Schedule Spec>REQUIRED
        Determines when the push is sent.

Responses

  • 202

    The scheduled push has been accepted for processing.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok booleanREQUIRED

        Success.

      • operation_id string

        A unique string which identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs.

      • schedule_ids array[string]

        An array of schedule IDs.

      • schedule_urls array[string]

        An array of schedule URLs. The URL for each schedule is the schedules endpoint, appended with the schedule_id of the schedule.

      • schedules array

        An array of schedule objects.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Look up a template

GET /api/templates/{template_id}

Example

GET /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Attribute: template
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "template": {
        "id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "created_at": "2020-08-17T11:10:02Z",
        "modified_at": "2020-08-17T11:10:02Z",
        "last_used": null,
        "name": "Welcome Message",
        "description": "Our welcome message",
        "variables": [
            {
                "key": "TITLE",
                "name": "Title",
                "description": "e.g., Mr, Ms, Dr, etc.",
                "default_value": ""
            },
            {
                "key": "FIRST_NAME",
                "name": "First Name",
                "description": "Given name",
                "default_value": null
            },
            {
                "key": "LAST_NAME",
                "name": "Last Name",
                "description": "Family name",
                "default_value": null
            }
        ],
        "push": {
            "notification": {
                "alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
            }
        }
    }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateListingRequest request = TemplateListingRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161");
Response<TemplateListingResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
template = Template(client).lookup(template_id)
print(
    template.template_id, template.created_at, template.modified_at,
    template.last_used, template.name, template.description,
    template.variables, template.push
)

Fetch the current definition of a single template.

 Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

Path parameters:

  • template_id stringREQUIRED
    A required string ID of the template.

Responses

  • 200

    Returned on success, with the JSON representation of the template in the body of the response.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok booleanREQUIRED

        If true, the operation completed successfully and returns an expected response.

      • template object<Template object>

        A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update template

POST /api/templates/{template_id}

Example

POST /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "name": "Welcome Message",
    "description": "Our welcome message",
    "push": {
        "notification": {
            "alert": "Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!"
        }
    }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

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

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PartialPushPayload partialPushPayload = PartialPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!")
                .build()
        )
        .build();

TemplateRequest request = TemplateRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161")
        .setName("Welcome Message")
        .setDescription("Our welcome message")
        .setPush(partialPushPayload);

Response<TemplateResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
updated_template = Template(client)
updated_template.push = {
    'notification': {
        'alert': 'Hi {{FIRST_NAME}} {{LAST_NAME}}!'
    }
}
response = updated_template.update(template_id)

Alternatively, call the lookup function on your updated template:

POST /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "name": "Welcome Message",
    "description": "Our welcome message",
    "push": {
        "notification": {
            "alert": "Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!"
        }
    }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

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

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PartialPushPayload partialPushPayload = PartialPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!")
                .build()
        )
        .build();

TemplateRequest request = TemplateRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161")
        .setName("Welcome Message")
        .setDescription("Our welcome message")
        .setPush(partialPushPayload);

Response<TemplateResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
updated_template = Template(client)
updated_template.push = {
    'notification': {
        'alert': 'Hi {{FIRST_NAME}} {{LAST_NAME}}!'
    }
}
response = updated_template.update(template_id)

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
updated_template = Template(client).lookup(template_id)
updated_template.push = {
    'notification': {
        'alert': 'Greetings {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}!'
    }
}
response = updated_template.update()

Update a template. The request body is a partially-defined template object, containing the field(s) you want to change and their updated values.

 Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

Path parameters:

  • template_id stringREQUIRED
    A required string ID of the template.

Request body:

  • Content-Type: application/json

    A partially-defined template object. Provide only variables and push items that you want to update.

    OBJECT PROPERTIES
    • description string

      The description of the template.

    • name stringREQUIRED

      The name of the template.

    • push object<Template push object>

      A partial push object describing everything about a push notification, except for the audience and device_types keys (which are defined in the Push template payload) and the message key (which is incompatible with templates).

    • variables array

      An array of variable specifications.

Responses

  • 200

    Returned if the template has been successfully updated.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok booleanREQUIRED

        If true, the operation completed successfully and returns an expected response.

      • operation_id string

        A unique string identifying the operation, useful for reporting and troubleshooting.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete template

DELETE /api/templates/{template_id}

Example

DELETE /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "a6394ff8-8a65-4494-ad06-677eb8b7ad6a"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateDeleteRequest request = TemplateDeleteRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161");
Response<TemplateResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Template, TemplateList, merge_data
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'

# Delete via template lookup
response = Template(client).lookup(template_id).delete()

# OR, if you want to delete a template without fetching it from the API
response = Template(client).delete(template_id)

Delete a template. If the template is successfully deleted, the response does not include a body.

 Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

Path parameters:

  • template_id stringREQUIRED
    A required string ID of the template.

Responses

  • 200

    The template with given ID has been successfully deleted.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok booleanREQUIRED

        If true, the operation completed successfully and returns an expected response.

      • operation_id string

        A unique string identifying the operation, useful for reporting and troubleshooting.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Regions

The Region API endpoints provide a listing and detail for all of your defined entry/exit regions, including custom shapes (polygons) and circles (point/radius).

Region listing

GET /api/regions

Example

GET /api/regions/?limit=100&start=100 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Attribute: regions
Link: <https://go.urbanairship.com/api/regions?limit=100&start=100>; rel=next
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "next_page": "https://go.urbanairship.com/api/regions?limit=100&start=100",
   "count": 100,
   "regions": [
       {
           "region_id": "abe5deb3-01d0-436e-8c5d-94b6421a01e0",
           "name": "My Favorite Place",
           "created_at": "2020-06-09T12:34:56",
           "updated_at": "2020-06-09T12:34:56",
           "geofence": {
               "type": "POLYGON",
               "points": [
                   {
                       "latitude": 90.0,
                       "longitude": 120.0
                   },
                   {
                       "latitude": 45.0,
                       "longitude": 120.0
                   },
                   {
                       "latitude": 0.0,
                       "longitude": 0.0
                   }
               ]
           },
           "beacons": [
               {
                   "name": "entryway",
                   "id": "VLSHZAOEXOFCMLDVTKFQ"
               },
               {
                   "name": "Exhibit A",
                   "id": "ZAQYMNOZKRFCRPYEUCZI"
               }
           ],
           "attributes": {
               "store_name": "Tonali's Donuts"
           },
           "source_info": {
               "source": "GIMBAL",
               "region_id": "C56654BC0C3243D6A4B7A3673560D6F8",
               "vendor_href": "https://manager.gimbal.com/api/v2/places/C56654BC0C3243D6A4B7A3673560D6F8"
           }
       }
   ]
}

Get a paginated list regions. The result is an array of Region objects under the "regions" key.

Security:

Query parameters:

  • limit integer
    Determines the number of results per page. Defaults to 100, with a maximum of 1,000 regions per page. Setting a limit greater than 1,000 returns a 400 response.

    Max: 1000

  • start integer
    A zero-based integer offset into the ordered list of regions, useful for addressing pages directly.

Responses

  • 200

    Returns OK for success.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • count integer

        The total number of regions returned.

      • next_page string

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

      • ok boolean

        Success.

      • regions array

        An array of region objects.

  • 400

    Returned when limit is greater than 1,000.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Region lookup

GET /api/regions/{region_id}

Example

GET /api/regions/7d4d9a5c-eff5-40f2-b648-4352c166e878 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Attribute: region
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "region": {
        "region_id": "7dbd9a5c-eff5-40f2-b648-4352c1668878",
        "created_at": "2020-08-24T23:15:22.900",
        "updated_at": "2020-08-24T23:15:22.900",
        "name": "Alberta Park",
        "source_info": {
            "source": "GIMBAL",
            "region_id": "C56654BC0C3243D6A4B7A3673560D6F8",
            "vendor_href": "https://manager.gimbal.com/api/v2/places/C56654BC0C3243D6A4B7A3673560D6F8"
        },
        "geofence": {
            "type": "CIRCLE",
            "center": {
                "latitude": 45.56447530000002,
                "longitude": -122.64461097354126
            },
            "radius": 200
        },
        "attributes": {
             "park_name": "alberta",
             "type": "park"
        }
    }
}

Get details for a specific region.

Security:

Path parameters:

  • region_id stringREQUIRED
    The region you want to lookup.

Responses

  • 200

    Returns OK for success.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      Type: object

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Custom Events

User events that occur outside of your app can be submitted to Airship for inclusion in analytics reporting, as triggers for Automation, or for export via Connect. These events can take place on the web, e.g., your website, social media, or in your back office systems such as CRM or POS software. Any event that can be associated with a mobile app user can be submitted as an Airship Custom Event. The events that you submit are associated with channels and are available to use as Custom Event triggers.

Add Custom Events

POST /api/custom-events

Example

POST /api/custom-events HTTP/1.1
Authorization: Bearer <authorization token>
X-UA-Appkey: <application key>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

[
   {
      "occurred": "2020-05-02T02:31:22",
      "user": {
         "named_user_id": "hugh.manbeing"
      },
      "body": {
         "name": "purchased",
         "value": 239.85,
         "transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a",
         "interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234",
         "interaction_type": "url",
         "properties": {
            "description": "Sneaker purchase",
            "brand": "Victory Sneakers",
            "colors": [
             "red",
             "blue"
            ],
            "items": [
               {
                  "text": "New Line Sneakers",
                  "price": "$ 79.95"
               },
               {
                  "text": "Old Line Sneakers",
                  "price": "$ 79.95"
               },
               {
                  "text": "Blue Line Sneakers",
                  "price": "$ 79.95"
               }
            ],
            "name": "Hugh Manbeing",
            "userLocation": {
               "state": "CO",
               "zip": "80202"
            }
         },
         "session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
      }
   }
]

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "operation_id": "8c61c0c4-95b0-45a6-bc38-733f7fcb8979"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .setBearerToken("<bearer token>")
        .build();

CustomEventUser customEventUser = CustomEventUser.newBuilder()
        .setNamedUserId("hugh.manbeing")
        .build();

CustomEventPropertyValue customEventProperty = CustomEventPropertyValue.of("Victory Sneakers");

List<CustomEventPropertyValue> items = new ArrayList<>();
items.add(CustomEventPropertyValue.of("New Line Sneakers"));
items.add(CustomEventPropertyValue.of("Old Line Sneakers"));

DateTime occurred = new DateTime(2020, 05, 02, 02, 31, 22, DateTimeZone.UTC);

CustomEventBody customEventBody = CustomEventBody.newBuilder()
        .setName("purchased")
        .addPropertiesEntry("brand", customEventProperty)
        .addPropertiesEntry("items", CustomEventPropertyValue.of(items))
        .build();

CustomEventPayload customEventPayload = CustomEventPayload.newBuilder()
        .setCustomEventBody(customEventBody)
        .setCustomEventUser(customEventUser)
        .setOccurred(occurred)
        .build();

CustomEventRequest customEventRequest = CustomEventRequest.newRequest(customEventPayload);
Response<CustomEventResponse> response = client.execute(customEventRequest);

from datetime import datetime
from urbanairship import (
    BearerTokenClient, CustomEvent
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

event = CustomEvent(
   client=client,
   name='purchased',
   user={'named_user_id': 'hugh.manbeing'},
   interaction_type='url',
   interaction_id='your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234',
   value=239.85,
   transaction='886f53d4-3e0f-46d7-930e-c2792dac6e0a',
   session_id='22404b07-3f8f-4e42-a4ff-a996c18fa9f1',
   properties={
      'description': 'Sneaker purchase',
      'brand': 'Victory Sneakers',
      'colors': ['red', 'blue'],
      'items': [
         {'text': 'New Line Sneakers', 'price': '$ 79.95'},
         {'text': 'Old Line Sneakers', 'price': '$ 79.95'},
         {'text': 'Blue Line Sneakers', 'price': '$ 79.95'}
      ],
      'name': 'Hugh Manbeing',
      'userLocation': {
         'state': 'CO',
         'zip': '80202'
      }
   },
   occurred=datetime(2020, 5, 2, 2, 31, 22)
)

response = event.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', token: '<token>')

example_events = [
  UA.custom_events(
    body: UA.custom_events_body(
      interaction_id: "https://docs.airship.com/api/ua/#schemas-customeventobject",
      interaction_type: "url",
      name: "example",
      properties: {
        "who" => "Alf",
        "where" => "In the garage!",
        "from" => "Melmac"
      },
      session_id: "8d168d40-bc9b-4359-800c-a546918354ac",
      transaction: "d768f61f-73ba-495f-9e16-b3b9c3b598b7",
      value: 1
    ),
    occurred: "2021-10-01T00:00:00",
    user: UA.custom_events_user(named_user_id: "Gordon Shumway")
  )
]
event = Urbanairship::CustomEvents::CustomEvent.new(client: airship)
event.events = example_events
event.create

Submit an externally-generated Custom Event, associated with a Channel ID or Named User, to Airship. You can use these events as Custom Event triggers for Automation or Sequences and can use handlebars to personalize messages using Custom Event properties (information in the body.properties object).

 Note

  • Requests complete validation before returning a response.
  • Requests are authenticated with a bearer token, which can provide access to this resource alone or to this resource and others.
  • The name value inside body must not contain any uppercase characters, or the event will be rejected with a 400 status code.

Security:

Request headers:

  • X-UA-Appkey stringREQUIRED

Request body:

An array of Custom Event objects.

Responses

  • 200

    Returned on success.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        Success.

      • operation_id string

        A unique string identifying the API interaction. You can use the operation_id in support requests if something goes wrong.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Channels

Channels are Airship’s unique identifiers for addressing applications on iOS, Android, Fire OS, and web devices.

Channel listing

GET /api/channels

Example

GET /api/channels HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
Data-Attribute: channels
Link: <https://go.urbanairship.com/api/channels/?start=1234&limit=100>; rel=next

{
   "ok": true,
   "next_page": "https://go.urbanairship.com/api/channels?start=07AAFE44CD82C2F4E3FBAB8962A95B95F90A54857FB8532A155DE3510B481C13&limit=2",
   "channels": [
      {
         "channel_id": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5",
         "device_type": "android",
         "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
         "opt_in": true,
         "installed": true,
         "background": true,
         "created": "2020-03-06T18:52:59",
         "last_registration": "2020-10-07T21:28:35",
         "named_user_id": "some_id_that_maps_to_your_systems",
         "alias": "null",
         "tags": [
            "tag1",
            "tag2"
         ],
         "tag_groups": {
            "tag_group_1": ["tag1", "tag2"],
            "tag_group_2": ["tag1", "tag2"]
         },
         "device_attributes": {
             "ua_device_os": "10",
             "ua_country": "US",
             "ua_device_model": "SM-G973U",
             "ua_local_tz": "America/Los_Angeles",
             "ua_app_version": "2020-02-01T002322-goat",
             "ua_location_settings": "true",
             "ua_language": "en",
             "ua_sdk_version": "12.2.0",
             "ua_carrier": "Verizon "
          },
          "attributes": {
             "first_name": "Cool",
             "last_name": "Person",
             "birthdate": "1983-03-15T00:00:00",
          }
      },
      {
         "channel_id": "bd36e8c7-5a73-47c0-9716-99fd3d4197d5",
         "device_type": "ios",
         "push_address": null,
         "opt_in": false,
         "installed": true,
         "background": true,
         "created": "2020-03-06T18:52:59",
         "last_registration": "2020-10-07T21:28:35",
         "named_user_id": "some_id_that_maps_to_your_systems",
         "alias": "null",
         "tags": [
            "tag1",
            "tag2"
         ],
         "tag_groups": {
            "tag_group_1": ["tag1", "tag2"],
            "tag_group_2": ["tag1", "tag2"]
         },
         "ios": {
            "badge": 0,
            "quiettime": {
               "start": null,
               "end": null
            },
            "tz": null
         }
      }
   ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ChannelRequest request = ChannelRequest.newRequest();
Response<ChannelResponse> response = client.execute(request);
ChannelView channels = response.getBody().get().getChannelView().get();

from urbanairship import (
    BasicAuthClient, ChannelList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
channel_id = None

for channel in ChannelList(client):
    channel_id = channel.channel_id
    print(channel.channel_id, channel.device_type, channel.tags,
          channel.push_address, channel.named_user_id, channel.opt_in)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

channel_list = UA::ChannelList.new(client: airship)
channel_list.each do |channel|
    puts(channel)
end
puts(channel_list.count)

List all channels registered to this app key, along with associated data and metadata.

 Note

Tags added to a channel via the Named Users tag endpoint will not appear with a request to this endpoint. To view those tags, you must look up the Named User associated with the channel.

Security:

Query parameters:

  • limit integer
    The default limit is 1,000 channel objects returned per request. Set the limit to 1,000 or fewer in your API calls.

    Max: 1000

Responses

  • 200

    Returns OK for success with the JSON response. Tags added to a channel using /named_users/tags are not returned from this endpoint. To view those tags, you must look up the Named User associated with the channel.

    Response headers:

    • Link string

      Provides the URL to the current page of results. The query within the URL contains the limit (the number of results on the page) and start (the first channel_id in the result set) parameters.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • channels array

        An array of channel objects.

      • next_page string

        If there is more than one page of results, use this link to get the next page of results.

      • ok boolean

        Success.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Set or remove attributes on channels

POST /api/channels/attributes

Example

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

{
    "audience": {
       "android_channel": ["13863b3c-f860-4bbf-a9f1-4d785379b8a2"]
    },
    "attributes": [
       {
             "action": "set",
             "key": "major_league",
             "value": "sf_giants"
       },
       {
             "action": "remove",
             "key": "minor_league"
       },
       {
             "action": "set",
             "key": "position",
             "value": "LF"
       },
       {
             "action": "set",
             "key": "specialData",
             "value": {
                  "timestamp": "1983-03-15 10:00:00",
                  "specialties": [
                    {
                        "specialty": {
                            "name": "golden",
                            "property": "small"
                        }
                    },
                    {
                        "specialty": {
                            "name": "silver",
                            "property": "medium"
                        }
                    }
                ]
            }
       }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Attribute setMajorLeague = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("major_league")
        .setValue("sf_giants")
        .build();

Attribute removeMinorLeague = Attribute.newBuilder()
        .setAction(AttributeAction.REMOVE)
        .setKey("minor_league")
        .build();

Attribute setPosition = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("position")
        .setValue("LF")
        .build();

String specialtiesStr = "{" +
                        "    \"timestamp\": \"1983-03-15 10:00:00\"," +
                        "    \"specialties\": [{" +
                        "            \"specialty\": {" +
                        "                \"name\": \"golden\"," +
                        "                \"property\": \"small\"" +
                        "            }" +
                        "        }," +
                        "        {" +
                        "            \"specialty\": {" +
                        "                \"name\": \"silver\"," +
                        "                \"property\": \"medium\"" +
                        "            }" +
                        "        }" +
                        "    ]" +
                        "}";
JSONObject specialtiesJson = new JSONObject(specialtiesStr);
Attribute setSpecialties = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("specialties")
        .setValue(specialtiesJson)
        .build();

ChannelAttributesPayload payload = ChannelAttributesPayload.newBuilder()
        .addAttribute(setMajorLeague)
        .addAttribute(removeMinorLeague)
        .addAttribute(setPosition)
        .setAudience(AttributeAudience.newBuilder()
                .addDeviceId(AttributeAudienceType.ANDROID_CHANNEL, "13863b3c-f860-4bbf-a9f1-4d785379b8a2")
                .build())
        .build();

ChannelAttributesRequest request = ChannelAttributesRequest.newRequest(payload);
Response<ChannelAttributesResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Attribute
)
import json

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

set_major_league = Attribute(
    action="set",
    key="major_league",
    value="sf_giants"
)

remove_minor_league = Attribute(
    action="remove",
    key="minor_league"
)

set_position = Attribute(
    action="set",
    key="position",
    value="LF"
)

specialties_string = "{" + \
                   "    \"timestamp\": \"1983-03-15 10:00:00\"," + \
                   "    \"specialties\": [{" + \
                   "            \"specialty\": {" + \
                   "                \"name\": \"golden\"," + \
                   "                \"property\": \"small\"" + \
                   "            }" + \
                   "        }," + \
                   "        {" + \
                   "            \"specialty\": {" + \
                   "                \"name\": \"silver\"," + \
                   "                \"property\": \"medium\"" + \
                   "            }" + \
                   "        }" + \
                   "    ]" + \
                   "}"
specialties_json = json.loads(specialties_string)
specialties = Attribute(
    action="set",
    key="specialties",
    value=specialties_json
)

modifications = Attribute.ModifyAttributes(
    client=client,
    attributes=[set_major_league,
               remove_minor_league,
               set_position],
    channel="13863b3c-f860-4bbf-a9f1-4d785379b8a2"
)

modifications.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

channel_info = UA::ChannelInfo.new(client: airship)
channel_info.audience = {"android_channel": '13863b3c-f860-4bbf-a9f1-4d785379b8a2'}
channel_info.attributes =  {
    "action": "set",
    "key": "major_league",
    "value": "sf_giants"
}
channel_info.set_attributes

Example request with dates and numbers

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

{
    "audience": {
       "android_channel": ["13863b3c-f860-4bbf-a9f1-4d785379b8a2"]
    },
    "attributes": [
       {
             "action": "set",
             "key": "major_league",
             "value": "sf_giants"
       },
       {
             "action": "remove",
             "key": "minor_league"
       },
       {
             "action": "set",
             "key": "position",
             "value": "LF"
       },
       {
             "action": "set",
             "key": "specialData",
             "value": {
                  "timestamp": "1983-03-15 10:00:00",
                  "specialties": [
                    {
                        "specialty": {
                            "name": "golden",
                            "property": "small"
                        }
                    },
                    {
                        "specialty": {
                            "name": "silver",
                            "property": "medium"
                        }
                    }
                ]
            }
       }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Attribute setMajorLeague = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("major_league")
        .setValue("sf_giants")
        .build();

Attribute removeMinorLeague = Attribute.newBuilder()
        .setAction(AttributeAction.REMOVE)
        .setKey("minor_league")
        .build();

Attribute setPosition = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("position")
        .setValue("LF")
        .build();

String specialtiesStr = "{" +
                        "    \"timestamp\": \"1983-03-15 10:00:00\"," +
                        "    \"specialties\": [{" +
                        "            \"specialty\": {" +
                        "                \"name\": \"golden\"," +
                        "                \"property\": \"small\"" +
                        "            }" +
                        "        }," +
                        "        {" +
                        "            \"specialty\": {" +
                        "                \"name\": \"silver\"," +
                        "                \"property\": \"medium\"" +
                        "            }" +
                        "        }" +
                        "    ]" +
                        "}";
JSONObject specialtiesJson = new JSONObject(specialtiesStr);
Attribute setSpecialties = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("specialties")
        .setValue(specialtiesJson)
        .build();

ChannelAttributesPayload payload = ChannelAttributesPayload.newBuilder()
        .addAttribute(setMajorLeague)
        .addAttribute(removeMinorLeague)
        .addAttribute(setPosition)
        .setAudience(AttributeAudience.newBuilder()
                .addDeviceId(AttributeAudienceType.ANDROID_CHANNEL, "13863b3c-f860-4bbf-a9f1-4d785379b8a2")
                .build())
        .build();

ChannelAttributesRequest request = ChannelAttributesRequest.newRequest(payload);
Response<ChannelAttributesResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Attribute
)
import json

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

set_major_league = Attribute(
    action="set",
    key="major_league",
    value="sf_giants"
)

remove_minor_league = Attribute(
    action="remove",
    key="minor_league"
)

set_position = Attribute(
    action="set",
    key="position",
    value="LF"
)

specialties_string = "{" + \
                   "    \"timestamp\": \"1983-03-15 10:00:00\"," + \
                   "    \"specialties\": [{" + \
                   "            \"specialty\": {" + \
                   "                \"name\": \"golden\"," + \
                   "                \"property\": \"small\"" + \
                   "            }" + \
                   "        }," + \
                   "        {" + \
                   "            \"specialty\": {" + \
                   "                \"name\": \"silver\"," + \
                   "                \"property\": \"medium\"" + \
                   "            }" + \
                   "        }" + \
                   "    ]" + \
                   "}"
specialties_json = json.loads(specialties_string)
specialties = Attribute(
    action="set",
    key="specialties",
    value=specialties_json
)

modifications = Attribute.ModifyAttributes(
    client=client,
    attributes=[set_major_league,
               remove_minor_league,
               set_position],
    channel="13863b3c-f860-4bbf-a9f1-4d785379b8a2"
)

modifications.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

channel_info = UA::ChannelInfo.new(client: airship)
channel_info.audience = {"android_channel": '13863b3c-f860-4bbf-a9f1-4d785379b8a2'}
channel_info.attributes =  {
    "action": "set",
    "key": "major_league",
    "value": "sf_giants"
}
channel_info.set_attributes

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

{
    "audience": {
       "android_channel": ["13863b3c-f860-4bbf-a9f1-4d785379b8a2"]
    },
    "attributes": [
       {
             "action": "set",
             "key": "birthday",
             "value": "1983-03-15 10:00:00"
       },
       {
             "action": "set",
             "key": "fav_number",
             "value": 42
       },
       {
             "action": "remove",
             "key": "another_attribute"
       }
    ]
}

Set or remove attributes on a channel. Aside from Airship’s default attributes, you must define attributes in the Airship dashboard before you can set them on channels.

Security:

Request body:

  • Content-Type: application/json

    Include an audience object and an array of attributes objects in your request.

    OBJECT PROPERTIES
    • attributes object<Attribute assignment>REQUIRED
    • audience objectREQUIRED

      The channel(s) you want to set or remove attributes for.

      OBJECT PROPERTIES
      • amazon_channel object

        The unique channel identifier used to target a Fire OS device.

        OBJECT PROPERTIES
        • amazon_channel objectREQUIRED
          One of
          • string
          • array<string>

            Min items: 1, Max items: 100

      • android_channel object

        The unique channel identifier used to target an Android device.

        OBJECT PROPERTIES
        • android_channel objectREQUIRED
          One of
          • string
          • array<string>

            Min items: 1, Max items: 100

      • channel object

        The unique channel identifier used to target an open channel device or web device, i.e., web browser.

        OBJECT PROPERTIES
        • channel objectREQUIRED
          One of
          • string
          • array<string>

            Min items: 1, Max items: 100

      • email_address array[string]

        The unique channel identifier used to target an email address.

      • ios_channel object

        The unique channel identifier used to target an iOS device.

        OBJECT PROPERTIES
        • ios_channel objectREQUIRED
          One of
          • string
          • array<string>

            Min items: 1, Max items: 100

      • sms_id object

        Selects a single SMS device. The msisdn must be opted_in to receive notifications.

        OBJECT PROPERTIES
        • msisdn stringREQUIRED

          The recipient phone number.

        • sender stringREQUIRED

          The sender that the app is configured to send SMS messages from.

      • web_channel array[string]

        The unique channel identifier used to target a web device.

Responses

  • 200

    The operation was successful.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        If true, your request was successful.

      • warning string

        Alerts you if your request could not be processed. You may receive a 200 with a warning if you provide a value that does not match your attribute type. For example, an attribute that expects a numeric value will allow a value of “25” but fail if you input “twenty-five”.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Subscribe or unsubscribe channels to/from subscription lists

POST /api/channels/subscription_lists

Example

POST /api/channels/subscription_lists HTTP/1.1
Authorization: Basic <App Auth>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "subscription_lists": [
      {
         "action":"subscribe",
         "list_id":"intriguing_ideas"
      },
      {
         "action":"unsubscribe",
         "list_id":"animal_facts"
      }
   ],
   "audience": {
      "ios_channel": [
         "b8f9b663-0a3b-cf45-587a-be880946e881"
      ],
      "email_address": [
         "homer@example.com",
         "nick@example.com"
      ]
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

 SubscriptionList subscriptionList = SubscriptionList.newBuilder()
       .setListId("big_deals")
       .setAction(SubscriptionListAction.SUBSCRIBE)
       .build();

 SubscriptionListPayload payload = SubscriptionListPayload.newBuilder()
       .addSubscriptionList(subscriptionList)
       .setAudience(ChannelAudience.newBuilder()
                .addDeviceId(ChannelAudienceType.ANDROID_CHANNEL, "002b4104-c94f-418d-be86-ead3214b3244").build())
       .build();

 SubscriptionListRequest request  = SubscriptionListRequest.newRequest(payload);
 Response<SubscriptionListResponse> response = client.execute(request);

import urbanairship as ua

client = ua.BasicAuthClient('<app key>', '<master secret>')

subscription_list = ua.SubscriptionList(client)

subscription_list.subscribe(list_id="intriguing_ideas",
                            audience=ua.email("nick@example.com")
                           )

subscription_list.unsubscribe(list_id="animal_facts", 
                              audience=ua.ios_channel(
                                 "b8f9b663-0a3b-cf45-587a-be880946e881"
                                 )
                              )

Subscribe or unsubscribe channels to/from Subscription Lists.

 Note

If you are using a single-channel Preference Center created before October 10, 2022, that has not been migrated to user-level, use the /api/channels/subscription_lists endpoint to add or remove individual channels to/from your subscription list. Otherwise, use the Scoped Named User batch operations endpoint to do so.

Security:

Request body:

  • Content-Type: application/json

    One of

Responses

  • 202

    Returns OK for success.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Channel tags

POST /api/channels/tags

Example

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

{
   "audience": {
      "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881",
      "android_channel": "13863b3c-f860-4bbf-a9f1-4d785379b8a2"
   },
   "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
   }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "warnings": ["The following tag groups do not exist: my_fav_tag_group2", "The following tag groups are deactivated: my_fav_tag_group3"]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ChannelTagRequest request = ChannelTagRequest.newRequest()
        .addIOSChannel("b8f9b663-0a3b-cf45-587a-be880946e881")
        .addAndroidChannel("13863b3c-f860-4bbf-a9f1-4d785379b8a2")
        .addTags("my_fav_tag_group1", ImmutableSet.of("tag1", "tag2", "tag3"))
        .addTags("my_fav_tag_group2", ImmutableSet.of("tag1", "tag2", "tag3"))
        .addTags("my_fav_tag_group3", ImmutableSet.of("tag1", "tag2", "tag3"));

Response<GenericResponse> response = client.execute(request);

import urbanairship as ua

client = ua.BasicAuthClient('<app key>', '<master secret>')
channel_tags = ua.devices.ChannelTags(client)
ios_audience = ['b8f9b663-0a3b-cf45-587a-be880946e881']
android_audience = ['13863b3c-f860-4bbf-a9f1-4d785379b8a2']
channel_tags.set_audience(ios_audience, android_audience
)
channel_tags.add('my_fav_tag_group1', ['tag1', 'tag2', 'tag3'])
channel_tags.remove('my_fav_tag_group2', 'tag4')
channel_tags.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

channel_tags = UA::ChannelTags.new(client: airship)
ios_audience = 'b8f9b663-0a3b-cf45-587a-be880946e881'
android_audience = '13863b3c-f860-4bbf-a9f1-4d785379b8a2'
channel_tags.set_audience(
    ios: ios_audience,
    android: android_audience
)
channel_tags.add(group_name: 'my_fav_tag_group1', tags: ['tag1', 'tag2', 'tag3'])
channel_tags.remove(group_name: 'my_fav_tag_group2', tags: 'tag4')
channel_tags.send_request

Add, remove, or set tags on a channel.

Security:

Request body:

  • Content-Type: application/json

    A single request body may contain add and/or remove objects or a single set object. At least one of the add, remove, or set objects must be present in a request.

    OBJECT PROPERTIES
    • add object<Tag Group object>

      Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • audience objectREQUIRED

      Specifies one or more channels that you want to apply tag operations to.

      OBJECT PROPERTIES
      • amazon_channel array[string]

        The unique channel identifier for a Fire OS device.

      • android_channel array[string]

        The unique channel identifier for an Android device.

      • channel array[string]

        The unique channel identifier for email, sms, open, or web device types.

      • ios_channel array[string]

        The unique channel identifier for an iOS device.

    • remove object<Tag Group object>

      Removes the specified tags from the channel.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • set object<Tag Group object>

      Assigns a list of tags exactly. Any previously set tags that are not in this current list will be removed.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 200

    Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 is returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        If true, your request was processed normally.

      • warnings array[string]

        Returned when some tag groups could not be updated. Contains a string indicating each tag group that could not be updated and the reason the update failed.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Uninstall channels

POST /api/channels/uninstall

Example

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

[
   {
      "channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881",
      "device_type": "ios"
   },
   {
      "channel_id": "13863b3c-f860-4bbf-a9f1-4d785379b8a2",
      "device_type": "android"
   }
]

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

 Set<ChannelUninstallDevice> channels = ImmutableSet.of(
       new ChannelUninstallDevice("00f74677-4616-4958-bd91-30e949814d2c", ChannelUninstallDeviceType.IOS),
       new ChannelUninstallDevice("007f7156-9b82-4cb6-a2f9-e2c8e7fce13d", ChannelUninstallDeviceType.ANDROID)
 );

 ChannelUninstallPayload payload = ChannelUninstallPayload.newBuilder()
       .setChannels(channels)
       .build();

 ChannelUninstallRequest request = ChannelUninstallRequest.newRequest(payload);
 Response<ChannelUninstallResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, ChannelUninstall
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

channel_uninstall = ChannelUninstall(client)
channel = {
    "channel_id": 'b8f9b663-0a3b-cf45-587a-be880946e881',
    "device_type": "ios"
}

channel_uninstall.uninstall(channel)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

cu = UA::ChannelUninstall.new(client: airship)

chans = [{"channel_id" => "b8f9b663-0a3b-cf45-587a-be880946e881",
          "device_type" => "ios"},
         {"channel_id" => "13863b3c-f860-4bbf-a9f1-4d785379b8a2",
          "device_type" => "android"}]

cu.uninstall(channels: chans)

Uninstalls a channel, removing it and all accompanying analytic data (including Performance Analytics) from Airship systems in accordance with data privacy law compliance.

Uninstallation is handled automatically by the Airship SDK and push systems. If a user decides to opt in to communications again (either by using your app or other user preferences), they will create a new channel and a new set of analytic data. The value of a Channel ID may be the same as before however none of the associated metadata will persist when a user opts in again. A new Channel ID will be created if the user clears their browser’s cookies and data, deletes and reinstalls the app, etc.

See Individual Data Privacy Rights Under Data Privacy Laws for more information about data privacy law compliance.

 Note

Channel uninstallation, like channel creation, is an asynchronous operation and may take some time to complete.

Security:

Request body:

  • Content-Type: application/json

    array<object>

    Min items: 1, Max items: 1000

    ARRAY ITEM

    • Specifies the Channel ID and device type you want to uninstall.

      OBJECT PROPERTIES
      • channel_id stringREQUIRED
        The Channel ID.
      • device_type stringREQUIRED
        The device type of the channel.

        Possible values: ios, android, amazon, web, open

Responses

  • 202

    Returns OK for success.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Channel lookup

GET /api/channels/{channel_id}

Example

GET /api/channels/9c36e8c7-5a73-47c0-9716-99fd3d4197d5 HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
Data-Attribute: channel

{
   "ok": true,
   "channel": {
      "channel_id": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5",
      "device_type": "ios",
      "installed": true,
      "opt_in": false,
      "background": true,
      "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
      "created": "2020-08-08T20:41:06",
      "last_registration": "2020-05-01T18:00:27",
      "named_user_id": "some_id_that_maps_to_your_systems",
      "alias": null,
      "tags": [
         "tag1",
         "tag2"
      ],
      "tag_groups": {
         "tag_group_1": ["tag1", "tag2"],
         "tag_group_2": ["tag1", "tag2"]
      },
      "ios": {
         "badge": 0,
         "quiettime": {
            "start": null,
            "end": null
         },
         "tz": "America/Los_Angeles"
      },
      "open_tracking_opted_in": "2022-11-26T00:00:00",
      "open_tracking_opted_out": "2022-12-11T00:00:00",
      "click_tracking_opted_in": "2022-11-26T00:00:00",
      "click_tracking_opted_out": "2022-12-11T00:00:00"
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ChannelRequest request = ChannelRequest.newRequest("9c36e8c7-5a73-47c0-9716-99fd3d4197d5");
Response<ChannelResponse> response = client.execute(request);
ChannelView channel = response.getBody().get().getChannelView().get();

from urbanairship import (
    BasicAuthClient, ChannelInfo
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
channel = ChannelInfo(client).lookup('9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
print(channel.channel_id, channel.device_type, channel.tags,
      channel.push_address, channel.named_user_id, channel.opt_in)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

channel_client = UA::ChannelInfo.new(client: airship)
channel_info = channel_client.lookup(uuid: '9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
puts(channel_info)

Example open channel lookup response with all optional keys

GET /api/channels/9c36e8c7-5a73-47c0-9716-99fd3d4197d5 HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
Data-Attribute: channel

{
   "ok": true,
   "channel": {
      "channel_id": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5",
      "device_type": "ios",
      "installed": true,
      "opt_in": false,
      "background": true,
      "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
      "created": "2020-08-08T20:41:06",
      "last_registration": "2020-05-01T18:00:27",
      "named_user_id": "some_id_that_maps_to_your_systems",
      "alias": null,
      "tags": [
         "tag1",
         "tag2"
      ],
      "tag_groups": {
         "tag_group_1": ["tag1", "tag2"],
         "tag_group_2": ["tag1", "tag2"]
      },
      "ios": {
         "badge": 0,
         "quiettime": {
            "start": null,
            "end": null
         },
         "tz": "America/Los_Angeles"
      },
      "open_tracking_opted_in": "2022-11-26T00:00:00",
      "open_tracking_opted_out": "2022-12-11T00:00:00",
      "click_tracking_opted_in": "2022-11-26T00:00:00",
      "click_tracking_opted_out": "2022-12-11T00:00:00"
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ChannelRequest request = ChannelRequest.newRequest("9c36e8c7-5a73-47c0-9716-99fd3d4197d5");
Response<ChannelResponse> response = client.execute(request);
ChannelView channel = response.getBody().get().getChannelView().get();

from urbanairship import (
    BasicAuthClient, ChannelInfo
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
channel = ChannelInfo(client).lookup('9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
print(channel.channel_id, channel.device_type, channel.tags,
      channel.push_address, channel.named_user_id, channel.opt_in)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

channel_client = UA::ChannelInfo.new(client: airship)
channel_info = channel_client.lookup(uuid: '9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
puts(channel_info)

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
Data-Attribute: channel

{
   "ok": true,
   "channel": {
      "channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881",
      "type": "open",
      "opt_in": true,
      "address": "example@example.com",

      "created": "2013-08-08T20:41:06",
      "last_registration": "2014-05-01T18:00:27",

      "named_user_id": "john_doe_123",
      "tags": ["asdf"],

      "tag_groups": {
         "timezone" : ["America/Los_Angeles"],
         "locale_country" : ["US"],
         "locale_language" : ["en"],
         "tag_group_1" : ["tag1", "tag2"],
         "tag_group_2" : ["tag1", "tag2"]
      },

      "open" {
         "open_platform_name": "email",
         "identifiers": {
            "com.example.external_id": "df6a6b50-9843-7894-1235-12aed4489489"
         }
      }
   }
}

Example open channel lookup response with only required keys

GET /api/channels/9c36e8c7-5a73-47c0-9716-99fd3d4197d5 HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
Data-Attribute: channel

{
   "ok": true,
   "channel": {
      "channel_id": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5",
      "device_type": "ios",
      "installed": true,
      "opt_in": false,
      "background": true,
      "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
      "created": "2020-08-08T20:41:06",
      "last_registration": "2020-05-01T18:00:27",
      "named_user_id": "some_id_that_maps_to_your_systems",
      "alias": null,
      "tags": [
         "tag1",
         "tag2"
      ],
      "tag_groups": {
         "tag_group_1": ["tag1", "tag2"],
         "tag_group_2": ["tag1", "tag2"]
      },
      "ios": {
         "badge": 0,
         "quiettime": {
            "start": null,
            "end": null
         },
         "tz": "America/Los_Angeles"
      },
      "open_tracking_opted_in": "2022-11-26T00:00:00",
      "open_tracking_opted_out": "2022-12-11T00:00:00",
      "click_tracking_opted_in": "2022-11-26T00:00:00",
      "click_tracking_opted_out": "2022-12-11T00:00:00"
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ChannelRequest request = ChannelRequest.newRequest("9c36e8c7-5a73-47c0-9716-99fd3d4197d5");
Response<ChannelResponse> response = client.execute(request);
ChannelView channel = response.getBody().get().getChannelView().get();

from urbanairship import (
    BasicAuthClient, ChannelInfo
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
channel = ChannelInfo(client).lookup('9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
print(channel.channel_id, channel.device_type, channel.tags,
      channel.push_address, channel.named_user_id, channel.opt_in)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

channel_client = UA::ChannelInfo.new(client: airship)
channel_info = channel_client.lookup(uuid: '9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
puts(channel_info)

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
Data-Attribute: channel

{
   "ok": true,
   "channel": {
      "channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881",
      "type": "open",
      "opt_in": true,
      "address": "example@example.com",

      "created": "2013-08-08T20:41:06",
      "last_registration": "2014-05-01T18:00:27",

      "named_user_id": "john_doe_123",
      "tags": ["asdf"],

      "tag_groups": {
         "timezone" : ["America/Los_Angeles"],
         "locale_country" : ["US"],
         "locale_language" : ["en"],
         "tag_group_1" : ["tag1", "tag2"],
         "tag_group_2" : ["tag1", "tag2"]
      },

      "open" {
         "open_platform_name": "email",
         "identifiers": {
            "com.example.external_id": "df6a6b50-9843-7894-1235-12aed4489489"
         }
      }
   }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
Data-Attribute: channel

{
   "ok": true,
   "channel": {
      "channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881",

      "type": "open",
      "opt_in": false,
      "address": "example@example.com",

      "created": "2013-08-08T20:41:06",
      "last_modified": "2014-05-01T18:00:27",

      "tags": [],
      "tag_groups" {},

      "open": {
         "open_platform_name": "email"
      }
   }
}

Fetch an individual channel registered to the app key, along with associated data and metadata.

 Note

Tags added to a channel via the Named Users tag endpoint will not appear with a request to this endpoint. To view those tags, you must look up the Named User associated with the channel.

Security:

Path parameters:

  • channel_id stringREQUIRED
    The unique channel identifier.

Responses

  • 200

    Tags added to a channel using /named_users/tags are not returned from this endpoint. To view those tags, you must look up the Named User associated with the channel.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • channel object

        A channel object.

        One of
        • Channel Listing Object

          Describes a channel listing object.

        • Open channel object object

          Describes an open channel.

          OBJECT PROPERTIES
          • address string

            The address to send push notifications to when device_type is email or open.

          • channel_id string

            The unique channel identifier for a device.

          • created string

            The creation date-time of this channel.

          • last_registration string

            The last registration date-time of this channel, if known.

          • locale_country string

            The two-letter country locale short code. Will set the ua_locale_country tag group to the specified value.

          • locale_language string

            The two-letter language locale short code. Will set the ua_locale_language tag group to the specified value.

          • named_user_id string

            A customer-chosen ID that represents the device user, e.g., CRM ID. This ID cannot have leading or trailing whitespace.

          • open object

            Contains options that apply when the device_type is set to open.

            OBJECT PROPERTIES
            • identifiers object

              A set of up to 100 key:value pairs representing identifiers for this channel in your own delivery systems and delivered as a part of webhook payloads.

            • old_address string

              If a channel exists for the value of old_address, replaces that channel’s address with the value of address. Use infrequently, such as when an end user’s phone number or email address permanently changes.

            • open_platform_name string

              The name of the open channel that this channel_id is registered on.

          • opt_in boolean

            If true, the channel is opted in to push notifications. If false, it is not.

          • set_tags boolean

            When true, replaces all device tags on the channel with the set provided in "tags". When false or absent, the "tags" set is unioned with existing device tags.

          • tag_groups object<Tag Group object>

            One or more tag group objects (including Device Property Tags) associated with this channel.

            Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

            A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

          • tags array[string]

            An array of tags associated with this channel.

          • timezone string

            An IANA tzdata identifier for the time zone as a string, e.g., "America/Los_Angeles". Will set the timezone tag group tag with the specified value.

          • type string

            Specifies the device platform for a channel.

            Possible values: open

      • ok boolean

        Success.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Open Channels

Open Channels are custom communication channels that you can configure for messaging, using the same segmentation and scheduling tools available on natively-supported platforms (iOS, Android, etc.). With Open Channels, you define a new open platform, e.g., SMS, Slack, Acme™ Smart Toasters, and register the new platform with Airship.

If you are sending through the Push API, platform overrides for open platforms are covered in Open Channel Overrides. For open channel lookup, use the Channel Lookup endpoint.

Register new / update channel

POST /api/channels/open

Example

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

{
   "channel": {
      "type": "open",
      "opt_in": true,
      "address": "Number Four",
      "tags": [
         "toaster",
         "caprica"
      ],
      "timezone": "America/Los_Angeles",
      "locale_country": "US",
      "locale_language": "en",
      "open": {
         "open_platform_name": "cylon",
         "identifiers": {
            "model": "4"
         }
      }
   }
}

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

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

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

OpenChannel openChannel = OpenChannel.newBuilder()
        .setOpenPlatformName("cylon")
        .setOldAddress("Number Four")
        .addIdentifier("model", "4")
        .build();

Channel channel = Channel.newBuilder()
        .setOpenChannel(openChannel)
        .setChannelType(ChannelType.OPEN)
        .setOptIn(true)
        .setAddress("Number Four")
        .setTags(true)
        .addTag("toaster")
        .setTimeZone("America/Los_Angeles")
        .setLocaleCountry("US")
        .setLocaleLanguage("en")
        .build();

OpenChannelPayload payload = new OpenChannelPayload(channel);
OpenChannelRequest request = OpenChannelRequest.newRequest(payload);
Response<OpenChannelResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, OpenChannel
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
channel = OpenChannel(airship=client)
channel.address = 'Number Four'
channel.open_platform = 'cylon'
channel.opt_in = True
channel.tags = ['toaster', 'caprica']
channel.identifiers = {'model': '4'}
response = channel.create()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

open_channel = UA::OpenChannel.new(client: airship)
open_channel.opt_in = true
open_channel.address = 'Number Four'
open_channel.open_platform = 'cylon'
open_channel.create()

Create a new open channel or update an existing open channel.

 Note

A 200 status will be returned if an existing channel was found for the specified open_platform_name and address. Otherwise, a new channel will be created and a 200 status will be returned.

Security:

Request body:

An open channel object.

  • Content-Type: application/json

    OBJECT PROPERTIES
    • channel objectREQUIRED

      Properties of the open channel object.

      OBJECT PROPERTIES
      • address stringREQUIRED

        Where notifications sent to this channel_id will be sent. Examples: email address, phone number. If missing, channel_id must be present. The address is one-to-one with the channel_id. New addresses on existing channels will overwrite old associations.

      • locale_country string

        The two-letter country locale short code. Will set the ua_locale_country tag group to the specified value.

      • locale_language string

        The two-letter language locale short code. Will set the ua_locale_language tag group to the specified value.

      • open objectREQUIRED

        Open channel-specific properties.

        OBJECT PROPERTIES
        • identifiers object

          Optional object with string-to-string key:value pairs that represent non-segmentable identifiers for the channel in your delivery systems. Delivered as part of webhook payloads. If present, the value will overwrite (not union with) existing identifier records.

        • open_platform_name stringREQUIRED

          The name of the open platform to which you are registering this channel.

      • opt_in booleanREQUIRED

        If false, no payloads will be delivered for the channel.

      • tags array[string]

        A list of strings used for audience targeting. When used for this endpoint, operates like the tags { set {}} operation; specified tags are applied, and all other tags are removed.

      • timezone string

        An IANA tzdata identifier for the time zone as a string, e.g., "America/Los_Angeles". Will set the timezone tag group tag with the specified value.

      • type stringREQUIRED

        Required string.

        Possible values: open

Responses

  • 200

    Returned if the new channel is created successfully or if an existing channel was found for the specified open_platform_name and address.

    Response headers:

    • Location string

      Used for later API calls for this channel.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • channel_id string

        Identifies the new open channel or the open channel you successfully updated.

      • ok boolean

        Success.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 429

    Too many requests hit the API too quickly. For example, if we are not ready to create a channel for this payload; e.g., it is rate limited. You should wait before retrying the channel creation.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Open channel tags

POST /api/channels/open/tags

Example

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

 {
  "audience": {
      "address": "Number Four",
      "open_platform_name": "cylon"
  },
  "add": {
    "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
    "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
    "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
  }
 }

HTTP/1.1 200 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok":true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

OpenChannelTagRequest openChannelTagRequest =  OpenChannelTagRequest.newRequest()
        .addOpenChannel("Number Four","cyclon")
        .addTags("CRM_Delux", Set.of("tag1","tag2"))
        .removeTags("CRM_Delux",  Set.of("tag3","tag4"));
Response<GenericResponse> response = client.execute(openChannelTagRequest);

from urbanairship import (
    BasicAuthClient, OpenChannel
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
channel = OpenChannel(airship=client)
channel.address = 'Number Four'
channel.open_platform = 'cylon'
channel.tags = ['tag1', 'tag2', 'tag3']
response = channel.update()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

open_channel = UA::OpenChannel.new(client: airship)
open_channel.opt_in = true
open_channel.address = 'Number Four'
open_channel.open_platform = 'cylon'
open_channel.channel_id = 'df6a6b50-9843-0304-d5a5-743f246a4946'
open_channel.tags = ['tag1', 'tag2', 'tag3']
open_channel.update(set_tags: true)

Manipulate a single open channel’s tags. Open channels are identified by address, not by their channel_id.

Security:

Request body:

  • Content-Type: application/json

    Add, remove, or set tags on a channel. A single request body may contain add and/or remove objects or a single set field. At least one of the add, remove, or set objects must be present in a request.

    OBJECT PROPERTIES
    • add object<Tag Group object>

      Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • audience objectREQUIRED

      The request body containing an address and open_platform_name.

      OBJECT PROPERTIES
      • address stringREQUIRED

        Where notifications sent to this channel_id will be sent. Examples: email address, phone number. If missing, channel_id must be present. The address is one-to-one with the channel_id. New addresses on existing channels will overwrite old associations.

      • open_platform_name stringREQUIRED

        An alphanumeric string that must be the name of a pre-created open platform object.

    • remove object<Tag Group object>

      Removes the specified tags from the channel.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • set object<Tag Group object>

      Assigns a list of tags exactly. Any previously set tags that are not in this current list will be removed.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 200

    Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 is returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Uninstall open channels

POST /api/channels/open/uninstall

Example

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

{
  "address": "Number Four",
  "open_platform_name": "cylon"
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

OpenChannelUninstallRequest openChannelUninstallRequest = OpenChannelUninstallRequest.newRequest("Number Four","cyclon");
Response<GenericResponse> response = client.execute(openChannelUninstallRequest);

from urbanairship import (
    BasicAuthClient, OpenChannel
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
channel = OpenChannel(airship=client)
channel.address = 'Number Four'
channel.open_platform = 'cylon'
response = channel.uninstall()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

cu = UA::OpenChannelUninstall.new(client: airship)
cu.uninstall(address: 'Number Four', open_platform: 'cylon')

Uninstall a channel needing to know its Channel ID. You cannot send notifications to, or get channel information for, an uninstalled channel.

Security:

Request body:

An address and the open_platform_name you want to uninstall the address from.

  • Content-Type: application/json

    Open channel identifier

    The request body containing an address and open_platform_name.

    OBJECT PROPERTIES
    • address stringREQUIRED

      Where notifications sent to this channel_id will be sent. Examples: email address, phone number. If missing, channel_id must be present. The address is one-to-one with the channel_id. New addresses on existing channels will overwrite old associations.

    • open_platform_name stringREQUIRED

      An alphanumeric string that must be the name of a pre-created open platform object.

Responses

  • 202

    The request has been accepted for processing.

    Response body:

    • Content-Type: application/json
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Email

Register email channels, set opt-in status, and manipulate tags on email channels.

Create email attachment

POST /api/attachments

Example create email attachment

POST /attachments HTTP/1.1
Authorization: Bearer <authorization token>
Content-Type: application/json
Accept: application/vnd.urbanairship+json; version=3

{
  "filename": "rickroll.png",
  "content_type": "text/plain; charset=\"UTF-8\"",
  "data": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAIAAADTED8xAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyhpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8..."
}

HTTP/1.1 201 Accepted
Data-Attribute: attachment_id
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "attachment_ids": [
        "b0c46a8d-b701-441b-9d6e-147c183b28ca"
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();
        
EmailAttachmentRequest emailAttachmentRequest = EmailAttachmentRequest.newRequest()
        .setContentType("text/plain; charset=\"UTF-8\"")
        .setData("iBORw0KGgoAAAANSUhEUgAAAQAAAAEACAIAAADTED8xAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyhpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8...")
        .setFilename("rickroll.png");

Response<EmailAttachmentResponse> response = client.execute(emailAttachmentRequest);

from urbanairship import (
    BearerTokenClient, EmailAttachment
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

attachment = EmailAttachment(
  client=client,
  filename='rickroll.png', 
  content_type='image/png; charset="UTF-8"', 
  filepath='path/to/never_gonna.png'
)
response = attachment.post()

print(response.get('attachment_ids'))

Create attachments by POSTing to the attachments URI. The body of the request must be a JSON object describing and including the contents of a file to attach.

Security:

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • content_type stringREQUIRED

      The mimetype of the uploaded file including the charset parameter, if needed. Example: "text/plain; charset=\"UTF-8\""

    • data stringREQUIRED

      Base64-encoded bytes of the file contents representing a maximum of 2.5 MiB of data when decoded. Padding with = chars is optional.

    • filename stringREQUIRED

      The name of the uploaded file (max 255 UTF-8 bytes). Multiple files with the same name are allowed in separate requests.

Responses

  • 201

    The email attachment was created. The response body will contain the IDs of the created attachments.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      The response body for an email attachment creation request.

      OBJECT PROPERTIES
      • attachment_id array[string]

        The attachment ID for a newly-created attachment. Reference this ID in the attachments list in the Email override.

      • ok boolean

        Either true or false. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    The application does not have the proper entitlement to create attachments.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Register email channel

POST /api/channels/email

Example

POST /api/channels/email HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

 {
    "channel" : {
        "type": "email",
        "commercial_opted_in": "2020-10-28T10:34:22",
        "open_tracking_opted_in": "2022-12-11T00:00:00",
        "click_tracking_opted_in": "2022-12-11T00:00:00",
        "address": "name@example.com",
        "timezone" : "America/Los_Angeles",
        "locale_country" : "US",
        "locale_language" : "en"
    },
    "opt_in_mode" : "classic",
    "properties" : {
        "interests" : "newsletter"
    },
    "tag_operations": {
      "add": {
        "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
        "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
        "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
      }
    },
    "attributes": {
        "my_fav_attribute1": "attribute1",
        "my_fav_attribute2": "attribute2"
    }
 }

HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/channels/251d3318-b3cb-4e9f-876a-ea3bfa6e47bd
Content-Type: application/json

{
    "ok": true,
    "channel_id": "251d3318-b3cb-4e9f-876a-ea3bfa6e47bd",
    "attributes": {"ok": true},
    "tags": {"ok": true}
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

RegisterEmailChannel emailChannel = RegisterEmailChannel.newBuilder()
        .setAddress("name@example.com")
        .setEmailOptInLevel(OptInLevel.EMAIL_COMMERCIAL_OPTED_IN, "2020-10-28T10:34:22")
        .setEmailOptInMode(OptInMode.CLASSIC)
        .addProperty("interests","newletter")
        .build();

RegisterEmailChannelRequest request = RegisterEmailChannelRequest.newRequest(emailChannel);
Response<EmailChannelResponse> response = client.execute(request);

from urbanairship import (
    BearerTokenClient, Email
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

email = Email(
    client=client,
    address='name@example.com',
    commercial_opted_in='2020-10-28T10:34:22',
    timezone='America/Los_Angeles',
    locale_country='US',
    locale_language='en'
)
response = email.register()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_channel = UA::Email.new(client: airship)
email_channel.type = 'email'
email_channel.commercial_opted_in = '2020-10-28T10:34:22'
email_channel.address = 'name@example.com'
email_channel.timezone = 'America/Los_Angeles'
email_channel.locale_country = 'US'
email_channel.locale_language = 'en'
email_channel.register

Create a new email channel or update an existing channel. If you provide the email address of an existing channel, the call is treated as a PUT. To update the address of an existing channel, see the Replace Email Channel endpoint.

Security:

Request body:

A single email channel object.

  • Content-Type: application/json

    Email channel object

    An email channel object is the object used to create channels.

    There are two types of emails: commercial and transactional. Commercial emails are promotional. Transactional emails are functional responses to interactions with a your app or website, like receipts, legal notices, and password reset requests. Users must explicitly opt-in to receive commercial emails; users do not need to opt-in to receive transactional emails (though they can explicitly opt-out).

    Each channel uses opted_in and opted_out keys for both commercial and transactional emails. The value of each key is the date-time when the user subscribed to or unsubscribed from emails of either type — commercial or transactional. If a user has opted out of a particular email type (or the user never opted in to 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. These values are all optional. However, an email channel with no opted_in or opted_out values can only receive transactional emails.

    If a channel has both opt_in and opt_out values for a particular email type, Airship respects the most recent date-time. So, if a user opted in to 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.

    Providing both opt-in and opt-out values for commercial email, transactional email, open tracking, or click tracking in a single request is considered invalid.

    OBJECT PROPERTIES
    • attributes object

      An optional object containing the customer-provided attributes associated with the email.

    • channel objectREQUIRED
      OBJECT PROPERTIES
      • address stringREQUIRED

        The email address being registered.

      • click_tracking_opted_in string

        The date-time when a user opted in to click tracking.

      • click_tracking_opted_out string

        The date-time when a user opted out of click tracking.

      • commercial_opted_in string

        The date-time when a user gave explicit permission to receive commercial emails.

      • commercial_opted_out string

        The date-time when a user explicitly denied permission to receive commercial emails.

      • locale_country string

        The device property tag related to locale country setting.

      • locale_language string

        The device property tag related to locale language setting.

      • open_tracking_opted_in string

        The date-time when a user opted in to open tracking.

      • open_tracking_opted_out string

        The date-time when a user opted out of open tracking.

      • suppression_state string

        If an email channel is suppressed, the reason for its suppression. Email channels with any suppression state set will not have any delivery to them fulfilled. If a more specific reason is not known, use imported.

        Possible values: spam_complaint, commercial_spam_complaint, bounce, imported

      • timezone string

        The device property tag related to time zone setting.

      • transactional_opted_in string

        The date-time when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out.

      • transactional_opted_out string

        The date-time when a user explicitly denied permission to receive transactional emails.

      • type stringREQUIRED

        The type of channel you are registering.

        Possible values: email

    • opt_in_mode string

      The opt-in mode for registering the channel. classic is the default when unspecified, double creates a double_opt_in event.

      Possible values: classic, double

    • properties object

      An object containing event properties. You can use these properties to filter the double opt-in event and reference them in your message content by using handlebars. Items in the properties object are limited to a 255-character maximum string length.

    • tag_operations object<Tag Group object>

      Optionally one or more tag group objects associated with the email.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 200

    An existing email channel was found matching the address and was updated.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      The response body for an email channel request.

      OBJECT PROPERTIES
      • attributes object
        OBJECT PROPERTIES
        • ok boolean

          If true, the attributes were set correctly.

      • channel_id string

        A unique string identifying the email channel.

      • ok booleanREQUIRED

        If true, the operation was successful. If false, other properties defined here will not necessarily be present.

      • tags object
        OBJECT PROPERTIES
        • ok boolean

          If true, the tags were set correctly.

  • 201

    The email channel was created.

    Response headers:

    • Location string

      The newly created email channel.

    Response body:

    • Content-Type: text/plain

      The response body for an email channel request.

      OBJECT PROPERTIES
      • channel_id string

        A unique string identifying the email channel.

      • ok booleanREQUIRED

        Either true or false. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Custom unsubscribe email channel

GET /api/channels/email/custom-unsubscribe

Example

GET /api/channels/email/custom-unsubscribe?ua_redirect=https://example.com/success.html&ua_unsubscribe_token=eyJhcHBfa2V5IjoiVmwwd3lHOGtTeUN5T1VXOThXajR4ZyIsImNhbXBhaWducyI6W10sInB1c2hfaWQiOiJlY2U0MDliMC0yNzYyLTExZWUtYjE4Ny0wMjQyNDkzZjM2MTkiLCJtZXNzYWdlX3R5cGUiOiJjb21tZXJjaWFsIiwiY2hhbm5lbF9pZCI6Ik9IWWdxTDJfU3FHMTRQZWlfWjV2QkEifQ%3D%3D HTTP/1.1
Accept: */*

HTTP/1.1 302 Found
Location: https://example.com/success.html

Opts-out an email address using a custom unsubscribe token. Requires Custom Unsubscribe be enabled for your project.

This endpoint is public and does not require authentication.

Query parameters:

  • ua_unsubscribe_token stringREQUIRED
    The token for the unsubscribe request.
  • ua_redirect string
    URL of the page to redirect to after unsubscribe. A default confirmation page will be used if not provided.

Responses

  • 302

    The channel was successfully opted out and will be redirected to a confirmation page.

    Response headers:

    • Location string

      URL of the page to redirect to after unsubscribe.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Replace email channel

POST /api/channels/email/replace/{channel_id}

Example

POST /api/channels/email/replace/9c36e8c7-5a73-47c0-9716-99fd3d4197d5 HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "channel" : {
      "type": "email",
      "commercial_opted_in": "2022-02-13T11:58:59",
      "address": "name@example.com",
      "timezone" : "America/Los_Angeles",
      "locale_country" : "US",
      "locale_language" : "en"
   }
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://go.urbanairship.com/api/channels/251d3318-b3cb-4e9f-876a-ea3bfa6e47bd

{
    "ok": true,
    "channel_id": "251d3318-b3cb-4e9f-876a-ea3bfa6e47bd"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

RegisterEmailChannel emailChannel = RegisterEmailChannel.newBuilder()
        .setAddress("name@example.com")
        .setEmailOptInLevel(OptInLevel.EMAIL_COMMERCIAL_OPTED_IN, "2022-02-13T11:58:59")
        .setTimeZone("America/Los_Angeles")
        .setLocaleCountry("US")
        .setLocaleLanguage("en")
        .build();

ReplaceEmailChannelRequest request = ReplaceEmailChannelRequest.newRequest("9c36e8c7-5a73-47c0-9716-99fd3d4197d5", emailChannel);
Response<EmailChannelResponse> response = client.execute(request);

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_channel = UA::Email.new(client: airship)
email_channel.channel_id = '251d3318-b3cb-4e9f-876a-ea3bfa6e47bd'
email_channel.address = 'tommy@example.com'
email_channel.type = 'email'
email_channel.commercial_opted_in = '2020-10-28T10:34:22'
email_channel.replace

Creates a new email channel in place of the provided channel. You may use this endpoint to change a contact’s email address. When called with an email channel, this endpoint will:

  • Register a new channel
  • Associate the new email channel with the same user as the source channel
  • Uninstall the source channel

Security:

Path parameters:

  • channel_id stringREQUIRED
    The email channel_id you want to modify.

Request body:

A single email channel object.

  • Content-Type: application/json

    Email channel object

    An email channel object is the object used to create channels.

    There are two types of emails: commercial and transactional. Commercial emails are promotional. Transactional emails are functional responses to interactions with a your app or website, like receipts, legal notices, and password reset requests. Users must explicitly opt-in to receive commercial emails; users do not need to opt-in to receive transactional emails (though they can explicitly opt-out).

    Each channel uses opted_in and opted_out keys for both commercial and transactional emails. The value of each key is the date-time when the user subscribed to or unsubscribed from emails of either type — commercial or transactional. If a user has opted out of a particular email type (or the user never opted in to 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. These values are all optional. However, an email channel with no opted_in or opted_out values can only receive transactional emails.

    If a channel has both opt_in and opt_out values for a particular email type, Airship respects the most recent date-time. So, if a user opted in to 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.

    Providing both opt-in and opt-out values for commercial email, transactional email, open tracking, or click tracking in a single request is considered invalid.

    OBJECT PROPERTIES
    • attributes object

      An optional object containing the customer-provided attributes associated with the email.

    • channel objectREQUIRED
      OBJECT PROPERTIES
      • address stringREQUIRED

        The email address being registered.

      • click_tracking_opted_in string

        The date-time when a user opted in to click tracking.

      • click_tracking_opted_out string

        The date-time when a user opted out of click tracking.

      • commercial_opted_in string

        The date-time when a user gave explicit permission to receive commercial emails.

      • commercial_opted_out string

        The date-time when a user explicitly denied permission to receive commercial emails.

      • locale_country string

        The device property tag related to locale country setting.

      • locale_language string

        The device property tag related to locale language setting.

      • open_tracking_opted_in string

        The date-time when a user opted in to open tracking.

      • open_tracking_opted_out string

        The date-time when a user opted out of open tracking.

      • suppression_state string

        If an email channel is suppressed, the reason for its suppression. Email channels with any suppression state set will not have any delivery to them fulfilled. If a more specific reason is not known, use imported.

        Possible values: spam_complaint, commercial_spam_complaint, bounce, imported

      • timezone string

        The device property tag related to time zone setting.

      • transactional_opted_in string

        The date-time when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out.

      • transactional_opted_out string

        The date-time when a user explicitly denied permission to receive transactional emails.

      • type stringREQUIRED

        The type of channel you are registering.

        Possible values: email

    • opt_in_mode string

      The opt-in mode for registering the channel. classic is the default when unspecified, double creates a double_opt_in event.

      Possible values: classic, double

    • properties object

      An object containing event properties. You can use these properties to filter the double opt-in event and reference them in your message content by using handlebars. Items in the properties object are limited to a 255-character maximum string length.

    • tag_operations object<Tag Group object>

      Optionally one or more tag group objects associated with the email.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 201

    The operation was successful.

    Response headers:

    • Location string

      The newly created email channel.

    Response body:

    • Content-Type: text/plain

      The response body for an email channel request.

      OBJECT PROPERTIES
      • channel_id string

        A unique string identifying the email channel.

      • ok boolean

        Either true or false. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Suppress an email channel

POST /api/channels/email/suppress

Example

POST /api/channels/email/suppress HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "address": "name@example.com",
    "reason": "spam_complaint"
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SuppressEmailChannelRequest request = SuppressEmailChannelRequest.newRequest("name@example.com","reason");
Response<GenericResponse> response = client.execute(request);

Suppress an existing email channel, disallowing any future delivery from being fulfilled for the channel.

 Note

Suppression state types that only apply to commercial messages, such as commercial_spam_complaint, cannot overwrite suppression state types that also apply to transactional messages.

Security:

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • address stringREQUIRED

      The email address for the channel to be suppressed.

    • reason stringREQUIRED

      The reason for suppressing the channel. If there is no specific reason, use imported.

      Possible values: spam_complaint, commercial_spam_complaint, bounce, imported

Responses

  • 202

    Returns OK for success.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Email tags

POST /api/channels/email/tags

Example

POST /api/channels/email/tags HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
      "email_address": "name@example.com"
   },
   "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

EmailTagRequest request = EmailTagRequest.newRequest();
emailTagRequest.addEmailChannel("name@example.com")
        .addTags("my_fav_tag_group1", ImmutableSet.of("tag1", "tag2", "tag3"))
        .addTags("my_fav_tag_group2", ImmutableSet.of("tag1", "tag2", "tag3"))
        .addTags("my_fav_tag_group3", ImmutableSet.of("tag1", "tag2", "tag3"));

Response<EmailChannelResponse> response = client.execute(request);

from urbanairship import (
    BearerTokenClient, EmailTags
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

# replaces all existing tags on an email channel
email_tags = EmailTags(airship=client,
                          address='name@example.com')
email_tags.set(group='my_tag_group',
              tags=['one', 'two', 'three'])
email_tags.send()

# adds and removes tags from an email channel
email_tags = EmailTags(airship=client,
                          address='name@example.com')
email_tags.remove(group='my_tag_group',
                  tags=['one', 'two', 'three'])
email_tags.add(group='my_tag_group',
              tags=['some', 'new', 'tags'])
email_tags.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_tags = UA::EmailTags.new(client: airship)
#set an audience
email_tags.set_audience(email_address: 'name@example.com')
#add a tag
email_tags.add(group_name: 'my_fav_tag_group1', tags: 'tag2')
#remove a tag
email_tags.remove(group_name: 'my_fav_tag_group1', tags: 'tag1')
email_tags.send_request

Add, remove, or set tags for a single email channel.

Security:

Request body:

A single request body can contain an add and/or remove field or a single set field. One or more of the add, remove, or set keys must be present in the request.

  • Content-Type: application/json

    OBJECT PROPERTIES
    • add object<Tag Group object>

      Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • audience objectREQUIRED

      Specifies the email address you want to perform tag operations against. Must contain a single email_address key.

      OBJECT PROPERTIES
      • email_address stringREQUIRED

        The email address you want to modify tags for. Accepts a single string value representing an email address.

    • remove object<Tag Group object>

      Removes the specified tags from the channel.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • set object<Tag Group object>

      Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 200

    Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 will be returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Uninstall email channel

POST /api/channels/email/uninstall

Example

POST /api/channels/email/uninstall HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "email_address": "name@example.com"
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

UninstallEmailChannel uninstallEmailChannel = UninstallEmailChannel.newBuilder()
        .setEmailAddress("name@example.com")
        .build();

UninstallEmailChannelRequest request = UninstallEmailChannelRequest.newRequest(uninstallEmailChannel);
Response<EmailChannelResponse> response = client.execute(request);

from urbanairship import (
    BearerTokenClient, Email
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)
email = Email(airship=client,
                address='name@example.com')
resp = email.uninstall()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_channel = UA::Email.new(client: airship)
email_channel.address = 'name@example.com'
email_channel.uninstall

Removes an email address from Airship. Use with caution. If the uninstalled email address opts-in again, it might generate a new channel_id. If a user generates a new channel_id when they opt-in again, the new channel_id cannot be reassociated with any opt-in information, tags, Named Users, Performance Analytics reports, or other information from the that belonged to the previously-uninstalled email channel.

Security:

Request body:

An email address of the channel to uninstall.

  • Content-Type: application/json

    OBJECT PROPERTIES
    • email_address stringREQUIRED

      The email address of the channel to uninstall.

Responses

  • 202

    Returns OK for success.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Remove suppression from an email channel

POST /api/channels/email/unsuppress

Example

POST /api/channels/email/unsuppress HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "address": "name@example.com"
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

UnsuppressEmailChannelRequest request = UnsuppressEmailChannelRequest.newRequest("name@example.com");
Response<GenericResponse> response = client.execute(request);

Remove the suppression reason for an existing email channel, allowing the channel to receive emails, depending on the channel’s commercial and transactional opt-in status.

Security:

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • address stringREQUIRED

      The email address for the channel to be unsuppressed.

Responses

  • 202

    Returns OK for success.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Look up an email address

GET /api/channels/email/{email}

Example

GET /api/channels/email/name%40example.com HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "channel": {
      "channel_id": "01234567-890a-bcde-f012-3456789abc0",
      "device_type": "email",
      "installed": true,
      "created": "2020-08-08T20:41:06",
      "named_user_id": "some_id_that_maps_to_your_systems",
      "email_address": "name@example.com",
      "tag_groups": {
         "tag_group_1": ["tag1", "tag2"],
         "tag_group_2": ["tag1", "tag2"]
      },
      "address": null,
      "opt_in": true,
      "commercial_opted_in": "2020-10-28T10:34:22",
      "commercial_opted_out": "2020-06-03T09:15:00",
      "transactional_opted_in": "2020-10-28T10:34:22",
      "open_tracking_opted_in": "2022-12-11T00:00:00",
      "click_tracking_opted_in": "2022-12-11T00:00:00",
      "open_tracking_opted_out": "2022-12-12T00:00:00",
      "click_tracking_opted_out": "2022-12-12T00:00:00",
      "last_registration": "2020-05-01T18:00:27"
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();
        
ChannelRequest channelRequest = ChannelRequest.newEmailLookupRequest("name@example.com");
Response<ChannelResponse> response = client.execute(channelRequest);

from urbanairship import (
    BearerTokenClient, Email
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

response = Email.lookup(airship=client, address='name@example.com')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_channel = UA::Email.new(client: airship)
email_channel.address = 'name@example.com'
email_channel.lookup

Returns a channel by email address. For security, email addresses are one-way hashed and aren’t returned when you look up a channel by ID. Use this endpoint to find a channel belonging to a particular email address.

You may need to escape the @ character in URLs using%40.

 Note

Emails with an opted_out date that is after or equal to the opted_in date will not be sent for that channel.

A commercial_opted_in date is required for sending commercial emails. Transactional emails do not require a transactional_opted_in. This field is used in the case where a user has unsubscribed to transactional email and would like to reassert consent to receive transactional emails.

The opt_in property is always set to true for an email channel, so it should be ignored.

Security:

Path parameters:

  • email stringREQUIRED
    The email address of the channel you want to look up.

Responses

  • 200

    A channel exists for the email address

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update an email channel

PUT /api/channels/email/{email}

Example update email address

PUT /api/channels/email/251d3318-b3cb-4e9f-876a-ea3bfa6e47bd HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

 {
     "channel" : {
        "device_type": "email",
        "address": "tommy@example.com",
        "commercial_opted_in": "2020-10-28T10:34:22"
     }
  }

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
Location: https://go.urbanairship.com/api/channels/251d3318-b3cb-4e9f-876a-ea3bfa6e47bd

{
    "ok": true,
    "channel_id": "251d3318-b3cb-4e9f-876a-ea3bfa6e47bd"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();
        
UpdateEmailChannel updateEmailChannel = UpdateEmailChannel.newBuilder()
        .setAddress("name@example.com")
        .setEmailOptInLevel(OptInLevel.EMAIL_COMMERCIAL_OPTED_IN, "2021-10-28T10:34:22")
        .setEmailOptInLevel(OptInLevel.EMAIL_TRANSACTIONAL_OPTED_IN,"2021-10-28T10:34:22")
        .build();

UpdateEmailChannelRequest updateEmailChannelRequest = UpdateEmailChannelRequest.newRequest("6c8f1d3a-64d8-4ef9-b7a1-9b128013327e", updateEmailChannel);
Response<EmailChannelResponse> response = client.execute(updateEmailChannelRequest);

from urbanairship import (
    BearerTokenClient, Email
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

email = Email(
    client=client,
    address='tommy@example.com',
    commercial_opted_in='2020-10-28T10:34:22'
)

response = email.update(channel_id='251d3318-b3cb-4e9f-876a-ea3bfa6e47bd')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_channel = UA::Email.new(client: airship)
email_channel.channel_id = '251d3318-b3cb-4e9f-876a-ea3bfa6e47bd'
email_channel.type = 'email'
email_channel.commercial_opted_in = '2020-10-28T10:34:22'
email_channel.update

Update an email channel. You can use this endpoint to update the subscription/unsubscription values.

Security:

Path parameters:

  • email stringREQUIRED
    The email channel_id you want to modify.

Request body:

  • Content-Type: application/json

    Email channel update object

    An email channel object is the object used to update channels.

    There are two types of emails: commercial and transactional. Commercial emails are promotional. Transactional emails are functional responses to interactions with a your app or website, like receipts, legal notices, and password reset requests. Users must explicitly opt-in to receive commercial emails; users do not need to opt-in to receive transactional emails (though they can explicitly opt-out).

    Each channel uses opted_in and opted_out keys for both commercial and transactional emails. The value of each key is the date-time when the user subscribed to or unsubscribed from emails of either type — commercial or transactional. If a user has opted out of a particular email type (or the user never opted in to 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. These values are all optional. However, an email channel with no opted_in or opted_out values can only receive transactional emails.

    If a channel has both opt_in and opt_out values for a particular email type, Airship respects the most recent date-time. So, if a user opted in to 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.

    OBJECT PROPERTIES
    • channel objectREQUIRED
      OBJECT PROPERTIES
      • address string

        The email address associated with the email channel. If provided, it must match the existing email address or the request will be rejected with a 400 status code.

      • commercial_opted_in string

        The date-time when a user gave explicit permission to receive commercial emails.

      • commercial_opted_out string

        The date-time when a user explicitly denied permission to receive commercial emails.

      • device_type string

        The type of channel you are updating.

        Possible values: email

      • locale_country string

        The device property tag related to locale country setting.

      • locale_language string

        The device property tag related to locale language setting.

      • suppression_state string

        If an email channel is suppressed, the reason for its suppression. Email channels with any suppression state set will not have any delivery to them fulfilled. If a more specific reason is not known, use imported.

        Possible values: spam_complaint, commercial_spam_complaint, bounce, imported

      • timezone string

        The device property tag related to time zone setting.

      • transactional_opted_in string

        The date-time when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out.

      • transactional_opted_out string

        The date-time when a user explicitly denied permission to receive transactional emails.

Responses

  • 200

    The email channel was updated.

    Response headers:

    • Location string

      The updated email channel.

    Response body:

    • Content-Type: text/plain

      The response body for an email channel request.

      OBJECT PROPERTIES
      • channel_id string

        A unique string identifying the email channel.

      • ok boolean

        Either true or false. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

SMS

Register and manage SMS channels. See SMS Platform Information to get started with SMS notifications.

Register SMS channel

POST /api/channels/sms

Example

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

{
  "msisdn" : "15035556789",
  "sender": "12345",
  "opted_in": "2020-02-13T11:58:59",
  "timezone": "America/Los_Angeles",
  "locale_country": "US",
  "locale_language": "en",
  "tag_operations": {
    "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
    }
  },
  "attributes": {
      "my_fav_attribute1": "attribute1",
      "my_fav_attribute2": "attribute2"
  }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SmsRegistrationRequest request = SmsRegistrationRequest
        .newRegistrationRequest("12345", "15035556789", DateTime.parse("2020-02-13T11:58:59Z"));

Response<SmsRegistrationResponse> response = client.execute(request);

from urbanairship import (
    BearerTokenClient, Sms
)
from datetime import datetime

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

sms_channel = Sms(
    client=client,
    sender="12345",
    msisdn="15035556789",
    opted_in=datetime.fromisoformat("2020-02-13T11:58:59"),
    locale_country="US",
    locale_language="en",
    timezone="America/Los_Angeles"
)

response = sms_channel.register()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.opted_in = '2020-02-13T11:58:59'
sms_channel.register

Response (With 'opted_in')

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

{
  "msisdn" : "15035556789",
  "sender": "12345",
  "opted_in": "2020-02-13T11:58:59",
  "timezone": "America/Los_Angeles",
  "locale_country": "US",
  "locale_language": "en",
  "tag_operations": {
    "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
    }
  },
  "attributes": {
      "my_fav_attribute1": "attribute1",
      "my_fav_attribute2": "attribute2"
  }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SmsRegistrationRequest request = SmsRegistrationRequest
        .newRegistrationRequest("12345", "15035556789", DateTime.parse("2020-02-13T11:58:59Z"));

Response<SmsRegistrationResponse> response = client.execute(request);

from urbanairship import (
    BearerTokenClient, Sms
)
from datetime import datetime

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

sms_channel = Sms(
    client=client,
    sender="12345",
    msisdn="15035556789",
    opted_in=datetime.fromisoformat("2020-02-13T11:58:59"),
    locale_country="US",
    locale_language="en",
    timezone="America/Los_Angeles"
)

response = sms_channel.register()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.opted_in = '2020-02-13T11:58:59'
sms_channel.register

HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/channels/7c5d7328-9bb4-4ff7-86b0-96a5f1da5868
Content-Type: application/json

{
  "ok": true,
  "operation_id": "62077236-d032-11e9-af71-ab156113d166",
  "channel_id": "7c5d7328-9bb4-4ff7-86b0-96a5f1da5868",
  "attributes": {"ok": true},
  "tags": {"ok": true}
}

Response (Without 'opted_in')

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

{
  "msisdn" : "15035556789",
  "sender": "12345",
  "opted_in": "2020-02-13T11:58:59",
  "timezone": "America/Los_Angeles",
  "locale_country": "US",
  "locale_language": "en",
  "tag_operations": {
    "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
    }
  },
  "attributes": {
      "my_fav_attribute1": "attribute1",
      "my_fav_attribute2": "attribute2"
  }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SmsRegistrationRequest request = SmsRegistrationRequest
        .newRegistrationRequest("12345", "15035556789", DateTime.parse("2020-02-13T11:58:59Z"));

Response<SmsRegistrationResponse> response = client.execute(request);

from urbanairship import (
    BearerTokenClient, Sms
)
from datetime import datetime

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

sms_channel = Sms(
    client=client,
    sender="12345",
    msisdn="15035556789",
    opted_in=datetime.fromisoformat("2020-02-13T11:58:59"),
    locale_country="US",
    locale_language="en",
    timezone="America/Los_Angeles"
)

response = sms_channel.register()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.opted_in = '2020-02-13T11:58:59'
sms_channel.register

HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/channels/7c5d7328-9bb4-4ff7-86b0-96a5f1da5868
Content-Type: application/json

{
  "ok": true,
  "operation_id": "62077236-d032-11e9-af71-ab156113d166",
  "channel_id": "7c5d7328-9bb4-4ff7-86b0-96a5f1da5868",
  "attributes": {"ok": true},
  "tags": {"ok": true}
}

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://go.urbanairship.com/api/channels/79fbe330-d033-11e9-adfb-df10b89c5e04

{
  "ok": true,
  "operation_id": "62077236-d032-11e9-af71-ab156113d166",
  "push_id": "26350f60-d033-11e9-80e3-33def0e528d1",
  "channel_id": "79fbe330-d033-11e9-adfb-df10b89c5e04",
  "status": "pending",
  "attributes": {"ok": true},
  "tags": {"ok": true}
}

Response (Project not configured with sender)

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

{
  "msisdn" : "15035556789",
  "sender": "12345",
  "opted_in": "2020-02-13T11:58:59",
  "timezone": "America/Los_Angeles",
  "locale_country": "US",
  "locale_language": "en",
  "tag_operations": {
    "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
    }
  },
  "attributes": {
      "my_fav_attribute1": "attribute1",
      "my_fav_attribute2": "attribute2"
  }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SmsRegistrationRequest request = SmsRegistrationRequest
        .newRegistrationRequest("12345", "15035556789", DateTime.parse("2020-02-13T11:58:59Z"));

Response<SmsRegistrationResponse> response = client.execute(request);

from urbanairship import (
    BearerTokenClient, Sms
)
from datetime import datetime

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

sms_channel = Sms(
    client=client,
    sender="12345",
    msisdn="15035556789",
    opted_in=datetime.fromisoformat("2020-02-13T11:58:59"),
    locale_country="US",
    locale_language="en",
    timezone="America/Los_Angeles"
)

response = sms_channel.register()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.opted_in = '2020-02-13T11:58:59'
sms_channel.register

HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/channels/7c5d7328-9bb4-4ff7-86b0-96a5f1da5868
Content-Type: application/json

{
  "ok": true,
  "operation_id": "62077236-d032-11e9-af71-ab156113d166",
  "channel_id": "7c5d7328-9bb4-4ff7-86b0-96a5f1da5868",
  "attributes": {"ok": true},
  "tags": {"ok": true}
}

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://go.urbanairship.com/api/channels/79fbe330-d033-11e9-adfb-df10b89c5e04

{
  "ok": true,
  "operation_id": "62077236-d032-11e9-af71-ab156113d166",
  "push_id": "26350f60-d033-11e9-80e3-33def0e528d1",
  "channel_id": "79fbe330-d033-11e9-adfb-df10b89c5e04",
  "status": "pending",
  "attributes": {"ok": true},
  "tags": {"ok": true}
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "ok": false,
    "errors": "Unable to retrieve details for sender 12345 with app_key <application key>"
}

Create an SMS channel. If the channel has not opted in yet (the request did not contain opted_in), Airship creates the channel with opt_in set to false and the user receives a message prompting them to complete the opt-in flow; you can assign tags and organize pending channels before the user has finished the opt-in process, but you cannot send messages to channels until they opt in to your audience.

SMS notifications require a sender - a number that recipients will receive SMS notifications from. Contact Airship Sales  or your Account Manager to provision your project for SMS notifications and complete the configuration.

 Note

Avoid repeated registration attempts. Repeated registrations of the same MSISDN and sender without an opted_in value will result in multiple opt-in instruction messages being sent to the MSISDN.

Security:

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • attributes object

      An optional object containing the customer-provided attributes associated with the SMS channel.

    • locale_country string

      The ISO 3166 two-character country code. The value for this field becomes a tag in the ua_locale_country tag group.

    • locale_language string

      The ISO 639-1 two-character language code. The value for this field becomes a tag in the ua_locale_language tag group.

    • msisdn stringREQUIRED

      The mobile phone number you want to register as an SMS channel (or send a request to opt-in). Must be numeric characters only, without leading zeros.

    • opted_in string

      The date-time that represents the date and time when explicit permission was received from the user to receive messages.

    • sender stringREQUIRED

      A long or short code the app is configured to send from. For example, 12345.

    • tag_operations object<Tag Group object>

      Optionally one or more tag group objects associated with the SMS channel.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • timezone string

      The IANA identifier for a time zone, e.g., America/Los_Angeles. The value in this field becomes a tag in the timezone tag group.

Responses

  • 200

    A channel with this msisdn/sender combination already exists.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      One of
      • New channel with opt-in object

        The request included a valid opted_in value. Airship creates a channel that is opted in to your audience.

        OBJECT PROPERTIES
        • attributes object
          OBJECT PROPERTIES
          • ok boolean

            If true, the attributes were set correctly.

        • channel_id string

          Unique Channel ID for the SMS channel.

        • ok boolean

          If true, Airship creates a channel value with opt_in set to true.

        • operation_id string

          A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.

        • tags object
          OBJECT PROPERTIES
          • ok boolean

            If true, the tags were set correctly.

      • New channel without opt-in object

        Response to a request that does not include an opted_in value. Airship creates a channel with opt_in set to false and sends the user a message prompting them to opt in.

        OBJECT PROPERTIES
        • attributes object
          OBJECT PROPERTIES
          • ok boolean

            If true, the attributes were set correctly.

        • channel_id stringREQUIRED

          Unique Channel ID for the SMS channel. This channel is created with opt_in set to false, as the user has not yet opted in to your audience.

        • ok booleanREQUIRED

          If true, Airship creates a channel with opt_in set to false and Airship sends a message prompting the user to opt in to your audience.

        • operation_id stringREQUIRED

          A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.

        • push_id stringREQUIRED

          Identifies the message prompting the user to opt in to your audience, sent as a result of a request without an opted_in value.

        • status stringREQUIRED

          The channel has been created but has not yet opted-in.

          Possible values: pending

        • tags object
          OBJECT PROPERTIES
          • ok boolean

            If true, the tags were set correctly.

  • 201

    The channel was created. If the request did not contain an opted_in value, the channel is created with a pending status and the channel’s opt_in value is set to false; you can assign assign tags and organize pending channels before the user has finished the opt-in process, but you cannot send messages to channels until they complete the opt-in flow.

    Response headers:

    • location string

      URI of the channel, used for later registrations.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      One of
      • New channel with opt-in object

        The request included a valid opted_in value. Airship creates a channel that is opted in to your audience.

        OBJECT PROPERTIES
        • attributes object
          OBJECT PROPERTIES
          • ok boolean

            If true, the attributes were set correctly.

        • channel_id string

          Unique Channel ID for the SMS channel.

        • ok boolean

          If true, Airship creates a channel value with opt_in set to true.

        • operation_id string

          A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.

        • tags object
          OBJECT PROPERTIES
          • ok boolean

            If true, the tags were set correctly.

      • New channel without opt-in object

        Response to a request that does not include an opted_in value. Airship creates a channel with opt_in set to false and sends the user a message prompting them to opt in.

        OBJECT PROPERTIES
        • attributes object
          OBJECT PROPERTIES
          • ok boolean

            If true, the attributes were set correctly.

        • channel_id stringREQUIRED

          Unique Channel ID for the SMS channel. This channel is created with opt_in set to false, as the user has not yet opted in to your audience.

        • ok booleanREQUIRED

          If true, Airship creates a channel with opt_in set to false and Airship sends a message prompting the user to opt in to your audience.

        • operation_id stringREQUIRED

          A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.

        • push_id stringREQUIRED

          Identifies the message prompting the user to opt in to your audience, sent as a result of a request without an opted_in value.

        • status stringREQUIRED

          The channel has been created but has not yet opted-in.

          Possible values: pending

        • tags object
          OBJECT PROPERTIES
          • ok boolean

            If true, the tags were set correctly.

  • 400

    The channel could not be created. This error occurs when the project is not configured with a valid sender, the request was missing required fields, or the MSISDN does not meet the E.164 international standard.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • errors string

        Returned with 40x responses; explains reason for the unsuccessful request.

      • ok boolean

        If false, the request was unsuccessful.

Opt-out of SMS messages

POST /api/channels/sms/opt-out

Example

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

{
    "sender": "12345",
    "msisdn": "15035556789"
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SmsRegistrationRequest request = SmsRegistrationRequest
        .newOptOutRequest("12345", "15035556789");

Response<SmsRegistrationResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Sms
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

sms = Sms(
    client=client,
    sender='12345',
    msisdn='15035556789'
)
response = sms.opt_out()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.opt_out

This will mark an SMS channel as opted-out (inactive) and it will not receive alerts even when they are addressed in the future. To opt the user back in, call the registration function again with a valid opted_in value.

Security:

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • msisdn stringREQUIRED

      The mobile phone number you want to opt-out of SMS messages. Must be numeric characters only, without leading zeros. 15 digits maximum.

    • sender stringREQUIRED

      A long or short code the app is configured to send from. For example, 12345.

Responses

  • 202

    The msisdn/channel is opted-out of SMS notifications.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        If true, the operation completed successfully.

  • 400

    The request body is not valid.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • details object
        OBJECT PROPERTIES
        • error string

          Specific error message that explains why the request was unsuccessful.

      • error string

        Returned with 40x responses; explains why the request was unsuccessful.

      • error_code integer

        The 5-digit Airship error code, pointing to a more specific error than the HTTP status.

      • ok boolean

        If false, the request was unsuccessful.

SMS tags

POST /api/channels/sms/tags

Example

POST /api/channels/sms/tags HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
    "sender": "12345",
    "msisdn": "15035556789"
   },
   "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
   }
}

Add, remove, or set tags for a single SMS channel.

Security:

Request body:

A single request body can contain an add and/or remove field or a single set field. One or more of the add, remove, or set keys must be present in the request.

  • Content-Type: application/json

    OBJECT PROPERTIES
    • add object<Tag Group object>

      Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • audience objectREQUIRED

      Specifies the MSISDN and sender you want to perform tag operations against.

      OBJECT PROPERTIES
      • msisdn string

        The mobile phone number corresponding to the SMS channel. Must be numeric characters only, without leading zeros. 15 digits maximum.

      • sender string

        A long or short code the app is configured to send from. For example, 12345.

    • remove object<Tag Group object>

      Removes the specified tags from the channel.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • set object<Tag Group object>

      Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 200

    Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 will be returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Uninstall SMS channel

POST /api/channels/sms/uninstall

Example

POST /api/channels/sms/uninstall HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "sender": "12345",
    "msisdn": "15035556789"
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SmsRegistrationRequest request = SmsRegistrationRequest
        .newUninstallRequest("12345", "15035556789");

Response<SmsRegistrationResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Sms
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

sms = Sms(
    client=client,
    sender='12345',
    msisdn='15035556789'
)
response = sms.uninstall()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.uninstall

Removes phone numbers and accompanying data from Airship. Use with caution. Uninstalling an SMS channel will prevent you from retrieving opt-in and opt-out history for the corresponding msisdn. If the uninstalled msisdn opts-in again, it will generate a new channel_id. The new channel_id cannot be reassociated with any opt-in information, tags, Named Users, Performance Analytics reports, or other information from the uninstalled SMS channel.

Security:

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • msisdn stringREQUIRED

      The mobile phone number you want to remove from the Airship system. Must be numeric characters only, without leading zeros. 15 digits maximum.

    • sender stringREQUIRED

      A long or short code the app is configured to send from. For example, 12345.

Responses

  • 202

    The SMS channel and all information associated with the msisdn is uninstalled.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        If true, the operation was successful.

  • 400

    The request body is not valid.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • details object
        OBJECT PROPERTIES
        • error string

          Specific error message that explains why the request was unsuccessful.

      • error string

        Returned with 40x responses; explains why the request was unsuccessful.

      • error_code integer

        The 5-digit Airship error code, pointing to a more specific error than the HTTP status.

      • ok boolean

        If false, the request was unsuccessful.

Update SMS channel

PUT /api/channels/sms/{channel_id}

Example

PUT /api/channels/sms/{channel_id} HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "msisdn": "15035556789",
  "sender": "12345",
  "opted_in": "2020-02-13T11:58:59",
  "timezone": "America/Los_Angeles",
  "locale_country": "US",
  "locale_language": "en"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

UpdateSmsChannel updateSmsChannel = UpdateSmsChannel.newBuilder()
        .setMsisdn("13609048615")
        .setSender("17372004196")
        .setOptedIn(DateTime.parse("2021-10-11T02:03:03"))
        .setLocaleCountry("US")
        .setLocaleLanguage("en")
        .setTimeZone("America/Los_Angeles")
        .build();

UpdateSmsChannelRequest updateSmsChannelRequest = UpdateSmsChannelRequest.newRequest("308303cf-9c10-4d71-9bc2-d9f3a671ed0c", updateSmsChannel);

Response<GenericResponse> response = client.execute(updateSmsChannelRequest);

from urbanairship import (
    BearerTokenClient, Sms
)
from datetime import datetime

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

sms_channel = Sms(
    client=client,
    sender="12345",
    msisdn="15035556789",
    opted_in=datetime.fromisoformat("2021-02-13T11:58:59"),
    locale_country="US",
    locale_language="en",
    timezone="America/Los_Angeles"
)

# Update properties
sms_channel.locale_country = "FR"
sms_channel.opted_in = datetime.fromisoformat("2020-02-13T11:58:59")

response = sms_channel.update()

Update an existing SMS channel to reflect opt-in date, time zone and/or locale changes. The msisdn and sender in the request must match the existing channel or the request will 404.

Security:

Path parameters:

  • channel_id stringREQUIRED
    The identifier for the SMS channel you want to update.

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • locale_country string

      The ISO 3166 two-character country code. The value for this field becomes a tag in the ua_locale_country tag group.

    • locale_language string

      The ISO 639-1 two-character language code. The value for this field becomes a tag in the ua_locale_language tag group.

    • msisdn stringREQUIRED

      The phone number corresponding to the channel_id in the request. You cannot change this value for the existing channel.

    • opted_in string

      The date-time that represents when explicit permission was received from the user to receive messages.

    • sender stringREQUIRED

      The sender corresponding to the channel_id in the request. You cannot change this value for an existing channel.

    • timezone string

      The IANA identifier for a time zone, e.g., America/Los_Angeles. The value in this field becomes a tag in the timezone tag group.

Responses

  • 200

    The SMS channel was updated successfully.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        True if the request was successful.

      • operation_id string

        A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.

  • 400

    The request to update the channel failed. This error occurs when the MSISDN does not fall into the geographical region supported by the sender or the request is incorrect, e.g., missing or mismatching msisdn or sender, the msisdn is not a valid E.164 standard MSISDN, or invalid timezone/locale values are supplied.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • errors string

        Returned with 40x responses; explains reason for the unsuccessful request.

      • ok boolean

        If false, the request was unsuccessful.

  • 404

    Occurs when the msisdn and/or sender don’t match any existing channel_id.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • errors string

        A plain-text explanation of the error.

      • ok boolean

        If false, your request was unsuccessful.

SMS channel lookup

GET /api/channels/sms/{msisdn}/{sender}

Example

GET /api/channels/sms/15035556789/12345 HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Attribute: channel
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "channel": {
      "channel_id": "84e36d69-873b-4ffe-81cd-e74c9f002057",
      "device_type": "sms",
      "installed": true,
      "push_address": null,
      "named_user_id": null,
      "alias": null,
      "tags": [],
      "tag_groups": {
         "ua_channel_type": [
            "sms"
         ],
         "ua_sender_id": [
            "12345"
         ],
         "ua_opt_in": [
            "true"
         ]
      },
      "created": "2020-04-27T22:06:21",
      "opt_in": true,
      "opt_in_date": "2022-07-07T03:23:13",
      "msisdn": "150355551234",
      "last_registration": "2020-05-14T19:51:38"
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ChannelRequest channelRequest = ChannelRequest.newSmsLookupRequest("15035556789","12345");
Response<ChannelResponse> response = client.execute(channelRequest);

from urbanairship import (
    BasicAuthClient, Sms
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

sms = Sms(
    client=client,
    sender='12345',
    msisdn='15035556789'
)
channel_info = sms.lookup()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.lookup

Example opt_out_date

GET /api/channels/sms/15035556789/12345 HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Attribute: channel
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "channel": {
      "channel_id": "84e36d69-873b-4ffe-81cd-e74c9f002057",
      "device_type": "sms",
      "installed": true,
      "push_address": null,
      "named_user_id": null,
      "alias": null,
      "tags": [],
      "tag_groups": {
         "ua_channel_type": [
            "sms"
         ],
         "ua_sender_id": [
            "12345"
         ],
         "ua_opt_in": [
            "true"
         ]
      },
      "created": "2020-04-27T22:06:21",
      "opt_in": true,
      "opt_in_date": "2022-07-07T03:23:13",
      "msisdn": "150355551234",
      "last_registration": "2020-05-14T19:51:38"
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ChannelRequest channelRequest = ChannelRequest.newSmsLookupRequest("15035556789","12345");
Response<ChannelResponse> response = client.execute(channelRequest);

from urbanairship import (
    BasicAuthClient, Sms
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

sms = Sms(
    client=client,
    sender='12345',
    msisdn='15035556789'
)
channel_info = sms.lookup()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.lookup

HTTP/1.1 200 OK
Data-Attribute: channel
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "channel": {
      "channel_id": "84e36d69-873b-4ffe-81cd-e74c9f002057",
      "device_type": "sms",
      "installed": true,
      "push_address": null,
      "named_user_id": null,
      "alias": null,
      "tags": [],
      "tag_groups": {
         "ua_channel_type": [
            "sms"
         ],
         "ua_sender_id": [
            "12345"
         ],
         "ua_opt_in": [
            "true"
         ]
      },
      "created": "2020-04-27T22:06:21",
      "opt_in": false,
      "opt_in_date": "2022-07-07T03:23:13",
      "opt_out_date": "2022-07-08T03:23:13",
      "msisdn": "150355551234",
      "last_registration": "2020-05-14T19:51:38"
   }
}

Lookup an SMS channel by msisdn and sender.

Security:

Path parameters:

  • msisdn integerREQUIRED
    The mobile phone number you want to lookup a channel for. 15 digits maximum; may not contain leading zeroes.
  • sender integerREQUIRED
    A long or short code the app is configured to send from.

Responses

  • 200

    Returns an SMS channel object. An SMS channel object includes tag groups for ua_channel_type, ua_sender_id, and ua_opt_in.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES

  • 404

    A channel_id does not exist for the msisdn and sender.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • error string

        Returned with 40x responses; explains why the request was unsuccessful.

      • error_code integer

        The 5-digit Airship error code, pointing to a more specific error than the HTTP status.

      • ok boolean

        If false, the request was unsuccessful.

Custom SMS response

POST /api/sms/custom-response

SMS example

POST /api/sms/custom-response HTTP/1.1
Authorization: Bearer <authorization token>
X-UA-Appkey: <app key>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "sms" : {
      "alert": "Your balance is $1234.56. Go to https://www.example.com/myaccount/my-balance?ua-tag-add=balance_prefs:sms to see more about your account.",
      "shorten_links": true
  },
  "mobile_originated_id" : "28883743-4868-4083-ab5d-77ac4542531a"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setBearerToken("<token>")
        .build();

CustomSmsResponseSmsPayload customSmsResponseChannelSms = CustomSmsResponseSmsPayload.newBuilder()
        .setAlert("Your balance is $1234.56. Go to https://www.example.com/myaccount/my-balance?ua-tag-add=balance_prefs:sms to see more about your account.")
        .setMobileOriginatedId("28883743-4868-4083-ab5d-77ac4542531a")
        .setShortenLinks(true)
        .build();

CustomSmsResponseRequest customSmsResponseRequest = CustomSmsResponseRequest.newRequest(customSmsResponseChannelSms);
Response<CustomSmsResponseResponse> response = client.execute(customSmsResponseRequest);

from urbanairship import (
    BearerTokenClient, SmsCustomResponse,
    sms, mms
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

custom_response = SmsCustomResponse(
    client=client,
    mobile_originated_id="28883743-4868-4083-ab5d-77ac4542531a"
)

custom_response.sms = sms(
    alert="Your balance is $1234.56. Go to https://www.example.com/myaccount/my-balance?ua-tag-add=balance_prefs:sms to see more about your account.",
    shorten_links=True
)

response = custom_response.send()

MMS example

POST /api/sms/custom-response HTTP/1.1
Authorization: Bearer <authorization token>
X-UA-Appkey: <app key>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "sms" : {
      "alert": "Your balance is $1234.56. Go to https://www.example.com/myaccount/my-balance?ua-tag-add=balance_prefs:sms to see more about your account.",
      "shorten_links": true
  },
  "mobile_originated_id" : "28883743-4868-4083-ab5d-77ac4542531a"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setBearerToken("<token>")
        .build();

CustomSmsResponseSmsPayload customSmsResponseChannelSms = CustomSmsResponseSmsPayload.newBuilder()
        .setAlert("Your balance is $1234.56. Go to https://www.example.com/myaccount/my-balance?ua-tag-add=balance_prefs:sms to see more about your account.")
        .setMobileOriginatedId("28883743-4868-4083-ab5d-77ac4542531a")
        .setShortenLinks(true)
        .build();

CustomSmsResponseRequest customSmsResponseRequest = CustomSmsResponseRequest.newRequest(customSmsResponseChannelSms);
Response<CustomSmsResponseResponse> response = client.execute(customSmsResponseRequest);

from urbanairship import (
    BearerTokenClient, SmsCustomResponse,
    sms, mms
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

custom_response = SmsCustomResponse(
    client=client,
    mobile_originated_id="28883743-4868-4083-ab5d-77ac4542531a"
)

custom_response.sms = sms(
    alert="Your balance is $1234.56. Go to https://www.example.com/myaccount/my-balance?ua-tag-add=balance_prefs:sms to see more about your account.",
    shorten_links=True
)

response = custom_response.send()

POST /api/sms/custom-response HTTP/1.1
Authorization: Bearer <bearer token>
X-UA-Appkey: <app key>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "mms" : {
    "fallback_text": "See fun cat pics at https://example.com/cat/pics/12345678",
    "slides": [
      {
        "media": {
          "url": "https://example.com/cat/pics/12345678.gif",
          "content_type": "image/gif",
          "content_length": 23098
        }
      }
    ],
    "shorten_links": true
  },
  "mobile_originated_id" : "3e1e4fb3-2d3c-431e-96bf-9b235a12f84b"
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
      "ok": true,
      "operation_id": "f3d0993e-e3e1-4aae-b1c0-864a715bfaff",
      "push_id": "7502abe6-e6ea-4f2b-906f-ebbab612c69e"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setBearerToken("<token>")
        .build();

MmsSlides mmsSlides = MmsSlides.newBuilder()
        .setText("Test")
        .setMediaUrl("https://example.com/cat/pics/12345678.gif")
        .setMediaContentType("image/gif")
        .setMediaContentLength(23098)
        .build();

CustomSmsResponseMmsPayload customSmsResponseMmsPayload = CustomSmsResponseMmsPayload.newBuilder()
        .setFallbackText("See fun cat pics at https://example.com/cat/pics/12345678")
        .setMobileOriginatedId("28883743-4868-4083-ab5d-77ac4542531a")
        .setSlides(mmsSlides)
        .build();

CustomSmsResponseRequest customSmsResponseRequest = customSmsResponseRequest.newRequest(customSmsResponseMmsPayload);
Response<CustomSmsResponseResponse> response = client.execute(customSmsResponseRequest);

from urbanairship import (
    BearerTokenClient, SmsCustomResponse,
    mms
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

custom_response = SmsCustomResponse(
    client=client,
    mobile_originated_id="3e1e4fb3-2d3c-431e-96bf-9b235a12f84b"
)

custom_response.mms = mms(
    fallback_text="See fun cat pics at https://example.com/cat/pics/12345678",
    slides=[{
        "media": {
            "url": "https://example.com/cat/pics/12345678.gif",
            "content_type": "image/gif",
            "content_length": 23098
        }
    }],
    shorten_links=True
)

response = custom_response.send()

Respond to a mobile-originated message based on a keyword consumed by your custom-response webhook, using a mobile-originated ID. See SMS Keyword Webhooks for information about setting up a custom response webhook server.

Security:

Request headers:

  • X-UA-Appkey stringREQUIRED

Request body:

  • Content-Type: application/json

    One of

    • object

    • object

Responses

  • 200

    The operation was successful.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        If true, your request was successful.

      • operation_id string

        A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.

      • push_id string

        A unique identifier for a push operation.

  • 404

    The mobile_originated_id could not be found.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • error string

        A plain-text explanation of the error.

      • ok boolean

        If false, your request was unsuccessful.

      • operation_id string

        A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.

Manually trigger a keyword interaction

POST /api/sms/{msisdn}/keywords

Example

POST /api/sms/15035556789/keywords HTTP/1.1
User-Agent: Apache-HttpAsyncClient/4.0.1 (java 1.5)
Content-Type: application/json
Authorization: Basic <user:pass>
Connection: close

{
  "keyword" : "stop",
  "sender_ids" : [ "54321", "1234"]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

KeywordInteractionRequest request = KeywordInteractionRequest.newRequest("15035556789")
        .addKeyword("stop")
        .addSenderId("54321")
        .addSenderId("1234");

Response<CustomSmsResponseResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, KeywordInteraction
)
from datetime import datetime

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

interaction = KeywordInteraction(
    client=client,
    keyword="stop",
    sender_ids=["54321", "1234"],
    timestamp=datetime(2021, 10, 8, 12, 0, 0)
)
response = interaction.post()

Failure response (Keyword not configured for Sender ID)

POST /api/sms/15035556789/keywords HTTP/1.1
User-Agent: Apache-HttpAsyncClient/4.0.1 (java 1.5)
Content-Type: application/json
Authorization: Basic <user:pass>
Connection: close

{
  "keyword" : "stop",
  "sender_ids" : [ "54321", "1234"]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

KeywordInteractionRequest request = KeywordInteractionRequest.newRequest("15035556789")
        .addKeyword("stop")
        .addSenderId("54321")
        .addSenderId("1234");

Response<CustomSmsResponseResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, KeywordInteraction
)
from datetime import datetime

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

interaction = KeywordInteraction(
    client=client,
    keyword="stop",
    sender_ids=["54321", "1234"],
    timestamp=datetime(2021, 10, 8, 12, 0, 0)
)
response = interaction.post()

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "ok" : false,
  "error" : "The following sender(s) are not configured for the 'stop' keyword: ['1234']",
  "error_code" : 400
}

Trigger Mobile Originated (MO) keyword interactions on behalf of an MSISDN.

Security:

Request headers:

  • X-UA-Appkey stringREQUIRED

Path parameters:

  • msisdn stringREQUIRED
    The identifier for the SMS channel you want to trigger a mobile originated keyword from.

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • keyword stringREQUIRED

      The keyword you want to trigger an action for. Must be an alphanumeric string with no spaces.

    • sender_ids array[string]REQUIRED

      The sender IDs with keyword actions that you want to test. Airship returns a 400 if the keyword is not configured for one or more of the senders in the array.

    • timestamp string

      The date-time when the MO keyword was sent. If absent, Airship uses the server-time of your request.

Responses

  • 200

    The operation was successful.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        If true, your request was successful.

  • 400

    The operation was not successful. If the request is formatted correctly, one or more sender_ids does not exist or the keyword is not configured for one or more of the sender_ids.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named Users

A Named User is a proprietary identifier that maps customer-chosen IDs, e.g., CRM data, to Channels. It is useful to think of a Named User as an individual consumer who might have more than one mobile device registered with your app. For example, Named User “john_doe_123” might have a personal Android phone and an iPad, on both of which he has opted in for push notifications. If you want to reach John on both devices, associate the Channel (device) identifiers for each device to the Named User “john_doe_123,” and push to the Named User. Notifications will then fan out to each associated device.

Named User listing or lookup

GET /api/named_users

Example Named User lookup

GET /api/named_users/?id=user-456 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok": true,
  "named_user": {
      "named_user_id": "user-456",
      "created" : "2020-04-08T20:41:06",
      "last_modified" : "2020-05-01T18:00:27",
      "tags": {
        "my_fav_tag_group": [
            "tag1",
            "tag2"
        ]
      },
      "subscription_lists": [
        {
          "list_ids": ["example_listId-1", "example_listId-5"],
          "scope": "web"
        },
        {
          "list_ids": ["example_listId-2", "example_listId-3"],
          "scope": "app"
        },
        {
          "list_ids": ["example_listId-2"],
          "scope": "web"
        },
        {
          "list_ids": ["example_listId-3"],
          "scope": "email"
        },
        {
          "list_ids": ["example_listId-4"],
          "scope": "sms"
        }
      ],
      "attributes": {
        "item_purchased": "Fur removal tool",
        "cats_name": "Sammy",
        "pets_age": 12
      },
      "user_attributes": {
        "ua_country": "US",
        "ua_language": "en",
        "ua_tz": "America/Los_Angeles"
      },
      "channels": [
        {
            "channel_id": "dceafd02-b852-4305-83df-98b65fa40dd4",
            "device_type": "ios",
            "installed": true,
            "opt_in": true,
            "push_address": "FFFF",
            "created": "2020-04-08T20:41:06",
            "last_registration": "2020-05-01T18:00:27",
            "tags": [
              "meow"
            ]
        }
      ]
  }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserListingRequest request = NamedUserListingRequest.newRequest("user-456");
Response<NamedUserListingResponse> response = client.execute(request);
NamedUserView namedUser = response.getBody().get().getNamedUserView().get();

// The Named User ID
String namedUserId = namedUser.getNamedUserId();

// Map of tag groups and the associated sets of tags
ImmutableMap<String, ImmutableSet<String>> namedUserTags = namedUser.getNamedUserTags();

// All channel objects associated with the Named User
ImmutableSet<ChannelView> channelViews = namedUser.getChannelViews();

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-456')
response = named_user.lookup()
print(response)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user = UA::NamedUser.new(client: airship)
named_user.named_user_id = 'user-456'
user = named_user.lookup

Example Named User listing

GET /api/named_users/?id=user-456 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok": true,
  "named_user": {
      "named_user_id": "user-456",
      "created" : "2020-04-08T20:41:06",
      "last_modified" : "2020-05-01T18:00:27",
      "tags": {
        "my_fav_tag_group": [
            "tag1",
            "tag2"
        ]
      },
      "subscription_lists": [
        {
          "list_ids": ["example_listId-1", "example_listId-5"],
          "scope": "web"
        },
        {
          "list_ids": ["example_listId-2", "example_listId-3"],
          "scope": "app"
        },
        {
          "list_ids": ["example_listId-2"],
          "scope": "web"
        },
        {
          "list_ids": ["example_listId-3"],
          "scope": "email"
        },
        {
          "list_ids": ["example_listId-4"],
          "scope": "sms"
        }
      ],
      "attributes": {
        "item_purchased": "Fur removal tool",
        "cats_name": "Sammy",
        "pets_age": 12
      },
      "user_attributes": {
        "ua_country": "US",
        "ua_language": "en",
        "ua_tz": "America/Los_Angeles"
      },
      "channels": [
        {
            "channel_id": "dceafd02-b852-4305-83df-98b65fa40dd4",
            "device_type": "ios",
            "installed": true,
            "opt_in": true,
            "push_address": "FFFF",
            "created": "2020-04-08T20:41:06",
            "last_registration": "2020-05-01T18:00:27",
            "tags": [
              "meow"
            ]
        }
      ]
  }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserListingRequest request = NamedUserListingRequest.newRequest("user-456");
Response<NamedUserListingResponse> response = client.execute(request);
NamedUserView namedUser = response.getBody().get().getNamedUserView().get();

// The Named User ID
String namedUserId = namedUser.getNamedUserId();

// Map of tag groups and the associated sets of tags
ImmutableMap<String, ImmutableSet<String>> namedUserTags = namedUser.getNamedUserTags();

// All channel objects associated with the Named User
ImmutableSet<ChannelView> channelViews = namedUser.getChannelViews();

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-456')
response = named_user.lookup()
print(response)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user = UA::NamedUser.new(client: airship)
named_user.named_user_id = 'user-456'
user = named_user.lookup

GET /api/named_users HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Attribute: named_users
Link: <https://go.urbanairship.com/api/named_users?start=user-1234>; rel=next
Content-Type: application/vnd.urbanairship+json; version=3

{
   "next_page": "https://go.urbanairship.com/api/named_users?start=user-1234",
   "named_users": [
      {
         "named_user_id": "user-id-1234",
         "created" : "2020-04-08T20:41:06",
         "last_modified" : "2020-05-01T18:00:27",
         "tags": {
            "my_fav_tag_group": ["tag1", "tag2"]
         },
         "subscription_lists": [
         {
            "list_ids": ["example_listId-1", "example_listId-5"],
            "scope": "web"
         },
         {
            "list_ids": ["example_listId-2", "example_listId-3"],
            "scope": "app"
         },
         {
            "list_ids": ["example_listId-2"],
            "scope": "web"
         },
         {
            "list_ids": ["example_listId-3"],
            "scope": "email"
         }
         ],
         "attributes":{
            "item_purchased":"Fur removal tool",
            "cats_name":"fluffy butt",
            "pets_age":2
         },
         "user_attributes": {
            "ua_country": "US",
            "ua_language": "en",
            "ua_tz": "America/Los_Angeles"
         },
         "channels": [
            {
               "channel_id": "dceafd02-b852-4305-83df-98b65fa40dd5",
               "device_type": "ios",
               "installed": true,
               "opt_in": true,
               "push_address": "FFFF",
               "created": "2020-04-08T20:41:06",
               "last_registration": "2020-05-01T18:00:27",
               "alias": "xxxx",
               "tags": ["asdf"],
               "ios": {
                  "badge": 0,
                  "quiettime": {
                     "start": "22:00",
                     "end": "06:00"
                  },
                  "tz": "America/Los_Angeles"
               }
            }
         ]
      }
   ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserListingRequest request = NamedUserListingRequest.newRequest();
Response<NamedUserListingResponse> response = client.execute(request);
ImmutableList<NamedUserView> namedUsers = response.getBody().get().getNamedUserViews().get();

from urbanairship import (
    BasicAuthClient, NamedUserList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user_list = NamedUserList(airship=client)

for n in named_user_list:
    print(n.named_user_id)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user_list = UA::NamedUserList.new(client: airship)
named_user_list.each do |named_user|
    puts(named_user)
end

Return a list of Named Users or look up a single Named User by named_user_id.

Security:

Query parameters:

  • id string
    The named_user_id you want to look up. When querying a named_user_id, the response contains a single named_user object. If you do not query a specific named_user_id, the response returns an array of named_users, in which each object represents an individual Named User.

Responses

  • 200

    Returns OK for success.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      One of

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named Users association

POST /api/named_users/associate

Example associate an iOS channel with a Named User

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

{
   "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
   "device_type": "ios",
   "named_user_id": "user-id-1234"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserRequest request = NamedUserRequest.newAssociationRequest()
        .setChannel("df6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.IOS)
        .setNamedUserId("user-id-1234");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.associate(channel_id='df6a6b50-9843-0304-d5a5-743f246a4946', device_type='ios')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user = UA::NamedUser.new(client: airship)
named_user.named_user_id = 'user-id-1234'
named_user.associate(channel_id: 'df6a6b50-9843-0304-d5a5-743f246a4946', device_type: 'ios')

Example associate a web channel with Named User (do not declare device type)

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

{
   "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
   "device_type": "ios",
   "named_user_id": "user-id-1234"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserRequest request = NamedUserRequest.newAssociationRequest()
        .setChannel("df6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.IOS)
        .setNamedUserId("user-id-1234");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.associate(channel_id='df6a6b50-9843-0304-d5a5-743f246a4946', device_type='ios')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user = UA::NamedUser.new(client: airship)
named_user.named_user_id = 'user-id-1234'
named_user.associate(channel_id: 'df6a6b50-9843-0304-d5a5-743f246a4946', device_type: 'ios')

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

{
   "channel_id": "wf6a6b50-9843-0304-d5a5-743f246a4946",
   "named_user_id": "user-id-1234"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserRequest request = NamedUserRequest.newAssociationRequest()
        .setChannel("wf6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.WEB)
        .setNamedUserId("user-id-1234");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.associate(channel_id='wf6a6b50-9843-0304-d5a5-743f246a4946')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user = UA::NamedUser.new(client: airship)
named_user.named_user_id = 'user-id-1234'
named_user.associate(channel_id: 'wf6a6b50-9843-0304-d5a5-743f246a4946')

Example associate an email channel with Named User

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

{
   "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
   "device_type": "ios",
   "named_user_id": "user-id-1234"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserRequest request = NamedUserRequest.newAssociationRequest()
        .setChannel("df6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.IOS)
        .setNamedUserId("user-id-1234");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.associate(channel_id='df6a6b50-9843-0304-d5a5-743f246a4946', device_type='ios')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user = UA::NamedUser.new(client: airship)
named_user.named_user_id = 'user-id-1234'
named_user.associate(channel_id: 'df6a6b50-9843-0304-d5a5-743f246a4946', device_type: 'ios')

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

{
   "channel_id": "wf6a6b50-9843-0304-d5a5-743f246a4946",
   "named_user_id": "user-id-1234"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserRequest request = NamedUserRequest.newAssociationRequest()
        .setChannel("wf6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.WEB)
        .setNamedUserId("user-id-1234");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.associate(channel_id='wf6a6b50-9843-0304-d5a5-743f246a4946')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user = UA::NamedUser.new(client: airship)
named_user.named_user_id = 'user-id-1234'
named_user.associate(channel_id: 'wf6a6b50-9843-0304-d5a5-743f246a4946')

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

{
   "email_address": "monopoly.man@example.com",
   "named_user_id": "user-id-1234"
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserRequest request = NamedUserRequest.newAssociationRequest()
        .setChannel("em6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.EMAIL)
        .setNamedUserId("user-id-1234");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.email_associate(email_address='monopoly.man@example.com')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user = UA::NamedUser.new(client: airship)
named_user.named_user_id = 'user-id-1234'
named_user.associate(channel_id: 'em6a6b50-9843-0304-d5a5-743f246a4946')

Associate a channel or email address with a Named User (named_user_id). If the named_user_id does not already exist, this operation will create it. If the channel_id or email address is already associated with the named_user_id, this operation will do nothing.

 Warning

If a channel has an assigned Named User and you make an additional call to associate that same channel with a new Named User, the original Named User association will be removed and the new Named User and associated data will take its place. Additionally, all tags associated to the original Named User cannot be used to address this channel unless they are also associated with the new Named User.

Security:

Request body:

Named User association requires a channel_id or email_address. Do not provide both in the same request. You can associate up to 100 Channel IDs to a Named User.

  • Content-Type: application/json

    One of
    • Named User association payload with Channel ID object
      OBJECT PROPERTIES
      • channel_id stringREQUIRED

        The Channel ID you want to associate with a Named User.

      • device_type string

        The device type of the channel.

        Possible values: ios, android, amazon, web, open, email, sms

      • named_user_id stringREQUIRED

        A string value identifying the user with no leading or trailing whitespace. If the named_user_id does not already exist, this operation will create a new Named User.

    • Named User association payload with email address object
      OBJECT PROPERTIES
      • email_address stringREQUIRED

        The email address you want to associate with a Named User.

      • named_user_id stringREQUIRED

        The existing Named User ID

Responses

  • 200

    The request was accepted but is not guaranteed to be successfully processed. If the Named User has more than 1,000 channels associated with it, the request will be ignored.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named Users disassociation

POST /api/named_users/disassociate

Example

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

{
   "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
   "device_type": "ios",
   "named_user_id": "user-id-1234"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserRequest request = NamedUserRequest.newDisassociationRequest()
        .setChannel("df6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.IOS);

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.disassociate(channel_id='df6a6b50-9843-0304-d5a5-743f246a4946', device_type='ios')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user = UA::NamedUser.new(client: airship)
named_user.disassociate(channel_id: 'df6a6b50-9843-0304-d5a5-743f246a4946', device_type: 'ios')

Example disassociate an email channel from Named User

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

{
   "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
   "device_type": "ios",
   "named_user_id": "user-id-1234"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserRequest request = NamedUserRequest.newDisassociationRequest()
        .setChannel("df6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.IOS);

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.disassociate(channel_id='df6a6b50-9843-0304-d5a5-743f246a4946', device_type='ios')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user = UA::NamedUser.new(client: airship)
named_user.disassociate(channel_id: 'df6a6b50-9843-0304-d5a5-743f246a4946', device_type: 'ios')

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

{
   "email_address": "monopoly.man@example.com",
   "named_user_id": "user-id-1234"
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserRequest request = NamedUserRequest.newDisassociationRequest()
        .setChannel("em6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.EMAIL)
        .setNamedUserId("user-id-1234");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.email_disassociate(email_address='monopoly.man@example.com')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user = UA::NamedUser.new(client: airship)
named_user.disassociate(channel_id: 'em6a6b50-9843-0304-d5a5-743f246a4946')

Disassociate a channel or an email address from a named_user_id.

Security:

Request body:

  • Content-Type: application/json

    One of
    • Named User disassociation payload with Channel ID object
      OBJECT PROPERTIES
      • channel_id stringREQUIRED

        The Channel ID you want to disassociate from a Named User.

      • device_type string

        The device type of the channel.

        Possible values: ios, android, amazon, web, email, sms, open

      • named_user_id string

        The existing Named User ID.

    • Named User disassociation payload with email address object
      OBJECT PROPERTIES
      • email_address stringREQUIRED

        The email address you want to disassociate from a Named User.

      • named_user_id string

        A string value identifying the new user with no leading or trailing whitespace. If the named_user_id does not already exist, this operation will create a new Named User and associate the channel_id with it.

Responses

  • 200

    The request was accepted but is not guaranteed to be successfully processed.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Scoped Named User batch operations

POST /api/named_users/scoped/{named_user_id}

Example scoped Named User batch operations

POST /api/named_users/scoped/b8f9b663-0a3b-cf45-587a-be880946e881 HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "scoped": [
      {
          "scope": ["app"],
          "subscription_lists": {
              "subscribe": ["stickers", "gifs"],
              "unsubscribe": ["cookies"]
          }
      },
      {
          "scope": ["web"],
          "subscription_lists": {
              "subscribe": ["daily_snacks", "brunch"],
              "unsubscribe": ["promotions"]
          }
      }
   ]
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Set<NamedUserScopeType> scopeTypes1 = new HashSet<>(Arrays.asList(NamedUserScopeType.APP));
Set<String> subscribeLists1 = new HashSet<>(Arrays.asList("stickers", "gifs"));
Set<String> unsubscribeLists1 = new HashSet<>(Arrays.asList("cookies"));

Set<NamedUserScopeType> scopeTypes2 = new HashSet<>(Arrays.asList(NamedUserScopeType.WEB));
Set<String> subscribeLists2 = new HashSet<>(Arrays.asList("daily_snacks", "brunch"));
Set<String> unsubscribeLists2 = new HashSet<>(Arrays.asList("promotions"));

NamedUserScope namedUserScope1 = NamedUserScope.newBuilder()
        .setScopes(scopeTypes1)
        .setSubscribeLists(subscribeLists1)
        .setUnsubscribeLists(unsubscribeLists1)
        .build();

NamedUserScope namedUserScope2 = NamedUserScope.newBuilder()
        .setScopes(scopeTypes2)
        .setSubscribeLists(subscribeLists2)
        .setUnsubscribeLists(unsubscribeLists2)
        .build();

NamedUserScopedPayload namedUserScopedPayload = NamedUserScopedPayload.newBuilder()
        .addNamedUserScope(namedUserScope1)
        .addNamedUserScope(namedUserScope2)
        .build();

NamedUserScopedRequest request = NamedUserScopedRequest.newRequest("named_user_id", namedUserScopedPayload);
Response<GenericResponse> response = client.execute(request);

Supports multiple operations on a Named User within a single request for a specified scope. The supported operation is subscription_lists. The behavior of each of these operations are the same as their individual request counterpart.

 Note

If you are using a single-channel Preference Center created before October 10, 2022, that has not been migrated to user-level, use the /api/channels/subscription_lists endpoint to add or remove individual channels to/from your subscription list.

Security:

Path parameters:

  • named_user_id stringREQUIRED
    A string value identifying the user with no leading or trailing whitespace. If this value contains reserved or special characters they must be URL encoded.

Request body:

  • Content-Type: application/json

    Type: object

Responses

  • 200

    The scoped Named User batch operations succeeded.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named Users tags

POST /api/named_users/tags

Example

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

{
  "audience": {
      "named_user_id": [
        "user-1",
        "user-2",
        "user-3"
      ]
  },
  "add": {
      "crm": [
        "tag1",
        "tag2",
        "tag3"
      ],
      "loyalty": [
        "tag1",
        "tag4",
        "tag5"
      ]
  },
  "remove": {
      "loyalty": [
        "tag6",
        "tag7"
      ]
  }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserTagRequest request = NamedUserTagRequest.newRequest()
        .addNamedUsers("user-1", "user-2", "user-3")
        .addTags("crm", ImmutableSet.of("tag1", "tag2", "tag3"))
        .addTags("loyalty", ImmutableSet.of("tag1", "tag4", "tag5"))
        .removeTags("loyalty", ImmutableSet.of("tag6", "tag7"));

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-1')

resp1 = named_user.tag(
    group='loyalty',
    add=['tag2', 'tag3', 'tag4'],
    remove='tag1'
)

resp2 = named_user.tag(
    group='crm',
    set=['tag5', 'tag6']
)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user_tags = UA::NamedUserTags.new(client: airship)
named_user_ids = ['user-1', 'user-2', 'user-3']
named_user_tags.set_audience(user_ids: named_user_ids)
named_user_tags.add(group_name: 'crm', tags: ['tag1', 'tag2', 'tag3'])
named_user_tags.remove(group_name: 'loyalty', tags: ['tag6', 'tag7'])
named_user_tags.send_request

Add, remove, or set tags on a Named User. A single request body may contain add and/or remove objects or a single set field. At least one of the add, remove, or set objects must be present in a request.

Security:

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • add object<Tag Group object>

      Add the list of tags to the Named User(s), but do not remove any. If the tags are already present, they are not modified.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • audience objectREQUIRED

      The Named User(s) you want to associate/disassociate tags with.

      OBJECT PROPERTIES
      • named_user_id array[string]
    • remove object<Tag Group object>

      Remove the list of tags from the Named User(s), but do not remove any others. If the tags are not currently present, nothing happens.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • set object<Tag Group object>

      Set these tags for the audience; any tags previously associated with the audience tags that are not in this current list are removed.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 200

    If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 will be returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.

    Response body:

    • Content-Type: application/json

      Body may contain warnings about portions of the request which were not processed.

      OBJECT PROPERTIES
      • ok booleanREQUIRED

        Set to true when status code is 200.

      • tag_warnings string

        Warnings encountered when processing tags for this Named User.

  • 400

    Parsing or validating the request failed. You will see this error if the same tag is present in both the add and remove fields.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named Users uninstall

POST /api/named_users/uninstall

Example delete all users and their associated channels

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

{
   "named_user_id": ["user-id-1234","user-id-5678"]
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserUninstallRequest namedUserUninstallRequest = NamedUserUninstallRequest
        .newUninstallRequest(ImmutableList.of("user-id-1234","user-id-5678"));

Response<GenericResponse> response = client.execute(namedUserUninstallRequest);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

response = NamedUser.uninstall(
    client=client,
    named_users=["user-id-1234", "user-id-5678"]
  )

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user_uninstall = UA::NamedUserUninstaller.new(client: airship)
named_user_uninstall.named_user_ids = ['user-id-1234']
named_user_uninstall.uninstall

Disassociate and delete all channels associated with the named_user_id(s) and also delete the named_user_id(s). This call removes all channels associated with a Named User from Airship systems in compliance with data privacy laws.

Uninstalling channels also removes accompanying analytic data (including Performance Analytics) from the system.

See Individual Data Privacy Rights Under Data Privacy Laws for more information about data privacy law compliance.

 Note

Channel uninstallation, like channel creation, is an asynchronous operation and may take some time to complete.

Security:

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • named_user_id array[string]REQUIRED

      Array of strings representing the named_user_id(s) you wish to be uninstalled. Must have between 1 to 100 items in the array with a 128 character/byte maximum per item.

Responses

  • 200

    All channels have been deleted and disassociated from the Named User.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named User update

POST /api/named_users/{named_user_id}

Create a Named User by associating an email and SMS channel and setting tags and attributes.

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

{
  "associate": [
      {
        "email_address": "john@example.com"
      },
      {
        "channel_id": "f5346fa3-99f1-496d-be37-2895ef58f5a5",
        "device_type": "sms"
      }
  ],
  "tags": {
      "set": {
          "subscription_status": ["gold"],
          "favorites" : ["sports", "stocks"]
      }
  },
  "attributes": [
    {
      "action": "set",
      "key": "name",
      "value": "John"
    }
  ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserUpdateChannel namedUserUpdateChannel = NamedUserUpdateChannel.newBuilder()
        .addChannel(NamedUserUpdateDeviceType.ANDROID_CHANNEL, "aa2ae18c-f4b0-48ac-a859-55f26d2a7439")
        .build();

Attribute lastName = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("pseudo")
        .setValue("Pataki")
        .build();

NamedUserUpdatePayload namedUserUpdatePayload = NamedUserUpdatePayload.newBuilder()
        .addAttribute(lastName)
        .addTags("go", List.of("test1","test2"))
        .removeTags("go",List.of("test3","test4"))
        .addNamedUserUpdateChannel(namedUserUpdateChannel)
        .setAction(NamedUserUpdateChannelAction.ASSOCIATE)
        .build();

NamedUserUpdateRequest request = NamedUserUpdateRequest.newRequest("john", namedUserUpdatePayload);
Response<NamedUserUpdateResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

associate = [
  {"email_address": "john@example.com"},
  {"channel_id": "f5346fa3-99f1-496d-be37-2895ef58f5a5", "device_type": "sms"}
]
tags = {
  "set": {
      "subscription_status": ["gold"],
      "favorites" : ["sports", "stocks"]
      }
}
attributes = [
    {
      "action": "set",
      "key": "name",
      "value": "John"
    }
  ]

named_user = NamedUser(
  airship=client,
  named_user_id="john_doe"
)

response = named_user.update(
  associate=associate,
  tags=tags,
  attributes=attributes
)

Create or update a Named User by associating/disassociating channels and adding/removing tags and attributes in a single request.

 Warning

If a channel has an assigned Named User and you make an additional call to associate that same channel with a new Named User, the original Named User association will be removed and the new Named User and associated data will take its place. Additionally, all tags associated to the original Named User cannot be used to address this channel unless they are also associated with the new Named User.

Security:

Path parameters:

  • named_user_id stringREQUIRED
    A string value identifying the user with no leading or trailing whitespace. If this value contains reserved or special characters they must be URL encoded.

Request body:

  • Content-Type: application/json

    Named User update payload

    At least one of associate, disassociate, tags, or attributes must be provided. If a channel is provided in both associate and disassociate sections, a 400 will be returned.

Responses

  • 200

    Request was accepted.

    Response body:

    • Content-Type: application/json

      Body may contain warnings about portions of the request which were not processed.

      OBJECT PROPERTIES
      • attribute_warnings string

        Warnings encountered when processing attributes for this Named User.

      • ok booleanREQUIRED

        Set to true when status code is 200.

      • tag_warnings string

        Warnings encountered when processing tags for this Named User.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Set or remove attributes on Named Users

POST /api/named_users/{named_user_id}/attributes

Example

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

{
    "attributes": [
        {
            "action": "set",
            "key": "firstName",
            "value": "Gyuri",
            "timestamp": "2020-09-19 12:00:00"
        },
        {
            "action": "remove",
            "key": "birthDate",
            "timestamp": "2020-09-19 12:00:00"
        },
        {
            "action": "set",
            "key": "lastName",
            "value": "Pataki",
            "timestamp": "2020-09-19 12:00:00"
        }
    ]
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Attribute firstName = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("firstName")
        .setValue("Gyuri")
        .setTimeStamp(DateTime.parse("2020-09-19T12:00:00Z"))
        .build();

Attribute birthDate = Attribute.newBuilder()
        .setAction(AttributeAction.REMOVE)
        .setKey("birthDate")
        .setTimeStamp(DateTime.parse("2020-09-19T12:00:00Z"))
        .build();

Attribute lastName = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("lastName")
        .setValue("Pataki")
        .setTimeStamp(DateTime.parse("2020-09-19T12:00:00Z"))
        .build();

NamedUserAttributePayload payload = NamedUserAttributePayload.newBuilder()
        .addAttribute(firstName)
        .addAttribute(birthDate)
        .addAttribute(lastName)
        .build();

NamedUserAttributeRequest request = NamedUserAttributeRequest.newRequest("my_named_user", payload);
Response<NamedUserAttributeResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Attribute, ModifyAttributes
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

set_major_league = Attribute(
                      action="set",
                      key="major_league",
                      value="sf_giants")

remove_minor_league = Attribute(
                         action="remove",
                         key="minor_league")

set_position = Attribute(
                  action="set",
                  key="position",
                  value="LF")

modifications = ModifyAttributes(
                   airship=client,
                   attributes=[set_major_league,
                               remove_minor_league,
                               set_position],
                   named_user="my_named_user"
                )

modifications.send()

Set or remove attributes on a Named User.

A single request body may contain a set or remove field, or both, or a single set field. If both set and remove fields are present and the intersection of the attributes in these fields is not empty, then a 400 will be returned.

If an attribute request is partially valid, i.e., at least one attribute exists, Airship returns a 200 with a warning about the attributes that failed to update. The attributes listed in the warnings string will be in CSV format.

 Note

Airship returns a 200 with a warning if you attempt to set attributes on a Named User that does not exist.

Security:

Path parameters:

  • named_user_id stringREQUIRED
    The Named User you are setting the attributes for.

Request body:

  • Content-Type: application/json

    array<Attributes Object>

    Include an array of attributes objects in your request.

Responses

  • 200

    Success. If an attribute request is partially valid, i.e., at least one attribute exists, Airship returns a 200 with a warning string containing a CSV list of attributes that failed to update. Airship also returns a 200 with a warning if you attempt to set attributes on a named_user, even if the named_user does not exist.

    Response body:

    • Content-Type: application/json

      Body may contain warnings about portions of the request which were not processed.

      OBJECT PROPERTIES
      • ok boolean

        Set to true when status code is 200.

      • warnings string

        Warnings encountered when updating Named User attributes.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Tags

Operations to assign or unassign tags for Channels and Named Users. Tags belong to Tag Groups and can help you organize channels using identifiers relevant to your operations. See the linked for information about, and strategies for using, tag groups.

Email tags

POST /api/channels/email/tags

Example

POST /api/channels/email/tags HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
      "email_address": "name@example.com"
   },
   "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

EmailTagRequest request = EmailTagRequest.newRequest();
emailTagRequest.addEmailChannel("name@example.com")
        .addTags("my_fav_tag_group1", ImmutableSet.of("tag1", "tag2", "tag3"))
        .addTags("my_fav_tag_group2", ImmutableSet.of("tag1", "tag2", "tag3"))
        .addTags("my_fav_tag_group3", ImmutableSet.of("tag1", "tag2", "tag3"));

Response<EmailChannelResponse> response = client.execute(request);

from urbanairship import (
    BearerTokenClient, EmailTags
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

# replaces all existing tags on an email channel
email_tags = EmailTags(airship=client,
                          address='name@example.com')
email_tags.set(group='my_tag_group',
              tags=['one', 'two', 'three'])
email_tags.send()

# adds and removes tags from an email channel
email_tags = EmailTags(airship=client,
                          address='name@example.com')
email_tags.remove(group='my_tag_group',
                  tags=['one', 'two', 'three'])
email_tags.add(group='my_tag_group',
              tags=['some', 'new', 'tags'])
email_tags.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_tags = UA::EmailTags.new(client: airship)
#set an audience
email_tags.set_audience(email_address: 'name@example.com')
#add a tag
email_tags.add(group_name: 'my_fav_tag_group1', tags: 'tag2')
#remove a tag
email_tags.remove(group_name: 'my_fav_tag_group1', tags: 'tag1')
email_tags.send_request

Add, remove, or set tags for a single email channel.

Security:

Request body:

A single request body can contain an add and/or remove field or a single set field. One or more of the add, remove, or set keys must be present in the request.

  • Content-Type: application/json

    OBJECT PROPERTIES
    • add object<Tag Group object>

      Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • audience objectREQUIRED

      Specifies the email address you want to perform tag operations against. Must contain a single email_address key.

      OBJECT PROPERTIES
      • email_address stringREQUIRED

        The email address you want to modify tags for. Accepts a single string value representing an email address.

    • remove object<Tag Group object>

      Removes the specified tags from the channel.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • set object<Tag Group object>

      Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 200

    Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 will be returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Open channel tags

POST /api/channels/open/tags

Example

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

 {
  "audience": {
      "address": "Number Four",
      "open_platform_name": "cylon"
  },
  "add": {
    "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
    "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
    "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
  }
 }

HTTP/1.1 200 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok":true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

OpenChannelTagRequest openChannelTagRequest =  OpenChannelTagRequest.newRequest()
        .addOpenChannel("Number Four","cyclon")
        .addTags("CRM_Delux", Set.of("tag1","tag2"))
        .removeTags("CRM_Delux",  Set.of("tag3","tag4"));
Response<GenericResponse> response = client.execute(openChannelTagRequest);

from urbanairship import (
    BasicAuthClient, OpenChannel
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
channel = OpenChannel(airship=client)
channel.address = 'Number Four'
channel.open_platform = 'cylon'
channel.tags = ['tag1', 'tag2', 'tag3']
response = channel.update()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

open_channel = UA::OpenChannel.new(client: airship)
open_channel.opt_in = true
open_channel.address = 'Number Four'
open_channel.open_platform = 'cylon'
open_channel.channel_id = 'df6a6b50-9843-0304-d5a5-743f246a4946'
open_channel.tags = ['tag1', 'tag2', 'tag3']
open_channel.update(set_tags: true)

Manipulate a single open channel’s tags. Open channels are identified by address, not by their channel_id.

Security:

Request body:

  • Content-Type: application/json

    Add, remove, or set tags on a channel. A single request body may contain add and/or remove objects or a single set field. At least one of the add, remove, or set objects must be present in a request.

    OBJECT PROPERTIES
    • add object<Tag Group object>

      Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • audience objectREQUIRED

      The request body containing an address and open_platform_name.

      OBJECT PROPERTIES
      • address stringREQUIRED

        Where notifications sent to this channel_id will be sent. Examples: email address, phone number. If missing, channel_id must be present. The address is one-to-one with the channel_id. New addresses on existing channels will overwrite old associations.

      • open_platform_name stringREQUIRED

        An alphanumeric string that must be the name of a pre-created open platform object.

    • remove object<Tag Group object>

      Removes the specified tags from the channel.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • set object<Tag Group object>

      Assigns a list of tags exactly. Any previously set tags that are not in this current list will be removed.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 200

    Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 is returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

SMS tags

POST /api/channels/sms/tags

Example

POST /api/channels/sms/tags HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
    "sender": "12345",
    "msisdn": "15035556789"
   },
   "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
   }
}

Add, remove, or set tags for a single SMS channel.

Security:

Request body:

A single request body can contain an add and/or remove field or a single set field. One or more of the add, remove, or set keys must be present in the request.

  • Content-Type: application/json

    OBJECT PROPERTIES
    • add object<Tag Group object>

      Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • audience objectREQUIRED

      Specifies the MSISDN and sender you want to perform tag operations against.

      OBJECT PROPERTIES
      • msisdn string

        The mobile phone number corresponding to the SMS channel. Must be numeric characters only, without leading zeros. 15 digits maximum.

      • sender string

        A long or short code the app is configured to send from. For example, 12345.

    • remove object<Tag Group object>

      Removes the specified tags from the channel.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • set object<Tag Group object>

      Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 200

    Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 will be returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Channel tags

POST /api/channels/tags

Example

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

{
   "audience": {
      "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881",
      "android_channel": "13863b3c-f860-4bbf-a9f1-4d785379b8a2"
   },
   "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
   }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "warnings": ["The following tag groups do not exist: my_fav_tag_group2", "The following tag groups are deactivated: my_fav_tag_group3"]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ChannelTagRequest request = ChannelTagRequest.newRequest()
        .addIOSChannel("b8f9b663-0a3b-cf45-587a-be880946e881")
        .addAndroidChannel("13863b3c-f860-4bbf-a9f1-4d785379b8a2")
        .addTags("my_fav_tag_group1", ImmutableSet.of("tag1", "tag2", "tag3"))
        .addTags("my_fav_tag_group2", ImmutableSet.of("tag1", "tag2", "tag3"))
        .addTags("my_fav_tag_group3", ImmutableSet.of("tag1", "tag2", "tag3"));

Response<GenericResponse> response = client.execute(request);

import urbanairship as ua

client = ua.BasicAuthClient('<app key>', '<master secret>')
channel_tags = ua.devices.ChannelTags(client)
ios_audience = ['b8f9b663-0a3b-cf45-587a-be880946e881']
android_audience = ['13863b3c-f860-4bbf-a9f1-4d785379b8a2']
channel_tags.set_audience(ios_audience, android_audience
)
channel_tags.add('my_fav_tag_group1', ['tag1', 'tag2', 'tag3'])
channel_tags.remove('my_fav_tag_group2', 'tag4')
channel_tags.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

channel_tags = UA::ChannelTags.new(client: airship)
ios_audience = 'b8f9b663-0a3b-cf45-587a-be880946e881'
android_audience = '13863b3c-f860-4bbf-a9f1-4d785379b8a2'
channel_tags.set_audience(
    ios: ios_audience,
    android: android_audience
)
channel_tags.add(group_name: 'my_fav_tag_group1', tags: ['tag1', 'tag2', 'tag3'])
channel_tags.remove(group_name: 'my_fav_tag_group2', tags: 'tag4')
channel_tags.send_request

Add, remove, or set tags on a channel.

Security:

Request body:

  • Content-Type: application/json

    A single request body may contain add and/or remove objects or a single set object. At least one of the add, remove, or set objects must be present in a request.

    OBJECT PROPERTIES
    • add object<Tag Group object>

      Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • audience objectREQUIRED

      Specifies one or more channels that you want to apply tag operations to.

      OBJECT PROPERTIES
      • amazon_channel array[string]

        The unique channel identifier for a Fire OS device.

      • android_channel array[string]

        The unique channel identifier for an Android device.

      • channel array[string]

        The unique channel identifier for email, sms, open, or web device types.

      • ios_channel array[string]

        The unique channel identifier for an iOS device.

    • remove object<Tag Group object>

      Removes the specified tags from the channel.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • set object<Tag Group object>

      Assigns a list of tags exactly. Any previously set tags that are not in this current list will be removed.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 200

    Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 is returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        If true, your request was processed normally.

      • warnings array[string]

        Returned when some tag groups could not be updated. Contains a string indicating each tag group that could not be updated and the reason the update failed.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named Users tags

POST /api/named_users/tags

Example

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

{
  "audience": {
      "named_user_id": [
        "user-1",
        "user-2",
        "user-3"
      ]
  },
  "add": {
      "crm": [
        "tag1",
        "tag2",
        "tag3"
      ],
      "loyalty": [
        "tag1",
        "tag4",
        "tag5"
      ]
  },
  "remove": {
      "loyalty": [
        "tag6",
        "tag7"
      ]
  }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserTagRequest request = NamedUserTagRequest.newRequest()
        .addNamedUsers("user-1", "user-2", "user-3")
        .addTags("crm", ImmutableSet.of("tag1", "tag2", "tag3"))
        .addTags("loyalty", ImmutableSet.of("tag1", "tag4", "tag5"))
        .removeTags("loyalty", ImmutableSet.of("tag6", "tag7"));

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-1')

resp1 = named_user.tag(
    group='loyalty',
    add=['tag2', 'tag3', 'tag4'],
    remove='tag1'
)

resp2 = named_user.tag(
    group='crm',
    set=['tag5', 'tag6']
)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user_tags = UA::NamedUserTags.new(client: airship)
named_user_ids = ['user-1', 'user-2', 'user-3']
named_user_tags.set_audience(user_ids: named_user_ids)
named_user_tags.add(group_name: 'crm', tags: ['tag1', 'tag2', 'tag3'])
named_user_tags.remove(group_name: 'loyalty', tags: ['tag6', 'tag7'])
named_user_tags.send_request

Add, remove, or set tags on a Named User. A single request body may contain add and/or remove objects or a single set field. At least one of the add, remove, or set objects must be present in a request.

Security:

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • add object<Tag Group object>

      Add the list of tags to the Named User(s), but do not remove any. If the tags are already present, they are not modified.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • audience objectREQUIRED

      The Named User(s) you want to associate/disassociate tags with.

      OBJECT PROPERTIES
      • named_user_id array[string]
    • remove object<Tag Group object>

      Remove the list of tags from the Named User(s), but do not remove any others. If the tags are not currently present, nothing happens.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • set object<Tag Group object>

      Set these tags for the audience; any tags previously associated with the audience tags that are not in this current list are removed.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 200

    If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 will be returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.

    Response body:

    • Content-Type: application/json

      Body may contain warnings about portions of the request which were not processed.

      OBJECT PROPERTIES
      • ok booleanREQUIRED

        Set to true when status code is 200.

      • tag_warnings string

        Warnings encountered when processing tags for this Named User.

  • 400

    Parsing or validating the request failed. You will see this error if the same tag is present in both the add and remove fields.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Segments

Segments are portions of your audience that have arbitrary metadata (e.g., tags, location data, etc.) attached. You can create, delete, update, or request information on a Segment via the /api/segments/ endpoint. Pushing to a Segment is done through the /api/push/ endpoint. See the Audience selection section for more information.

Segment listing

GET /api/segments

Example

GET /api/segments/ HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Link: <https://go.urbanairship.com/api/segments?limit=1&sort=id&order=asc&start=3832cf72-cb44-4132-a11f-eafb41b82f64>;rel=next
Content-Type: application/vnd.urbanairship+json; version=3

{
   "next_page": "https://go.urbanairship.com/api/segments?limit=1&sort=id&order=asc&start=3832cf72-cb44-4132-a11f-eafb41b82f64",
   "segments": [
      {
         "creation_date": 1346248822221,
         "display_name": "A segment",
         "id": "00c0d899-a595-4c66-9071-bc59374bbe6b",
         "modification_date": 1346248822221
      }
   ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SegmentListingRequest request = SegmentListingRequest.newRequest();
Response<SegmentListingResponse> response = client.execute(request);

// Get the first segment in the list
SegmentListingView segment = response.getBody().get().getSegmentListingViews().get(0);

// Get the segment display name
String displayName = segment.getDisplayName();

// Get the segment ID
String id = segment.getSegmentId();

from urbanairship import (
    BasicAuthClient, SegmentList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# List all segments
segment_list = SegmentList(client)
for segment in segment_list:
    print(segment.display_name)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

segment_list = UA::SegmentList.new(client: airship)

segment_list.each do |segment|
   puts(segment['display_name'])
end

List all segments for the application.

Security:

Query parameters:

  • limit integer
    Set the limit to 200 or fewer Segment objects per request.

    Max: 200

Responses

  • 200

    Returned on success a JSON object containing segments.

    Response headers:

    • Link string

      A link to the next page of results. If present, follow this URL to the next page of segments. Also available in the next_page value in the response body.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • next_page string

        An optional relative URL which can be used to retrieve the next page of results. If no more results are available, next_page will be absent.

      • segments array[object]REQUIRED

        An array of segments for the application.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create Segment

POST /api/segments

Example

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

{
   "display_name": "News but not sports",
   "criteria": {
      "and": [
         {"tag": "news"},
         {"not":
            {"tag": "sports"}
         }
      ]
   }
}

HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/segments/f35da41d-59c1-4106-a192-9594bd480cb6
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "segment_id": "f35da41d-59c1-4106-a192-9594bd480cb6",
   "operation_id": "1d154121-951f-45b9-896d-e70718b5865b"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

// Define the segment criteria
Selector compound = Selectors.and(Selectors.tag("news"), Selectors.not(Selectors.tag("sports")));

SegmentRequest request = SegmentRequest.newRequest();
request.setCriteria(compound);
request.setDisplayName("News but not sports");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Segment,
    tag, not_, and_
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Create a new segment
segment = Segment()
segment.display_name = "News but not sports"
segment.criteria = and_(
    tag('news'),
    not_(tag('sports'))
)

# Create the segment
response = segment.create(client)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

segment = UA::Segment.new(client: airship)
segment.display_name = 'Display Name'
segment.criteria = { 'tag' => 'existing_tag' }
segment.create

Create a new Segment.

Security:

Request body:

A single Segment object.

  • Content-Type: application/json

    Segment object

    A set of audience selection criteria that you can reuse as a segment.

    OBJECT PROPERTIES
    • criteria objectREQUIRED

      Defines the set of devices to send notifications to. criteria is a JSON expression containing the same information as the audience selector, including Event Segmentation. See Audience selection for more information.

      One of
      • Compound Selector

        Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

      • Atomic Selector

        Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.

    • display_name stringREQUIRED

      Human readable name for this Segment. This will be used in the dashboard.

Responses

  • 201

    The Segment was created.

    Response headers:

    • Location string

      The newly created Segment.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        If true, the operation completed successfully and returns expected results.

      • operation_id string

        A unique string identifying an API call, and can be used to identify operations in reporting and troubleshooting logs.

      • segment_id string

        The ID of the newly created Segment.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Segment lookup

GET /api/segments/{segment_id}

Example

GET /api/segments/00c0d899-a595-4c66-9071-bc59374bbe6b HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "criteria": {
      "and": [
         {
            "tag": "ipad"
         },
         {
            "not": {
               "tag": "foo"
            }
         }
      ]
   },
   "display_name": "A segment"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SegmentLookupRequest request = SegmentLookupRequest.newRequest("00c0d899-a595-4c66-9071-bc59374bbe6b");
Response<SegmentView> response = client.execute(request);

// Get the segment criteria
Selector criteria = response.getBody().get().getCriteria();

// Get the segment display name
String displayName = response.getBody().get().getDisplayName();

from urbanairship import (
    BasicAuthClient, Segment
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Look up a segment by ID
segment = Segment()
response = segment.from_id(client, "00c0d899-a595-4c66-9071-bc59374bbe6b")

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

segment = UA::Segment.new(client: airship)
details = segment.from_id(id: '00c0d899-a595-4c66-9071-bc59374bbe6b')

Lookup a Segment.

Security:

Path parameters:

  • segment_id stringREQUIRED
    The Segment you want to retrieve.

Responses

  • 200

    Returns OK for success.

    Response body:

    • Content-Type: application/json

      A set of audience selection criteria that you can reuse as a segment.

      OBJECT PROPERTIES
      • criteria objectREQUIRED

        Defines the set of devices to send notifications to. criteria is a JSON expression containing the same information as the audience selector, including Event Segmentation. See Audience selection for more information.

        One of
        • Compound Selector

          Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

        • Atomic Selector

          Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.

      • display_name stringREQUIRED

        Human readable name for this Segment. This will be used in the dashboard.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update Segment

PUT /api/segments/{segment_id}

Example

PUT /api/segments/00c0d899-a595-4c66-9071-bc59374bbe6b HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "display_name": "Entertainment but not sports",
   "criteria": {
      "and": [
         {"tag": "entertainment"},
         {"not":
            {"tag": "sports"}
         }
      ]
   }
}

HTTP/1.1 200 OK
Content-Length: 65
Content-Type: application/vnd.urbanairship+json;version=3

{
   "ok": true,
   "operation_id": "1f93ca85-b8fd-4833-8d1a-6e2b7f4ceea9"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

// Define the segment criteria
Selector compound = Selectors.and(Selectors.tag("entertainment"), Selectors.not(Selectors.tag("sports")));

SegmentRequest request = SegmentRequest.newUpdateRequest("00c0d899-a595-4c66-9071-bc59374bbe6b");
request.setCriteria(compound);
request.setDisplayName("Entertainment but not sports");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Segment,
    tag, not_, and_
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Update an existing segment
segment = Segment()
segment.from_id(client, "00c0d899-a595-4c66-9071-bc59374bbe6b")

# Update segment properties
segment.display_name = "Entertainment but not sports"
segment.criteria = and_(
    tag('entertainment'),
    not_(tag('sports'))
)

# Save the changes
response = segment.update(client)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

segment = UA::Segment.new(client: airship)
segment.from_id(id: '00c0d899-a595-4c66-9071-bc59374bbe6b')
segment.display_name = 'New Display Name'
segment.criteria = { 'tag' => 'new_tag' }
segment.update

Change the definition of the Segment.

 Note

Segmentation data is evaluated at send time. If you schedule a message that targets a Segment and then edit that Segment, the scheduled message automatically uses the updated Segment criteria. “Scheduled” includes recurring messages.

Security:

Path parameters:

  • segment_id stringREQUIRED
    The Segment you want to retrieve.

Request body:

A single Segment object.

  • Content-Type: application/json

    Segment object

    A set of audience selection criteria that you can reuse as a segment.

    OBJECT PROPERTIES
    • criteria objectREQUIRED

      Defines the set of devices to send notifications to. criteria is a JSON expression containing the same information as the audience selector, including Event Segmentation. See Audience selection for more information.

      One of
      • Compound Selector

        Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

      • Atomic Selector

        Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.

    • display_name stringREQUIRED

      Human readable name for this Segment. This will be used in the dashboard.

Responses

  • 200

    Returned if the Segment has been successfully updated.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete Segment

DELETE /api/segments/{segment_id}

Example

DELETE /api/segments/00c0d899-a595-4c66-9071-bc59374bbe6b HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 204 No Content

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SegmentDeleteRequest request = SegmentDeleteRequest.newRequest("00c0d899-a595-4c66-9071-bc59374bbe6b");
Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Segment
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Delete a segment
segment = Segment()
segment.from_id(client, "00c0d899-a595-4c66-9071-bc59374bbe6b")
response = segment.delete(client)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

segment = UA::Segment.new(client: airship)
segment.from_id(id: '00c0d899-a595-4c66-9071-bc59374bbe6b')
segment.delete

Remove the Segment.

Security:

Path parameters:

  • segment_id stringREQUIRED
    The Segment you want to retrieve.

Responses

  • 204

    An API request was successful, but there is no response body to return.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Attribute Lists

Define and manage attribute lists; upload corresponding attribute data in CSV format.

Retrieve lists

GET /api/attribute-lists

Example

GET /api/attribute-lists HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Attribute: lists
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok": true,
  "lists": [
      {
        "name": "ua_attributes_my_list",
        "description": "My first list",
        "extra": {
            "filename": "list.csv",
            "source": "crm"
        },
        "created": "2020-05-13T21:41:25",
        "last_updated": "2020-05-13T21:45:17",
        "channel_count": 0,
        "error_path": "https://go.urbanairship.com/api/attribute-lists/ua_attributes_my_list/errors",
        "status": "ready"
      },
      {
        "name": "ua_attributes_another_list",
        "description": "My second list",
        "extra": {
            "filename": "list2.csv",
            "source": "api"
        },
        "created": "2020-05-14T21:41:25",
        "last_updated": "2020-05-14T21:45:17",
        "channel_count": 0,
        "error_path": "https://go.urbanairship.com/api/attribute-lists/ua_attributes_another_list/errors",
        "status": "ready"
      }
  ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

AttributeListsListingRequest attributeListsListingRequest = AttributeListsListingRequest.newRequest();
Response<AttributeListsListingResponse> response = client.execute(attributeListsListingRequest);

from urbanairship import (
    BasicAuthClient, AttributeList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

listing = AttributeList.list(airship=client)

listing.json()

Retrieve information about all Attributes lists. This call returns a list of metadata that will not contain the actual lists of users.

Security:

Responses

  • 200

    Lists metadata retrieved successfully.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • lists array

        An array of list objects.

      • ok boolean

        Success.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create Attributes list

POST /api/attribute-lists

Example

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

{
  "name": "ua_attributes_my_new_list",
  "description": "First of many attributes lists!",
  "extra": {
      "filename": "attributes.csv",
      "source": "CRM"
  }
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://go.urbanairship.com/api/attribute-lists/ua_attributes_my_new_list

{
  "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();
        
AttributeListsCreateRequest attributeListsCreateRequest = AttributeListsCreateRequest.newRequest("ua_attributes_list")
        .setDescription("ua_attributes_list")
        .addExtra("filename", "attributes.csv")
        .addExtra("source","crm");

Response<GenericResponse> response = client.execute(attributeListsCreateRequest);

from urbanairship import (
    BasicAuthClient, AttributeList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

attribute_list = AttributeList(
  client=client, 
  list_name="ua_attributes_my_new_list", 
  description="First of many attributes lists!", 
  extra={
      "filename": "attributes.csv",
      "source": "CRM"
  }
)

attribute_list.create()

Create a new Attributes list by defining it in the Airship system. The body of the request contains the name, description, and optional metadata for the list. After you define a list, you populate it with a call to the Upload Attribute List endpoint.

Security:

Request body:

  • Content-Type: application/json

    Attribute list metadata object

    Contains all user-specified data when defining an attributes list in Airship.

    OBJECT PROPERTIES
    • description string

      An optional description for the list.

    • extra object

      An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.

    • name stringREQUIRED

      The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.

      Note: Since the name portion of the URL may represent any Unicode string, it must be encoded properly as a URI path component. The encodeURIComponent function in JavaScript can be used.

      The list name must include a prefix that determines how empty values are handled:

      • Lists with ua_attributes_ prefix: Empty or null values are ignored, preserving any existing attribute values not explicitly set in the CSV. This mode is useful for making partial updates to a user’s attributes without affecting others.
      • Lists with ua_attributes_snapshot_ prefix: Empty or null values trigger removing those attributes from the user. This mode is useful for synchronizing attribute states with external systems, ensuring the attributes in the CSV exactly match the user’s attributes.

Responses

  • 201

    The list was created successfully.

    Response headers:

    • Location string

      The URI of the list, used for later updates.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 409

    The request conflicts with another request.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Upload Attribute list

PUT /api/attribute-lists/{list_name}/csv

Upload Attribute list example

PUT /api/attribute-lists/ua_attributes_list/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

channel_id,Magic Score,Preferred Sport
c543f3a3-bc1d-4830-8dee-7532c6a23b9a,100,Basketball
6ba360a0-1f73-4ee7-861e-95f6c1ed6410,,Basketball
15410d17-687c-46fa-bbd9-f255741a1523,2,Football
c2c64ef7-8f5c-470e-915f-f5e3da04e1df,22.1,Rugby

Upload Attribute Snapshot list example

PUT /api/attribute-lists/ua_attributes_list/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

channel_id,Magic Score,Preferred Sport
c543f3a3-bc1d-4830-8dee-7532c6a23b9a,100,Basketball
6ba360a0-1f73-4ee7-861e-95f6c1ed6410,,Basketball
15410d17-687c-46fa-bbd9-f255741a1523,2,Football
c2c64ef7-8f5c-470e-915f-f5e3da04e1df,22.1,Rugby

PUT /api/attribute-lists/ua_attributes_snapshot_list/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

channel_id,Magic Score,Preferred Sport,Favorite Team
c543f3a3-bc1d-4830-8dee-7532c6a23b9a,100,Basketball,Lakers
6ba360a0-1f73-4ee7-861e-95f6c1ed6410,,,,
15410d17-687c-46fa-bbd9-f255741a1523,2,Football,
c2c64ef7-8f5c-470e-915f-f5e3da04e1df,22.1,,Patriots

# In this example using a Snapshot CSV:
# - First user has all attributes set
# - Second user has all attributes removed (empty values)
# - Third user has Magic Score and Preferred Sport set, but Favorite Team removed
# - Fourth user has Magic Score and Favorite Team set, but Preferred Sport removed

from urbanairship import (
    BasicAuthClient, AttributeList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# For standard attribute lists, use ua_attributes_ prefix
standard_list = AttributeList(
  client=client, 
  list_name="ua_attributes_list",
  description="example standard list",
)
standard_list.upload(file_path="path/to/standard_file.csv")

# For attributesnapshot lists, use ua_attributes_snapshot_ prefix
snapshot_list = AttributeList(
  client=client,
  list_name="ua_attributes_snapshot_list",
  description="example snapshot list",
)
snapshot_list.upload(file_path="path/to/snapshot_file.csv")

Upload Attribute list for SMS example

PUT /api/attribute-lists/ua_attributes_list/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

channel_id,Magic Score,Preferred Sport
c543f3a3-bc1d-4830-8dee-7532c6a23b9a,100,Basketball
6ba360a0-1f73-4ee7-861e-95f6c1ed6410,,Basketball
15410d17-687c-46fa-bbd9-f255741a1523,2,Football
c2c64ef7-8f5c-470e-915f-f5e3da04e1df,22.1,Rugby

PUT /api/attribute-lists/ua_attributes_snapshot_list/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

channel_id,Magic Score,Preferred Sport,Favorite Team
c543f3a3-bc1d-4830-8dee-7532c6a23b9a,100,Basketball,Lakers
6ba360a0-1f73-4ee7-861e-95f6c1ed6410,,,,
15410d17-687c-46fa-bbd9-f255741a1523,2,Football,
c2c64ef7-8f5c-470e-915f-f5e3da04e1df,22.1,,Patriots

# In this example using a Snapshot CSV:
# - First user has all attributes set
# - Second user has all attributes removed (empty values)
# - Third user has Magic Score and Preferred Sport set, but Favorite Team removed
# - Fourth user has Magic Score and Favorite Team set, but Preferred Sport removed

from urbanairship import (
    BasicAuthClient, AttributeList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# For standard attribute lists, use ua_attributes_ prefix
standard_list = AttributeList(
  client=client, 
  list_name="ua_attributes_list",
  description="example standard list",
)
standard_list.upload(file_path="path/to/standard_file.csv")

# For attributesnapshot lists, use ua_attributes_snapshot_ prefix
snapshot_list = AttributeList(
  client=client,
  list_name="ua_attributes_snapshot_list",
  description="example snapshot list",
)
snapshot_list.upload(file_path="path/to/snapshot_file.csv")

PUT /api/attribute-lists/ua_attributes_list/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

msisdn,sms_sender,firstName
5035556789,18588675309,Jane
4155551212,18588675309,Rory

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "ok" : true
}

from urbanairship import (
    BasicAuthClient, AttributeList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

attribute_list = AttributeList(
  client=client, 
  list_name="ua_attributes_list",
  description="example list", 
)

attribute_list.upload(file_path="path/to/sms_file.csv")

Upload a CSV that will set Attribute values on the specified channels or Named Users.

CSV guidelines:

  • The first entry in the uploaded CSV must be a header row. The first field must be one of the following identifier types: channel_id, msisdn, email_address, or named_user.
  • Only one identifier type is allowed per file unless the identifier type name matches a custom Attribute schema for the associated app key.
  • You must include both msisdn and sms_sender columns when targeting SMS or MMS channel types. See example to the right.
  • Uploads must be newline-delimited identifiers (text/CSV) as described in RFC 4180, with commas as the delimiter, optionally double-quoted values, UTF-8 encoded, and with CRLF or LF line separators.

Required column headers per identifier type:

Target typeRequired column headers
iOSchannel_id
Androidchannel_id
Named Usernamed_user
Webchannel_id
Emailemail_address
Open Channelchannel_id
SMS
  • msisdn (numeric and no leading 0)
  • sms_sender (numeric, e.g., 1234)
MMS
  • msisdn (numeric and no leading 0)
  • sms_sender (numeric, e.g., 1234)

Optional Fields: Opt-in dates can optionally be set for new channels when the identifier is an email_address or msisdn.

Target typeOptional column headers
SMSua_opted_in (UTC Timestamp)
MMSua_opted_in (UTC Timestamp)
Email
  • ua_transactional_opted_in (UTC Timestamp)
  • ua_commercial_opted_in (UTC Timestamp)

 Note

A list can contain a maximum of 10 million rows and 101 columns: one identifier column and 100 Attribute or internal header columns. Content-Encoding: gzip is supported and recommended on this endpoint to reduce network traffic.

 Warning

If your upload times out due to a poor connection, you must re-upload the list from scratch. Because we want to ensure that the entirety of a given list is successfully uploaded, we do not support partial list uploads.

Security:

Path parameters:

  • list_name stringREQUIRED
    The name of the list you want to upload.

Request body:

  • Content-Type: text/csv

    Type: string

Responses

  • 202

    The request has been accepted for processing.

    Response body:

    • Content-Type: application/json
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    Bad Request. Parsing or validating the request failed.

    Error codeDescription
    40002CSV contains too many identifiers
    40003CSV header contains too many columns
    40013CSV header’s first field must be an identifier
    40014CSV header contains an unknown Attribute name
    40015CSV header contains duplicate Attribute names
    40017CSV header contains duplicate column names
    40018CSV header does not contain required column for identifier type

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Download list errors

GET /api/attribute-lists/{list_name}/errors

Example

GET /api/attribute-lists/ua_attributes_list/errors HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+csv; version=3

HTTP/1.1 200 OK
Content-Type: text/csv

8b4de669-16f1-4e71-9a1f-0c62a8235a65,ERROR,"Unable to parse number: forty-two"
d5ebe607-a3e6-4601-b97e-83ec604223fe,ERROR,"Unable to parse date: monday"

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

AttributeListsErrorsRequest attributeListsErrorsRequest = AttributeListsErrorsRequest.newRequest("ua_attributes_list");
Response<String> response = client.execute(attributeListsErrorsRequest);

from urbanairship import (
    BasicAuthClient, AttributeList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

attribute_list = AttributeList(
  client=client, 
  list_name="ua_attributes_list",
  description="example list", 
)

errors = attribute_list.get_errors()

During processing, after a list is uploaded, errors can occur. Depending on the type of list processing, an error file may be created, showing a user exactly what went wrong.

Security:

Path parameters:

  • list_name stringREQUIRED
    The name of the list.

Responses

  • 200

    The response will contain the errors found during list processing.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      List response object

      Contains all user-specified data about a static list or attributes list (metadata), but does not contain CSV list contents. Use the /api/lists/{name}/csv endpoints to upload or download list contents.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Static Lists

With the Static List API endpoint, you can target and manage lists of devices that are defined in systems outside of Airship. Any list or grouping of devices for which the canonical source of data about the members is elsewhere is a good candidate for Static Lists, e.g., members of a customer loyalty program. In the dashboard, they are referred to as Uploaded Lists.

Airship automatically deletes a Static list and all its versions after 90 days of inactivity. Timestamps used to calculate the 90-day period are the creation date, when updating list contents or metadata, and when sending a message (pushing) to the list. The creation date is the initial day one of the 90-day period. Each instance of updating or sending to the list resets the timestamp to day one.

After automatic deletion or deleting from the Airship dashboard, the list is removed from the upload history, is no longer visible in the Airship dashboard or through API calls, and is no longer available for audience segmentation.

Retrieve lists

GET /api/lists

Example

GET /api/lists HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Attribute: lists
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : true,
   "lists" : [
      {
         "name" : "platinum_members",
         "description" : "loyalty program platinum members",
         "extra" : { "key" : "value" },
         "created" : "2020-04-08T20:41:06",
         "last_modified" : "2020-05-01T18:00:27",
         "channel_count": 3145,
         "status": "ready"
      },
      {
         "name": "gold_members",
         "description": "loyalty program gold member",
         "extra": { "key": "value" },
         "created": "2020-04-08T20:41:06",
         "last_updated": "2020-05-01T18:00:27",
         "channel_count": 678,
         "status": "ready"
      }
   ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

StaticListListingRequest request = StaticListListingRequest.newRequest();
Response<StaticListListingResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticLists
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# List all static lists
static_lists = StaticLists(client)
for static_list in static_lists:
    print(
        static_list.name,
        static_list.description,
        static_list.extra,
        static_list.created,
        static_list.last_updated,
        static_list.channel_count,
        static_list.status
    )

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_lists = UA::StaticLists.new(client: airship)

static_lists.each do |static_list|
    puts(static_list)
end

Retrieve information about all static lists. This call returns a list of metadata that will not contain the actual lists of users.

Security:

Responses

  • 200

    Lists metadata retrieved successfully.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • lists array

        An array of list objects.

      • ok boolean

        Success.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create list

POST /api/lists

Example

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

{
   "name" : "platinum_members",
   "description" : "loyalty program platinum members",
   "extra" : {
      "key" : "value",
      "another" : "etc."
   }
}

HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/lists/platinum_members
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

StaticListRequest request = StaticListRequest.newRequest("platinum_members")
                .setDescription("loyalty program platinum members")
                .addExtra("key", "value");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Create a new static list
static_list = StaticList(
    client=client,
    name='platinum_members'
)
static_list.description = 'loyalty program platinum members'
static_list.extra = {'key': 'value'}

response = static_list.create()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_list = UA::StaticList.new(client: airship)
static_list.name = 'platinum_members'
static_list.create(description: 'loyalty program platinum members')

Create a static list. The body of the request will contain several of the list object parameters, but the actual list content will be provided by a second call to the upload endpoint. You can upload up to 100 lists per project.

 Note

Content-Encoding: gzip is supported and recommended on this endpoint to reduce network traffic.

Security:

Request body:

  • Content-Type: application/json

    List metadata object

    Contains all user-specified data when defining a static list in Airship.

    OBJECT PROPERTIES
    • description string

      An optional description for the list.

    • extra object

      An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.

    • name stringREQUIRED

      The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.

      Note: Since the name portion of the URL may represent any Unicode string, it must be encoded properly as a URI path component. The encodeURIComponent function in JavaScript can be used.

Responses

  • 201

    The list was created successfully.

    Response headers:

    • Location string

      The URI of the list, used for later updates.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 409

    The request conflicts with another request.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Get single list metadata

GET /api/lists/{list_name}

Example

GET /api/lists/platinum_members/ HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Attribute: static_list
Link: <https://go.urbanairship.com/api/platinum_members/list/?start=uuid101&limit=100>; rel=next
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : true,
   "name" : "platinum_members",
   "description" : "loyalty program platinum members",
   "extra" : { "key" : "value" },
   "created" : "2020-04-08T20:41:06",
   "last_updated" : "2020-05-01T18:00:27",
   "channel_count" : 1000,
   "status" : "ready"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

StaticListLookupRequest request = StaticListLookupRequest.newRequest("platinum_members");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Look up a static list
static_list = StaticList(
    client=client,
    name='platinum_members'
)
response = static_list.lookup()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_list = UA::StaticList.new(client: airship)
static_list.name = 'platinum_members'
static_list.lookup

Retrieve information about one static list, specified in the URL. When looking up lists, the returned information may actually be a combination of values from both the last uploaded list and the last successfully processed list. If you create a list successfully, and then you update it and the processing step fails, then the list status will read failed, but the channel_count and last_modified fields will contain information on the last successfully processed list.

Security:

Path parameters:

  • list_name stringREQUIRED
    The name of the list.

Responses

  • 200

    List metadata retrieved successfully.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • description string

        An optional description for the list.

      • extra object

        An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.

      • name string

        The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.

      • ok boolean

        Success.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update list metadata

PUT /api/lists/{list_name}

Example

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

{
   "name" : "platinum_members",
   "description" : "loyalty program platinum members",
   "extra" : {
      "key" : "value"
   }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

StaticListRequest request = StaticListRequest.newUpdateRequest("platinum_members")
                .setDescription("loyalty program platinum members")
                .addExtra("key", "value");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Update an existing static list
static_list = StaticList(
    client=client,
    name='platinum_members'
)
static_list.description = 'loyalty program platinum members'
static_list.extra = {'key': 'value'}

response = static_list.update()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_list = UA::StaticList.new(client: airship)
static_list.name = 'platinum_members'
static_list.update(description: 'loyalty program platinum members')

Update the metadata (description, extras, etc.) of a static list.

 Note

To update the list contents, use the list upload endpoint. The update endpoint is used to update a list’s metadata rather than the actual list of device identifiers.

Security:

Path parameters:

  • list_name stringREQUIRED
    The name of the list.

Request body:

The body of the request will contain a list metadata object, though you can omit the name attribute. If present, it must match the name provided in the URL. You cannot change the name of a list; it is the primary identifier for the list.

  • Content-Type: application/json

    List metadata object

    Contains all user-specified data when defining a static list in Airship.

    OBJECT PROPERTIES
    • description string

      An optional description for the list.

    • extra object

      An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.

    • name stringREQUIRED

      The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.

      Note: Since the name portion of the URL may represent any Unicode string, it must be encoded properly as a URI path component. The encodeURIComponent function in JavaScript can be used.

Responses

  • 200

    The list metadata was updated successfully.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    Bad Request. Parsing or validating the request failed. error_code 40001: Attempted list rename. List renaming is not allowed.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g., the API may not be used to create or modify lists with a ua_ prefixed name.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete a list

DELETE /api/lists/{list_name}

Example

DELETE /api/lists/platinum_members HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 204 No Content

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

StaticListDeleteRequest request = StaticListDeleteRequest.newRequest("platinum_members");
Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Delete a static list
static_list = StaticList(
    client=client,
    name='platinum_members'
)
response = static_list.delete()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_list = UA::StaticList.new(client: airship)
static_list.name = 'platinum_members'
static_list.delete

Delete a static list.

 Warning

If you are attempting to update a current list by deleting it and then recreating it with new data, stop and go to the upload endpoint. There is no need to delete a list before uploading a new CSV file. Moreover, once you delete a list, you will be unable to create a list with the same name as the deleted list.

Security:

Path parameters:

  • list_name stringREQUIRED
    The name of the list.

Responses

  • 204

    An API request was successful, but there is no response body to return.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    You cannot delete or modify lists with a ua_ prefixed name.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Download a list of channels

GET /api/lists/{list_name}/csv

Example

GET /api/lists/foobar/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+csv; version=3

HTTP/1.1 200 OK
Content-Type: text/csv

ios_channel,6d56ab7e-2c78-4ba9-ab11-d9b664ca2b32
ios_channel,d5ebe607-a3e6-4601-b97e-83ec604223fe
ios_channel,fa599af7-43e4-4862-a570-1470bf6f53ff
android_channel,0e91d0f2-c65d-4b40-b968-b9f8e8b0c987
android_channel,c346a3ce-5754-4d02-8ee5-500ce470a0b7
android_channel,e9a01369-5f74-4167-b660-df84014a2e57
amazon_channel,0356d138-d1d9-4572-b321-e1b67f4cd658
amazon_channel,24dc9a76-45fe-4b17-8ed7-841f96b658ad
amazon_channel,4d6b59f8-6d8c-4151-8b13-cd58d6ac8c6e

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

StaticListDownloadRequest request = StaticListDownloadRequest.newRequest("foobar");
Response<String> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Download a static list
response = StaticList.download(
    client=client,
    list_name='platinum_members'
)

Allows you to download the contents of a static list (as opposed to a GET /api/lists/{list_name}, which will return metadata about the list). The CSV output from this endpoint will only include entries originally uploaded as ios_channel, android_channel, or amazon_channel.

Security:

Path parameters:

  • list_name stringREQUIRED
    The name of the list you want to retrieve or update.

Responses

  • 200

    Returns a CSV list of channels.

    Response body:

    • Content-Type: text/csv

      Type: string

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update list contents

PUT /api/lists/{list_name}/csv

Example

PUT /api/lists/platinum_members/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

named_user,customer-42
named_user,room-27
ios_channel,5i4c91s5-9tg2-k5zc-m592150z5634
web_channel,d132f5b7-abcf-4920-aeb3-9132ddac3d5a
android_channel,52b2b587-0152-4134-a8a0-38ae6933c88a
email_channel,ab1a81e3-5af3-4c04-a7ae-d676960e6684
open_channel,6bcf3e63-a38a-44d8-8b0d-2fb5941e74ab
sms_channel,ab1a81e3-aaf3-ac04-a7ae-a676960e6684

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

File dataDirectory = new File("src/data");
String filePath = dataDirectory.getAbsolutePath() + "/platinum.csv";
StaticListUploadRequest request = StaticListUploadRequest.newRequest("platinum_members", filePath);

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Upload a CSV file to a static list
static_list = StaticList(
    client=client,
    name='platinum_members'
)

with open('list.csv', 'r') as csv_file:
    response = static_list.upload(csv_file)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_list = UA::StaticList.new(client: airship)
static_list.name = 'platinum_members'
File.open('csv_file', 'rb') do |csv|
    static_list.upload(csv_file: csv, gzip: false)
end

Example request with header row

PUT /api/lists/platinum_members/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

named_user,customer-42
named_user,room-27
ios_channel,5i4c91s5-9tg2-k5zc-m592150z5634
web_channel,d132f5b7-abcf-4920-aeb3-9132ddac3d5a
android_channel,52b2b587-0152-4134-a8a0-38ae6933c88a
email_channel,ab1a81e3-5af3-4c04-a7ae-d676960e6684
open_channel,6bcf3e63-a38a-44d8-8b0d-2fb5941e74ab
sms_channel,ab1a81e3-aaf3-ac04-a7ae-a676960e6684

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

File dataDirectory = new File("src/data");
String filePath = dataDirectory.getAbsolutePath() + "/platinum.csv";
StaticListUploadRequest request = StaticListUploadRequest.newRequest("platinum_members", filePath);

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Upload a CSV file to a static list
static_list = StaticList(
    client=client,
    name='platinum_members'
)

with open('list.csv', 'r') as csv_file:
    response = static_list.upload(csv_file)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_list = UA::StaticList.new(client: airship)
static_list.name = 'platinum_members'
File.open('csv_file', 'rb') do |csv|
    static_list.upload(csv_file: csv, gzip: false)
end

PUT /api/lists/foobar/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

Identifier Type,Identifier
alias,some-user-12345
alias,some-user-12346
ios_channel,5b1a81e3-5af3-4c04-a7ae-d676960e6684
named_user,SODFHsodfuJ9433
named_user,"contains,comma"
named_user,"contains""double-quote"

Replace the contents of an existing static list via CSV file upload. Uploads must be newline-delimited identifiers (text/CSV) with commas as the delimiter.

The CSV format is two columns: identifier_type and identifier. The identifier is the associated identifier you wish to send to. The identifier_type must be one of:

  • named_user
  • ios_channel
  • android_channel
  • amazon_channel
  • sms_channel
  • email_channel
  • open_channel
  • web_channel

The first entry in the uploaded CSV may be a header row, which will be ignored. If present, the header row must contain exactly two entries, and the first column must not be an identifier_type as specified above.

 Note

The maximum number of identifier_type,identifier pairs that may be uploaded to a list is 10 million. Content-Encoding: gzip is supported and recommended on this endpoint to reduce network traffic.

 Warning

If an attempt to upload a list times out due to a poor connection, you must re-upload the list from scratch. Because we want to ensure that the entirety of a given list is successfully uploaded, we do not support partial list uploads.

Security:

Path parameters:

  • list_name stringREQUIRED
    The name of the list you want to retrieve or update.

Request body:

  • Content-Type: text/csv

    Type: string

Responses

  • 202

    The request has been accepted for processing.

    Response body:

    • Content-Type: application/json
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    Bad Request. Parsing or validating the request failed.

    Error codeDescription
    40002CSV contains too many identifiers
    40003CSV contains an entry with a column count other than 2
    40004CSV contains an invalid identifier_type
    40005CSV contains a channel identifier that is not a valid UUID

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Bulk Sending

Target recipients of a single channel type by providing audience identifiers at send time. Bulk sending supports two methods:

See the Bulk sending guide for more information.

Send message with bulk ID

POST /api/bulk-send

Example send message with bulk ID

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

{
    "audience" : {
      "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
    },
    "device_types" : [ "android" ],
    "notification" : {
      "alert" : "Welcome to the winter sale!!"
    },
    "campaigns": {
      "categories": ["winter sale", "west coast"]
    }
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
    "push_ids": [
      "c0eead17-333b-4f86-8a42-9fb7be1ed627"
    ],
    "message_ids": [],
    "content_urls": []
}

Send an immediate message to existing channels using a bulk_id. Inactive channels are dropped. Before calling this endpoint, obtain a bulk_id from the Create bulk send audience endpoint.

Security:

Request body:

A Send a message with bulk ID payload.

Responses

  • 202

    The push notification has been accepted for processing. The response contains push_id, message_id, and/or content_url arrays based on the type of push.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      A push response contains a list of identifiers for the notifications sent in the request.

      OBJECT PROPERTIES
      • content_urls array[string]

        An array of URLs where the push payload contains a landing page action.

      • localized_ids array[string]

        An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).

      • message_ids array[string]

        An array of message IDs, each uniquely identifying a Message Center message.

      • ok boolean

        Success.

      • operation_id string

        A unique string identifying the operation, useful for reporting and troubleshooting.

      • push_ids array[string]

        An array of push IDs, each uniquely identifying a push.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 429

    Too many requests hit the API too quickly. For example, if we are not ready to create a channel for this payload; e.g., it is rate limited. You should wait before retrying the channel creation.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate message with bulk ID

POST /api/bulk-send/validate

Example validate message with bulk ID

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

{
    "audience" : {
      "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
    },
    "device_types" : [ "android" ],
    "notification" : {
      "alert" : "Welcome to the winter sale!!"
    },
    "campaigns": {
      "categories": ["winter sale", "west coast"]
    }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

Accept the same range of payloads as POSTing to /api/bulk-send, but parse and validate only, without sending any messages. Before calling this endpoint, obtain a bulk_id using the Create bulk send audience operation.

Security:

Request body:

A single bulk send object.

Responses

  • 200

    The payload was valid.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create bulk send audience

POST /api/bulk/{platform_name}

Example create bulk send audience request for email

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

ua_address,ua_commercial_opted_in
someone@example.com,2024-04-01T18:45:30
else@example.com,2024-04-21T16:13:01

Example create bulk send audience request for SMS

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

ua_address,ua_commercial_opted_in
someone@example.com,2024-04-01T18:45:30
else@example.com,2024-04-21T16:13:01

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

ua_msisdn,ua_sender,ua_opted_in
15035551212,55555,2024-04-01T18:45:30
15031215555,55555,2024-04-21T16:13:01

Example create bulk send audience request for email with merge data fields

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

ua_address,ua_commercial_opted_in
someone@example.com,2024-04-01T18:45:30
else@example.com,2024-04-21T16:13:01

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

ua_msisdn,ua_sender,ua_opted_in
15035551212,55555,2024-04-01T18:45:30
15031215555,55555,2024-04-21T16:13:01

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

ua_address,ua_commercial_opted_in,name,city
someone@example.com,2024-04-01T18:45:30,Joe Someone,Portland
else@example.com,2024-04-21T16:13:01,Sir Else,Seattle

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : true,
  "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
  "field_names": ["ua_address", "ua_commercial_opted_in", "name", "city"]
}

Example create bulk send audience request for email

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

ua_address,ua_commercial_opted_in
someone@example.com,2024-04-01T18:45:30
else@example.com,2024-04-21T16:13:01

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

ua_msisdn,ua_sender,ua_opted_in
15035551212,55555,2024-04-01T18:45:30
15031215555,55555,2024-04-21T16:13:01

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

ua_address,ua_commercial_opted_in,name,city
someone@example.com,2024-04-01T18:45:30,Joe Someone,Portland
else@example.com,2024-04-21T16:13:01,Sir Else,Seattle

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : true,
  "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
  "field_names": ["ua_address", "ua_commercial_opted_in", "name", "city"]
}

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

ua_channel_id
26bbfba4-f70a-4093-ab63-38d9123f6b23
89099449-6032-4821-8f1c-fd0892fdc609

Example create bulk send audience request for email with merge data fields

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

ua_address,ua_commercial_opted_in
someone@example.com,2024-04-01T18:45:30
else@example.com,2024-04-21T16:13:01

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

ua_msisdn,ua_sender,ua_opted_in
15035551212,55555,2024-04-01T18:45:30
15031215555,55555,2024-04-21T16:13:01

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

ua_address,ua_commercial_opted_in,name,city
someone@example.com,2024-04-01T18:45:30,Joe Someone,Portland
else@example.com,2024-04-21T16:13:01,Sir Else,Seattle

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : true,
  "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
  "field_names": ["ua_address", "ua_commercial_opted_in", "name", "city"]
}

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

ua_channel_id
26bbfba4-f70a-4093-ab63-38d9123f6b23
89099449-6032-4821-8f1c-fd0892fdc609

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

ua_channel_id,name,city
26bbfba4-f70a-4093-ab63-38d9123f6b23,2018-04-01T18:45:30,Joe Someone,Portland
89099449-6032-4821-8f1c-fd0892fdc609,2018-04-21T16:13:01,Sir Else,Seattle

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
    "field_names": ["ua_channel_id", "name", "city"]
}

Example create bulk send audience request for open platform

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

ua_address,ua_commercial_opted_in
someone@example.com,2024-04-01T18:45:30
else@example.com,2024-04-21T16:13:01

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

ua_msisdn,ua_sender,ua_opted_in
15035551212,55555,2024-04-01T18:45:30
15031215555,55555,2024-04-21T16:13:01

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

ua_address,ua_commercial_opted_in,name,city
someone@example.com,2024-04-01T18:45:30,Joe Someone,Portland
else@example.com,2024-04-21T16:13:01,Sir Else,Seattle

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : true,
  "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
  "field_names": ["ua_address", "ua_commercial_opted_in", "name", "city"]
}

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

ua_channel_id
26bbfba4-f70a-4093-ab63-38d9123f6b23
89099449-6032-4821-8f1c-fd0892fdc609

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

ua_channel_id,name,city
26bbfba4-f70a-4093-ab63-38d9123f6b23,2018-04-01T18:45:30,Joe Someone,Portland
89099449-6032-4821-8f1c-fd0892fdc609,2018-04-21T16:13:01,Sir Else,Seattle

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
    "field_names": ["ua_channel_id", "name", "city"]
}

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

ua_address
17881e35-4dcc-4f72-a017-e5aca8bb85f5
47745e49-099d-48d7-a489-563a2ae7497d
03079fe7-a013-4a22-9c1b-bca350a3e3fb
8a9b3ebc-010c-41c1-9484-6395b201dffe
65fefb71-c38e-4af8-9d6f-ec8bfcefd999
6e6fc2ee-722a-4729-86c3-f6d289373c41

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : true,
  "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
  "field_names": ["ua_address"]
}

Example create bulk send audience request for open channels

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

ua_address,ua_commercial_opted_in
someone@example.com,2024-04-01T18:45:30
else@example.com,2024-04-21T16:13:01

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

ua_msisdn,ua_sender,ua_opted_in
15035551212,55555,2024-04-01T18:45:30
15031215555,55555,2024-04-21T16:13:01

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

ua_address,ua_commercial_opted_in,name,city
someone@example.com,2024-04-01T18:45:30,Joe Someone,Portland
else@example.com,2024-04-21T16:13:01,Sir Else,Seattle

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : true,
  "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
  "field_names": ["ua_address", "ua_commercial_opted_in", "name", "city"]
}

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

ua_channel_id
26bbfba4-f70a-4093-ab63-38d9123f6b23
89099449-6032-4821-8f1c-fd0892fdc609

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

ua_channel_id,name,city
26bbfba4-f70a-4093-ab63-38d9123f6b23,2018-04-01T18:45:30,Joe Someone,Portland
89099449-6032-4821-8f1c-fd0892fdc609,2018-04-21T16:13:01,Sir Else,Seattle

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
    "field_names": ["ua_channel_id", "name", "city"]
}

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

ua_address
17881e35-4dcc-4f72-a017-e5aca8bb85f5
47745e49-099d-48d7-a489-563a2ae7497d
03079fe7-a013-4a22-9c1b-bca350a3e3fb
8a9b3ebc-010c-41c1-9484-6395b201dffe
65fefb71-c38e-4af8-9d6f-ec8bfcefd999
6e6fc2ee-722a-4729-86c3-f6d289373c41

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : true,
  "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
  "field_names": ["ua_address"]
}

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

ua_channel_id
26bbfba4-f70a-4093-ab63-38d9123f6b23
89099449-6032-4821-8f1c-fd0892fdc609

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
    "field_names": ["ua_channel_id"]
}

Upload a CSV to obtain a bulk_id for sending messages. The CSV can contain:

See Bulk sending for CSV formatting requirements.

Security:

Path parameters:

  • platform_name stringREQUIRED
    The audience channel platform. For open platforms, format the {platform_name} as open/{open_platform_name}.

    Possible values: android, amazon, ios, web, sms, email, open_platform_name

Request body:

  • Content-Type: text/csv

    Type: string

    A CSV of Channel IDs, email addresses, MSISDNs, or Open channel addresses. See Bulk sending for CSV formatting requirements.

Responses

  • 200

    The CSV was uploaded successfully and is now being processed.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      The upload CSV response.

      OBJECT PROPERTIES
      • bulk_id string

        A unique string that identifies the audience provided in the CSV for bulk sending.

      • field_names array[string]

        A list of the field names found in the CSV.

      • ok boolean

        Success.

  • 400

    Bad Request. Parsing or validating the request failed.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create and Send a message

POST /api/create-and-send

Example Create and Send a message for email

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

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22",
        "ua_open_tracking_opted_in": "2022-11-02T10:35:00",
        "ua_click_tracking_opted_in": "2022-11-02T10:36:00" 
      },
      {
        "ua_address" : "ben@example.com",
        "ua_commercial_opted_in": "2020-11-29T12:45:10",
        "ua_open_tracking_opted_out": "2022-11-02T10:35:00",
        "ua_click_tracking_opted_out": "2022-11-02T10:36:00"
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "subject": "Welcome to the 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": "Airship",
      "sender_address": "team@airship.com",
      "reply_to": "no-reply@airship.com",
      "click_tracking": false,
      "open_tracking": false
    }
  },
  "campaigns": {
      "categories": ["winter sale", "west coast"]
  }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

String htmlBodyString = "<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>";
String plaintextBodyString = "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]";

EmailChannel newChannel = EmailChannel.newBuilder()
        .setAddress("new@example.com")
        .setCommertialOptedIn(DateTime.parse("2020-11-29T10:34:22Z"))
        .build();

EmailChannel benChannel = EmailChannel.newBuilder()
        .setAddress("ben@example.com")
        .setTransactionalOptedIn(DateTime.parse("2020-11-29T12:45:10Z"))
        .build();

CreateAndSendAudience audience = new CreateAndSendAudience(EmailChannels.newBuilder()
        .addChannel(newChannel)
        .addChannel(benChannel)
        .build());

CreateAndSendEmailPayload createAndSendEmailPayload = CreateAndSendEmailPayload.newBuilder()
        .setSubject("Welcome to the Winter Sale! ")
        .setHtmlBody(htmlBodyString)
        .setPlaintextBody(plaintextBodyString)
        .setMessageType(MessageType.TRANSACTIONAL)
        .setSenderName("Airship")
        .setSenderAddress("team@airship.com")
        .setReplyTo("no-reply@airship.com")
        .build();

Notification notification = Notification.newBuilder()
        .addDeviceTypeOverride(DeviceType.EMAIL, createAndSendEmailPayload)
        .build();

Campaigns campaign = Campaigns.newBuilder()
        .addCategory("winter sale")
        .addCategory("west coast")
        .build();

CreateAndSendPayload payload = CreateAndSendPayload.newBuilder()
        .setAudience(audience)
        .setNotification(notification)
        .setCampaigns(campaign)
        .build();

CreateAndSendRequest request = CreateAndSendRequest.newRequest(payload);
Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, CreateAndSendPush, email, sms, mms, campaigns
)

client = BasicAuthClient(key='<app_key>', secret='<master_secret>')

# Create and Send a message for email
push = CreateAndSendPush(client)
push.audience = {
    "create_and_send": [
        {
            "ua_address": "new@example.com",
            "ua_commercial_opted_in": "2020-11-29T10:34:22"
        },
        {
            "ua_address": "ben@example.com",
            "ua_commercial_opted_out": "2020-11-29T12:45:10"
        },
        {
            "ua_address": "mary@example.com",
            "ua_email_suppression_state": "BOUNCE"
        }
    ]
}
push.device_types = ["email"]
push.notification = email(
    subject="Welcome to the 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="transactional",
    sender_name="Airship",
    sender_address="team@airship.com",
    reply_to="no-reply@airship.com",
    click_tracking=False,
    open_tracking=False,
    attachments=[
        {"id": "0e10a6b9-725c-4f6b-9af2-9ef5b31328c0"},
        {"id": "5503b5fe-ed69-4609-bef6-6fef0e6e428f"}
    ]
)
push.campaigns = campaigns(categories=["winter sale", "west coast"])

response = push.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_notification = UA::EmailNotification.new(client: airship)
email_notification.bypass_opt_in_level = false
email_notification.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>"
email_notification.message_type = 'transactional'
email_notification.plaintext_body = 'Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]'
email_notification.reply_to = 'no-reply@airship.com'
email_notification.sender_address = 'team@airship.com'
email_notification.sender_name = 'Airship'
email_notification.subject = 'Welcome to the Winter Sale!'
override = email_notification.email_override
send_it = UA::CreateAndSend.new(client: airship)
send_it.addresses = [
  {
    "ua_address": "new@example.com",
    "ua_commercial_opted_in": "2020-11-29T10:34:22"
  },
  {
    "ua_address": "ben@example.com",
    "ua_commercial_opted_in": "2020-11-29T12:45:10"
  }
]
send_it.device_types = [ "email" ]
send_it.campaigns = ["winter sale", "west coast"]
send_it.notification = email_notification.email_override
send_it.create_and_send

Example Create and Send a message for email with stored template

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

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22",
        "ua_open_tracking_opted_in": "2022-11-02T10:35:00",
        "ua_click_tracking_opted_in": "2022-11-02T10:36:00" 
      },
      {
        "ua_address" : "ben@example.com",
        "ua_commercial_opted_in": "2020-11-29T12:45:10",
        "ua_open_tracking_opted_out": "2022-11-02T10:35:00",
        "ua_click_tracking_opted_out": "2022-11-02T10:36:00"
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "subject": "Welcome to the 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": "Airship",
      "sender_address": "team@airship.com",
      "reply_to": "no-reply@airship.com",
      "click_tracking": false,
      "open_tracking": false
    }
  },
  "campaigns": {
      "categories": ["winter sale", "west coast"]
  }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

String htmlBodyString = "<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>";
String plaintextBodyString = "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]";

EmailChannel newChannel = EmailChannel.newBuilder()
        .setAddress("new@example.com")
        .setCommertialOptedIn(DateTime.parse("2020-11-29T10:34:22Z"))
        .build();

EmailChannel benChannel = EmailChannel.newBuilder()
        .setAddress("ben@example.com")
        .setTransactionalOptedIn(DateTime.parse("2020-11-29T12:45:10Z"))
        .build();

CreateAndSendAudience audience = new CreateAndSendAudience(EmailChannels.newBuilder()
        .addChannel(newChannel)
        .addChannel(benChannel)
        .build());

CreateAndSendEmailPayload createAndSendEmailPayload = CreateAndSendEmailPayload.newBuilder()
        .setSubject("Welcome to the Winter Sale! ")
        .setHtmlBody(htmlBodyString)
        .setPlaintextBody(plaintextBodyString)
        .setMessageType(MessageType.TRANSACTIONAL)
        .setSenderName("Airship")
        .setSenderAddress("team@airship.com")
        .setReplyTo("no-reply@airship.com")
        .build();

Notification notification = Notification.newBuilder()
        .addDeviceTypeOverride(DeviceType.EMAIL, createAndSendEmailPayload)
        .build();

Campaigns campaign = Campaigns.newBuilder()
        .addCategory("winter sale")
        .addCategory("west coast")
        .build();

CreateAndSendPayload payload = CreateAndSendPayload.newBuilder()
        .setAudience(audience)
        .setNotification(notification)
        .setCampaigns(campaign)
        .build();

CreateAndSendRequest request = CreateAndSendRequest.newRequest(payload);
Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, CreateAndSendPush, email, sms, mms, campaigns
)

client = BasicAuthClient(key='<app_key>', secret='<master_secret>')

# Create and Send a message for email
push = CreateAndSendPush(client)
push.audience = {
    "create_and_send": [
        {
            "ua_address": "new@example.com",
            "ua_commercial_opted_in": "2020-11-29T10:34:22"
        },
        {
            "ua_address": "ben@example.com",
            "ua_commercial_opted_out": "2020-11-29T12:45:10"
        },
        {
            "ua_address": "mary@example.com",
            "ua_email_suppression_state": "BOUNCE"
        }
    ]
}
push.device_types = ["email"]
push.notification = email(
    subject="Welcome to the 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="transactional",
    sender_name="Airship",
    sender_address="team@airship.com",
    reply_to="no-reply@airship.com",
    click_tracking=False,
    open_tracking=False,
    attachments=[
        {"id": "0e10a6b9-725c-4f6b-9af2-9ef5b31328c0"},
        {"id": "5503b5fe-ed69-4609-bef6-6fef0e6e428f"}
    ]
)
push.campaigns = campaigns(categories=["winter sale", "west coast"])

response = push.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_notification = UA::EmailNotification.new(client: airship)
email_notification.bypass_opt_in_level = false
email_notification.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>"
email_notification.message_type = 'transactional'
email_notification.plaintext_body = 'Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]'
email_notification.reply_to = 'no-reply@airship.com'
email_notification.sender_address = 'team@airship.com'
email_notification.sender_name = 'Airship'
email_notification.subject = 'Welcome to the Winter Sale!'
override = email_notification.email_override
send_it = UA::CreateAndSend.new(client: airship)
send_it.addresses = [
  {
    "ua_address": "new@example.com",
    "ua_commercial_opted_in": "2020-11-29T10:34:22"
  },
  {
    "ua_address": "ben@example.com",
    "ua_commercial_opted_in": "2020-11-29T12:45:10"
  }
]
send_it.device_types = [ "email" ]
send_it.campaigns = ["winter sale", "west coast"]
send_it.notification = email_notification.email_override
send_it.create_and_send

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

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22",
        "name": "New Person, Esq.",
        "location": "City, State"
      },
      {
        "ua_address" : "ben@example.com",
        "ua_commercial_opted_in": "2020-11-29T12:45:10",
        "name": "Ben Wyatt",
        "location": "Pawnee, IN"
      }
    ]
  },
  "device_types": [
      "email"
  ],
  "notification": {
      "email": {
        "bcc": [
            "blind@example.com"
        ],
        "message_type": "commercial",
        "reply_to": "no-reply@airship.com",
        "sender_address": "team@airship.com",
        "sender_name": "Airship",
        "template": {
            "template_id": "9335bb2a-2a45-456c-8b53-42af7898236a"
        }
      }
  }
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
    "push_ids": [
        "c0eead17-333b-4f86-8a42-9fb7be1ed627"
    ],
    "message_ids": [],
    "content_urls": []
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

EmailChannel newChannel = EmailChannel.newBuilder()
        .setAddress("new@example.com")
        .setCommertialOptedIn(DateTime.parse("2020-11-29T10:34:22Z"))
        .build();

EmailChannel benChannel = EmailChannel.newBuilder()
        .setAddress("ben@example.com")
        .setTransactionalOptedIn(DateTime.parse("2020-11-29T12:45:10Z"))
        .build();

CreateAndSendAudience audience = new CreateAndSendAudience(EmailChannels.newBuilder()
        .addChannel(newChannel)
        .addChannel(benChannel)
        .build());

EmailTemplate template = EmailTemplate.newBuilder()
        .setTemplateId("9335bb2a-2a45-456c-8b53-42af7898236a")
        .build();

CreateAndSendEmailPayload createAndSendEmailPayload = CreateAndSendEmailPayload.newBuilder()
        .setEmailTemplate(template)
        .setMessageType(MessageType.TRANSACTIONAL)
        .setSenderName("Airship")
        .setSenderAddress("team@airship.com")
        .setReplyTo("no-reply@airship.com")
        .build();

Notification notification = Notification.newBuilder()
        .addDeviceTypeOverride(DeviceType.EMAIL, createAndSendEmailPayload)
        .build();

CreateAndSendPayload payload = CreateAndSendPayload.newBuilder()
        .setAudience(audience)
        .setNotification(notification)
        .build();

CreateAndSendRequest request = CreateAndSendRequest.newRequest(payload);
Response<GenericResponse> response = client.execute(request);

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_notification = UA::EmailNotification.new(client: airship)
email_notification.message_type = 'transactional'
email_notification.reply_to = 'no-reply@airship.com'
email_notification.sender_address = 'team@airship.com'
email_notification.sender_name = 'Airship'
email_notification.template_id = "9335bb2a-2a45-456c-8b53-42af7898236a"
inline_template = email_notification.email_with_inline_template
send_it = UA::CreateAndSend.new(client: airship)
send_it.addresses = [
  {
    "ua_address": "new@example.com",
    "ua_commercial_opted_in": "2020-11-29T10:34:22"
  },
  {
    "ua_address": "ben@example.com",
    "ua_commercial_opted_in": "2020-11-29T12:45:10"
  }
]
send_it.device_types = [ "email" ]
send_it.notification = inline_template
send_it.create_and_send

Example Create and Send with bulk ID for email

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

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22",
        "ua_open_tracking_opted_in": "2022-11-02T10:35:00",
        "ua_click_tracking_opted_in": "2022-11-02T10:36:00" 
      },
      {
        "ua_address" : "ben@example.com",
        "ua_commercial_opted_in": "2020-11-29T12:45:10",
        "ua_open_tracking_opted_out": "2022-11-02T10:35:00",
        "ua_click_tracking_opted_out": "2022-11-02T10:36:00"
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "subject": "Welcome to the 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": "Airship",
      "sender_address": "team@airship.com",
      "reply_to": "no-reply@airship.com",
      "click_tracking": false,
      "open_tracking": false
    }
  },
  "campaigns": {
      "categories": ["winter sale", "west coast"]
  }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

String htmlBodyString = "<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>";
String plaintextBodyString = "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]";

EmailChannel newChannel = EmailChannel.newBuilder()
        .setAddress("new@example.com")
        .setCommertialOptedIn(DateTime.parse("2020-11-29T10:34:22Z"))
        .build();

EmailChannel benChannel = EmailChannel.newBuilder()
        .setAddress("ben@example.com")
        .setTransactionalOptedIn(DateTime.parse("2020-11-29T12:45:10Z"))
        .build();

CreateAndSendAudience audience = new CreateAndSendAudience(EmailChannels.newBuilder()
        .addChannel(newChannel)
        .addChannel(benChannel)
        .build());

CreateAndSendEmailPayload createAndSendEmailPayload = CreateAndSendEmailPayload.newBuilder()
        .setSubject("Welcome to the Winter Sale! ")
        .setHtmlBody(htmlBodyString)
        .setPlaintextBody(plaintextBodyString)
        .setMessageType(MessageType.TRANSACTIONAL)
        .setSenderName("Airship")
        .setSenderAddress("team@airship.com")
        .setReplyTo("no-reply@airship.com")
        .build();

Notification notification = Notification.newBuilder()
        .addDeviceTypeOverride(DeviceType.EMAIL, createAndSendEmailPayload)
        .build();

Campaigns campaign = Campaigns.newBuilder()
        .addCategory("winter sale")
        .addCategory("west coast")
        .build();

CreateAndSendPayload payload = CreateAndSendPayload.newBuilder()
        .setAudience(audience)
        .setNotification(notification)
        .setCampaigns(campaign)
        .build();

CreateAndSendRequest request = CreateAndSendRequest.newRequest(payload);
Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, CreateAndSendPush, email, sms, mms, campaigns
)

client = BasicAuthClient(key='<app_key>', secret='<master_secret>')

# Create and Send a message for email
push = CreateAndSendPush(client)
push.audience = {
    "create_and_send": [
        {
            "ua_address": "new@example.com",
            "ua_commercial_opted_in": "2020-11-29T10:34:22"
        },
        {
            "ua_address": "ben@example.com",
            "ua_commercial_opted_out": "2020-11-29T12:45:10"
        },
        {
            "ua_address": "mary@example.com",
            "ua_email_suppression_state": "BOUNCE"
        }
    ]
}
push.device_types = ["email"]
push.notification = email(
    subject="Welcome to the 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="transactional",
    sender_name="Airship",
    sender_address="team@airship.com",
    reply_to="no-reply@airship.com",
    click_tracking=False,
    open_tracking=False,
    attachments=[
        {"id": "0e10a6b9-725c-4f6b-9af2-9ef5b31328c0"},
        {"id": "5503b5fe-ed69-4609-bef6-6fef0e6e428f"}
    ]
)
push.campaigns = campaigns(categories=["winter sale", "west coast"])

response = push.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_notification = UA::EmailNotification.new(client: airship)
email_notification.bypass_opt_in_level = false
email_notification.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>"
email_notification.message_type = 'transactional'
email_notification.plaintext_body = 'Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]'
email_notification.reply_to = 'no-reply@airship.com'
email_notification.sender_address = 'team@airship.com'
email_notification.sender_name = 'Airship'
email_notification.subject = 'Welcome to the Winter Sale!'
override = email_notification.email_override
send_it = UA::CreateAndSend.new(client: airship)
send_it.addresses = [
  {
    "ua_address": "new@example.com",
    "ua_commercial_opted_in": "2020-11-29T10:34:22"
  },
  {
    "ua_address": "ben@example.com",
    "ua_commercial_opted_in": "2020-11-29T12:45:10"
  }
]
send_it.device_types = [ "email" ]
send_it.campaigns = ["winter sale", "west coast"]
send_it.notification = email_notification.email_override
send_it.create_and_send

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

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22",
        "name": "New Person, Esq.",
        "location": "City, State"
      },
      {
        "ua_address" : "ben@example.com",
        "ua_commercial_opted_in": "2020-11-29T12:45:10",
        "name": "Ben Wyatt",
        "location": "Pawnee, IN"
      }
    ]
  },
  "device_types": [
      "email"
  ],
  "notification": {
      "email": {
        "bcc": [
            "blind@example.com"
        ],
        "message_type": "commercial",
        "reply_to": "no-reply@airship.com",
        "sender_address": "team@airship.com",
        "sender_name": "Airship",
        "template": {
            "template_id": "9335bb2a-2a45-456c-8b53-42af7898236a"
        }
      }
  }
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
    "push_ids": [
        "c0eead17-333b-4f86-8a42-9fb7be1ed627"
    ],
    "message_ids": [],
    "content_urls": []
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

EmailChannel newChannel = EmailChannel.newBuilder()
        .setAddress("new@example.com")
        .setCommertialOptedIn(DateTime.parse("2020-11-29T10:34:22Z"))
        .build();

EmailChannel benChannel = EmailChannel.newBuilder()
        .setAddress("ben@example.com")
        .setTransactionalOptedIn(DateTime.parse("2020-11-29T12:45:10Z"))
        .build();

CreateAndSendAudience audience = new CreateAndSendAudience(EmailChannels.newBuilder()
        .addChannel(newChannel)
        .addChannel(benChannel)
        .build());

EmailTemplate template = EmailTemplate.newBuilder()
        .setTemplateId("9335bb2a-2a45-456c-8b53-42af7898236a")
        .build();

CreateAndSendEmailPayload createAndSendEmailPayload = CreateAndSendEmailPayload.newBuilder()
        .setEmailTemplate(template)
        .setMessageType(MessageType.TRANSACTIONAL)
        .setSenderName("Airship")
        .setSenderAddress("team@airship.com")
        .setReplyTo("no-reply@airship.com")
        .build();

Notification notification = Notification.newBuilder()
        .addDeviceTypeOverride(DeviceType.EMAIL, createAndSendEmailPayload)
        .build();

CreateAndSendPayload payload = CreateAndSendPayload.newBuilder()
        .setAudience(audience)
        .setNotification(notification)
        .build();

CreateAndSendRequest request = CreateAndSendRequest.newRequest(payload);
Response<GenericResponse> response = client.execute(request);

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_notification = UA::EmailNotification.new(client: airship)
email_notification.message_type = 'transactional'
email_notification.reply_to = 'no-reply@airship.com'
email_notification.sender_address = 'team@airship.com'
email_notification.sender_name = 'Airship'
email_notification.template_id = "9335bb2a-2a45-456c-8b53-42af7898236a"
inline_template = email_notification.email_with_inline_template
send_it = UA::CreateAndSend.new(client: airship)
send_it.addresses = [
  {
    "ua_address": "new@example.com",
    "ua_commercial_opted_in": "2020-11-29T10:34:22"
  },
  {
    "ua_address": "ben@example.com",
    "ua_commercial_opted_in": "2020-11-29T12:45:10"
  }
]
send_it.device_types = [ "email" ]
send_it.notification = inline_template
send_it.create_and_send

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

{
  "audience": {
    "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087"
  },
  "device_types": [
      "email"
  ],
  "notification": {
      "email": {
        "subject": "Welcome to the Winter Sale!",
        "html_body": "<h1>Seasons Greetings {{name}}</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 {{name}}! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
        "message_type": "commercial",
        "sender_name": "Airship",
        "sender_address": "team@airship.com",
        "reply_to": "no-reply@airship.com"
      }
  },
  "campaigns": {
      "categories": ["winter sale", "west coast"]
  }
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
    "push_ids": [
        "c0eead17-333b-4f86-8a42-9fb7be1ed627"
    ],
    "message_ids": [],
    "content_urls": []
}

Send messages to email addresses, MSISDNs, or Open channel addresses. Unknown identifiers are registered as new channels. This endpoint supports two audience methods:

  • create_and_send array: For smaller audiences, provide email addresses, MSISDNs, or Open channel addresses directly in the request.

  • bulk_id: For larger audiences, upload a CSV using the Create bulk send audience endpoint to obtain a bulk_id, then reference it in this request.

Existing channels that are opted_in or have a newer opted_in value in the payload receive the message but are not re-registered. You cannot update opted_in values for existing channels through this endpoint.

Note: This endpoint also accepts Channel IDs for app or web via bulk_id, but this works identically to Send message with bulk ID.

 Warning

Duplicate addresses in the create_and_send array might receive redundant notifications or fewer notifications than expected. You should remove duplicate addresses from your request before sending a Create and Send message.

Security:

Request body:

  • Content-Type: application/json

    One of
    • Email

      The payload for a Create and Send operation to email channels. When sending to email channels, device_types must be set to email.

    • Sms

      The payload for a Create and Send operation to SMS channels. When sending to SMS channels, device_types must be set to sms.

    • Mms

      The payload for a Create and Send operation that sends a multimedia payload (MMS) to SMS channels. When sending an MMS payload, device_types must be set to mms.

    • Open

      The payload for a Create and Send operation to open channels. When sending to open channels, the device_type must be set to open::<open_channel_name>.

Responses

  • 202

    Because this operation sends messages, a successful response is nearly identical to a /api/push response.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      A push response contains a list of identifiers for the notifications sent in the request.

      OBJECT PROPERTIES
      • content_urls array[string]

        An array of URLs where the push payload contains a landing page action.

      • localized_ids array[string]

        An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).

      • message_ids array[string]

        An array of message IDs, each uniquely identifying a Message Center message.

      • ok boolean

        Success.

      • operation_id string

        A unique string identifying the operation, useful for reporting and troubleshooting.

      • push_ids array[string]

        An array of push IDs, each uniquely identifying a push.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate Create and Send payload

POST /api/create-and-send/validate

Example Validate Create and Send payload

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

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22"
      },
      {
        "ua_address" : "ben@example.com",
        "ua_commercial_opted_in": "2020-11-29T12:45:10"
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "subject": "Welcome to the 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": "Airship",
      "sender_address": "team@airship.com",
      "reply_to": "no-reply@airship.com"
    }
  },
  "campaigns": {
      "categories": ["winter sale", "west coast"]
  }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

String htmlBodyString = "<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>";
String plaintextBodyString = "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]";

EmailChannel newChannel = EmailChannel.newBuilder()
        .setAddress("new@example.com")
        .setCommertialOptedIn(DateTime.parse("2020-11-29T10:34:22Z"))
        .build();

EmailChannel benChannel = EmailChannel.newBuilder()
        .setAddress("ben@example.com")
        .setTransactionalOptedIn(DateTime.parse("2020-11-29T12:45:10Z"))
        .build();

CreateAndSendAudience audience = new CreateAndSendAudience(EmailChannels.newBuilder()
        .addChannel(newChannel)
        .addChannel(benChannel)
        .build());

CreateAndSendEmailPayload createAndSendEmailPayload = CreateAndSendEmailPayload.newBuilder()
        .setSubject("Welcome to the Winter Sale! ")
        .setHtmlBody(htmlBodyString)
        .setPlaintextBody(plaintextBodyString)
        .setMessageType(MessageType.TRANSACTIONAL)
        .setSenderName("Airship")
        .setSenderAddress("team@airship.com")
        .setReplyTo("no-reply@airship.com")
        .build();

Notification notification = Notification.newBuilder()
        .addDeviceTypeOverride(DeviceType.EMAIL, createAndSendEmailPayload)
        .build();

Campaigns campaign = Campaigns.newBuilder()
        .addCategory("winter sale")
        .addCategory("west coast")
        .build();

CreateAndSendPayload payload = CreateAndSendPayload.newBuilder()
        .setAudience(audience)
        .setNotification(notification)
        .setCampaigns(campaign)
        .build();

CreateAndSendRequest request = CreateAndSendRequest.newRequest(payload)
        .setValidateOnly(true);
Response<GenericResponse> response = client.execute(request);

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_notification = UA::EmailNotification.new(client: airship)
email_notification.bypass_opt_in_level = false
email_notification.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>"
email_notification.message_type = 'transactional'
email_notification.plaintext_body = 'Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]'
email_notification.reply_to = 'no-reply@airship.com'
email_notification.sender_address = 'team@airship.com'
email_notification.sender_name = 'Airship'
email_notification.subject = 'Welcome to the Winter Sale!'
override = email_notification.email_override
send_it = UA::CreateAndSend.new(client: airship)
send_it.addresses = [
  {
    "ua_address": "new@example.com",
    "ua_commercial_opted_in": "2020-11-29T10:34:22"
  }
]
send_it.device_types = [ "email" ]
send_it.campaigns = ["winter sale", "west coast"]
send_it.notification = email_notification.email_override
send_it.validate

Validate a Create and Send payload without creating channels or sending messages. It only parses and validates your payload.

Security:

Request body:

  • Content-Type: application/json

    One of
    • Email

      The payload for a Create and Send operation to email channels. When sending to email channels, device_types must be set to email.

    • Sms

      The payload for a Create and Send operation to SMS channels. When sending to SMS channels, device_types must be set to sms.

    • Mms

      The payload for a Create and Send operation that sends a multimedia payload (MMS) to SMS channels. When sending an MMS payload, device_types must be set to mms.

    • Open

      The payload for a Create and Send operation to open channels. When sending to open channels, the device_type must be set to open::<open_channel_name>.

Responses

  • 200

    The payload was valid.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedule message with bulk ID

POST /api/schedules/bulk-send

Example schedule message with bulk ID

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

{
    "schedule": {
      "scheduled_time" : "2024-11-07T12:00:00"
    },
    "name" : "scheduled bulk send",
    "push" : {
      "audience" : {
            "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
      },
      "device_types" : [ "android" ],
      "notification" : {
            "alert" : "Hope you voted"
      },
      "campaigns": {
            "categories": ["midterms2024", "getoutthevote2024"]
      }
    }
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
    "schedule_urls": [
      "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
    ],
    "schedules": [
      {
            "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
            "schedule": {
                "scheduled_time" : "2024-11-07T12:00:00"
            }
            "push": {
                "audience": {
                  "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
                },
                "device_types" : [ "open::rcs" ],
                "notification" : {
                  "alert" : "Welcome to the winter sale!!"
                },
                "campaigns": {
                  "categories": ["winter sale", "west coast"]
                }
            }
      }
    ],
    "push_ids": ["8cf8b2a5-7655-40c2-a500-ff498e60453e"]
}

Schedule a message to existing channels using a bulk_id. Inactive channels are dropped. Before calling this endpoint, obtain a bulk_id from the Create bulk send audience endpoint.

Security:

Request body:

A Send a message with bulk ID payload.

  • Content-Type: application/json

    Scheduled bulk send object

    A scheduled bulk send object wraps a bulk send object. It describes when the notification should be sent, an optional name for the notification, and the object defining the notification itself, which must be a bulk send object or Templated message content. The scheduled date must be within 60 days.

Responses

  • 202

    The push notification has been accepted for processing. The response contains push_id, message_id, and/or content_url arrays based on the type of push.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      A push response contains a list of identifiers for the notifications sent in the request.

      OBJECT PROPERTIES
      • content_urls array[string]

        An array of URLs where the push payload contains a landing page action.

      • localized_ids array[string]

        An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).

      • message_ids array[string]

        An array of message IDs, each uniquely identifying a Message Center message.

      • ok boolean

        Success.

      • operation_id string

        A unique string identifying the operation, useful for reporting and troubleshooting.

      • push_ids array[string]

        An array of push IDs, each uniquely identifying a push.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 429

    Too many requests hit the API too quickly. For example, if we are not ready to create a channel for this payload; e.g., it is rate limited. You should wait before retrying the channel creation.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedule a Create and Send message

POST /api/schedules/create-and-send

Example scheduled Create and Send message

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

{
  "schedule": {
    "scheduled_time" : "2020-11-11T12:00:00"
  },
  "name" : "scheduled winter sale email",
  "push" : {
    "audience": {
      "create_and_send" : [
        {
          "ua_address": "new@example.com",
          "ua_commercial_opted_in": "2020-11-29T10:34:22"
        },
        {
          "ua_address" : "ben@example.com",
          "ua_commercial_opted_in": "2020-11-29T12:45:10"
        }
      ]
    },
    "device_types" : [ "email" ],
    "notification" : {
      "email": {
        "subject": "Welcome to the 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": "Airship",
        "sender_address": "team@airship.com",
        "reply_to": "no-reply@airship.com"
      }
    },
    "campaigns": {
        "categories": ["winter sale", "west coast"]
    }
  }
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok": true,
  "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
  "push_ids": [
      "8cf8b2a5-7655-40c2-a500-ff498e60453e"
  ],
  "schedule_urls": [
      "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
  ],
  "schedules": [
      {
        "push": {
            "audience": {
              "create_and_send": [
                  {
                    "ua_address": "new@example.com",
                    "ua_commercial_opted_in": "2020-11-29T10:34:22"
                  },
                  {
                    "ua_address": "ben@example.com",
                    "ua_commercial_opted_in": "2020-11-29T12:45:10"
                  }
              ]
            },
            "device_types": [
              "email"
            ],
            "notification": {
              "campaigns": {
                  "categories": [
                    "winter sale",
                    "west coast"
                  ]
              },
              "email": {
                  "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>",
                  "message_type": "commercial",
                  "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
                  "reply_to": "no-reply@airship.com",
                  "sender_address": "team@airship.com",
                  "sender_name": "Airship",
                  "subject": "Welcome to the Winter Sale! "
              }
            }
        },
        "schedule": {
            "scheduled_time": "2020-11-11T12:00:00"
        },
        "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
      }
  ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

String htmlBodyString = "<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>";
String plaintextBodyString = "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]";

EmailChannel newChannel = EmailChannel.newBuilder()
        .setAddress("new@example.com")
        .setCommertialOptedIn(DateTime.parse("2020-11-29T10:34:22Z"))
        .build();

EmailChannel benChannel = EmailChannel.newBuilder()
        .setAddress("ben@example.com")
        .setTransactionalOptedIn(DateTime.parse("2020-11-29T12:45:10Z"))
        .build();

CreateAndSendAudience audience = new CreateAndSendAudience(EmailChannels.newBuilder()
        .addChannel(newChannel)
        .addChannel(benChannel)
        .build());

CreateAndSendEmailPayload createAndSendEmailPayload = CreateAndSendEmailPayload.newBuilder()
        .setSubject("Welcome to the Winter Sale! ")
        .setHtmlBody(htmlBodyString)
        .setPlaintextBody(plaintextBodyString)
        .setMessageType(MessageType.TRANSACTIONAL)
        .setSenderName("Airship")
        .setSenderAddress("team@airship.com")
        .setReplyTo("no-reply@airship.com")
        .build();

Notification notification = Notification.newBuilder()
        .addDeviceTypeOverride(DeviceType.EMAIL, createAndSendEmailPayload)
        .build();

Campaigns campaign = Campaigns.newBuilder()
        .addCategory("winter sale")
        .addCategory("west coast")
        .build();

CreateAndSendPayload payload = CreateAndSendPayload.newBuilder()
        .setAudience(audience)
        .setNotification(notification)
        .setCampaigns(campaign)
        .build();

CreateAndSendSchedulePayload schedulePayload = CreateAndSendSchedulePayload.newBuilder()
        .setPayload(payload)
        .setScheduleTime(DateTime.parse("2020-11-11T12:00:00"))
        .setName("scheduled winter sale email")
        .build();

CreateAndSendScheduleRequest scheduleRequest = CreateAndSendScheduleRequest.newRequest(schedulePayload)
Response<GenericResponse> response = client.execute(scheduleRequest);

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_notification = UA::EmailNotification.new(client: airship)
email_notification.bypass_opt_in_level = false
email_notification.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>"
email_notification.message_type = 'transactional'
email_notification.plaintext_body = 'Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]'
email_notification.reply_to = 'no-reply@airship.com'
email_notification.sender_address = 'team@airship.com'
email_notification.sender_name = 'Airship'
email_notification.subject = 'Welcome to the Winter Sale!'
override = email_notification.email_override
send_it = UA::CreateAndSend.new(client: airship)
send_it.addresses = [
  {
    "ua_address": "new@example.com",
    "ua_commercial_opted_in": "2020-10-28T10:34:22"
  }
]
send_it.device_types = [ "email" ]
send_it.campaigns = ["winter sale", "west coast"]
send_it.notification = email_notification.email_override
send_it.name = "scheduled winter sale email"
send_it.scheduled_time = "2020-12-08T11:06:00"
send_it.schedule

Example scheduled Create and Send with bulk ID

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

{
  "schedule": {
    "scheduled_time" : "2020-11-11T12:00:00"
  },
  "name" : "scheduled winter sale email",
  "push" : {
    "audience": {
      "create_and_send" : [
        {
          "ua_address": "new@example.com",
          "ua_commercial_opted_in": "2020-11-29T10:34:22"
        },
        {
          "ua_address" : "ben@example.com",
          "ua_commercial_opted_in": "2020-11-29T12:45:10"
        }
      ]
    },
    "device_types" : [ "email" ],
    "notification" : {
      "email": {
        "subject": "Welcome to the 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": "Airship",
        "sender_address": "team@airship.com",
        "reply_to": "no-reply@airship.com"
      }
    },
    "campaigns": {
        "categories": ["winter sale", "west coast"]
    }
  }
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok": true,
  "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
  "push_ids": [
      "8cf8b2a5-7655-40c2-a500-ff498e60453e"
  ],
  "schedule_urls": [
      "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
  ],
  "schedules": [
      {
        "push": {
            "audience": {
              "create_and_send": [
                  {
                    "ua_address": "new@example.com",
                    "ua_commercial_opted_in": "2020-11-29T10:34:22"
                  },
                  {
                    "ua_address": "ben@example.com",
                    "ua_commercial_opted_in": "2020-11-29T12:45:10"
                  }
              ]
            },
            "device_types": [
              "email"
            ],
            "notification": {
              "campaigns": {
                  "categories": [
                    "winter sale",
                    "west coast"
                  ]
              },
              "email": {
                  "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>",
                  "message_type": "commercial",
                  "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
                  "reply_to": "no-reply@airship.com",
                  "sender_address": "team@airship.com",
                  "sender_name": "Airship",
                  "subject": "Welcome to the Winter Sale! "
              }
            }
        },
        "schedule": {
            "scheduled_time": "2020-11-11T12:00:00"
        },
        "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
      }
  ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

String htmlBodyString = "<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>";
String plaintextBodyString = "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]";

EmailChannel newChannel = EmailChannel.newBuilder()
        .setAddress("new@example.com")
        .setCommertialOptedIn(DateTime.parse("2020-11-29T10:34:22Z"))
        .build();

EmailChannel benChannel = EmailChannel.newBuilder()
        .setAddress("ben@example.com")
        .setTransactionalOptedIn(DateTime.parse("2020-11-29T12:45:10Z"))
        .build();

CreateAndSendAudience audience = new CreateAndSendAudience(EmailChannels.newBuilder()
        .addChannel(newChannel)
        .addChannel(benChannel)
        .build());

CreateAndSendEmailPayload createAndSendEmailPayload = CreateAndSendEmailPayload.newBuilder()
        .setSubject("Welcome to the Winter Sale! ")
        .setHtmlBody(htmlBodyString)
        .setPlaintextBody(plaintextBodyString)
        .setMessageType(MessageType.TRANSACTIONAL)
        .setSenderName("Airship")
        .setSenderAddress("team@airship.com")
        .setReplyTo("no-reply@airship.com")
        .build();

Notification notification = Notification.newBuilder()
        .addDeviceTypeOverride(DeviceType.EMAIL, createAndSendEmailPayload)
        .build();

Campaigns campaign = Campaigns.newBuilder()
        .addCategory("winter sale")
        .addCategory("west coast")
        .build();

CreateAndSendPayload payload = CreateAndSendPayload.newBuilder()
        .setAudience(audience)
        .setNotification(notification)
        .setCampaigns(campaign)
        .build();

CreateAndSendSchedulePayload schedulePayload = CreateAndSendSchedulePayload.newBuilder()
        .setPayload(payload)
        .setScheduleTime(DateTime.parse("2020-11-11T12:00:00"))
        .setName("scheduled winter sale email")
        .build();

CreateAndSendScheduleRequest scheduleRequest = CreateAndSendScheduleRequest.newRequest(schedulePayload)
Response<GenericResponse> response = client.execute(scheduleRequest);

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_notification = UA::EmailNotification.new(client: airship)
email_notification.bypass_opt_in_level = false
email_notification.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>"
email_notification.message_type = 'transactional'
email_notification.plaintext_body = 'Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]'
email_notification.reply_to = 'no-reply@airship.com'
email_notification.sender_address = 'team@airship.com'
email_notification.sender_name = 'Airship'
email_notification.subject = 'Welcome to the Winter Sale!'
override = email_notification.email_override
send_it = UA::CreateAndSend.new(client: airship)
send_it.addresses = [
  {
    "ua_address": "new@example.com",
    "ua_commercial_opted_in": "2020-10-28T10:34:22"
  }
]
send_it.device_types = [ "email" ]
send_it.campaigns = ["winter sale", "west coast"]
send_it.notification = email_notification.email_override
send_it.name = "scheduled winter sale email"
send_it.scheduled_time = "2020-12-08T11:06:00"
send_it.schedule

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

{
  "schedule": {
    "scheduled_time": "2020-11-11T12:00:00"
  },
  "name": "scheduled winter sale email",
  "push": {
    "audience": {
      "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087"
    },
    "device_types": [
        "email"
    ],
    "notification": {
        "email": {
          "subject": "Welcome to the Winter Sale!",
          "html_body": "<h1>Seasons Greetings {{name}}</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 {{name}}! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
          "message_type": "commercial",
          "sender_name": "Airship",
          "sender_address": "team@airship.com",
          "reply_to": "no-reply@airship.com"
        }
    },
    "campaigns": {
        "categories": ["winter sale", "west coast"]
    }
  }
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok": true,
  "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
  "schedule_urls": [
      "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
  ]
}

Schedule a Create and Send message. Unknown identifiers are registered as new channels. This endpoint supports two audience methods:

  • create_and_send array: For smaller audiences, provide email addresses, MSISDNs, or Open channel addresses directly in the request.

  • bulk_id: For larger audiences, upload a CSV using the Create bulk send audience endpoint to obtain a bulk_id, then reference it in this request.

Existing channels that are opted_in or have a newer opted_in value in the payload receive the message but are not re-registered. You cannot update opted_in values for existing channels through this endpoint.

Note: This endpoint also accepts Channel IDs for app or web via bulk_id, but this works identically to Schedule message with bulk ID.

 Warning

Duplicate addresses in the create_and_send array might receive redundant notifications or fewer notifications than expected. You should remove duplicate addresses from your request before sending a Create and Send message.

Security:

Request body:

The request is much like other Create and Send operations, with a leading schedule object. The standard Create and Send payload sits inside a push object.

  • Content-Type: application/json

    OBJECT PROPERTIES
    • name string

      A name for the schedule.

    • push objectREQUIRED
      One of
      • Email

        The payload for a Create and Send operation to email channels. When sending to email channels, device_types must be set to email.

      • Sms

        The payload for a Create and Send operation to SMS channels. When sending to SMS channels, device_types must be set to sms.

      • Mms

        The payload for a Create and Send operation that sends a multimedia payload (MMS) to SMS channels. When sending an MMS payload, device_types must be set to mms.

      • Open

        The payload for a Create and Send operation to open channels. When sending to open channels, the device_type must be set to open::<open_channel_name>.

    • schedule objectREQUIRED

      Similar to other schedule objects. However, Create and Send requests support scheduled_time only.

      OBJECT PROPERTIES
      • scheduled_time stringREQUIRED

        The date-time when you want to perform your Create and Send operation. Users will receive the notification as soon as possible after the specified date-time.

Responses

  • 202

    Because this operation sends messages, a successful response is nearly identical to a /api/push response.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      A push response contains a list of identifiers for the notifications sent in the request.

      OBJECT PROPERTIES
      • content_urls array[string]

        An array of URLs where the push payload contains a landing page action.

      • localized_ids array[string]

        An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).

      • message_ids array[string]

        An array of message IDs, each uniquely identifying a Message Center message.

      • ok boolean

        Success.

      • operation_id string

        A unique string identifying the operation, useful for reporting and troubleshooting.

      • push_ids array[string]

        An array of push IDs, each uniquely identifying a push.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    Returned when the request is too large to be processed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Reports

The Airship Reports APIs are available in only certain account plans. Please contact Support  or your Account Manager if you are unable to use them for an app key that you believe is on an appropriate plan.

Activity log report

GET /api/reports/activity/details

Example (response truncated)

GET /api/reports/activity/details?start=2020-06-02T20:47:20&end=2023-01-31T20:47:20 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/json

{
    "app_key": "Wz9d8TlSWk0lZTAwzHA2qc",
    "start": "2020-06-02T20:47:20",
    "end": "2023-01-31T20:47:20",
    "limit": 10,
    "next_page": "https://go.urbanairship.com/api/reports/activity/details...",
    "activities": [
        {
            "push_id": "ecb8eaf0-0430-4dfa-93d8-c3149f479d96",
            "timestamp": "2023-01-31 20:47:20",
            "type": "GROUP",
            "experiment": true,
            "details": {
                "interaction": {
                    "web": {
                        "clicks": 20,
                        "sessions": 13
                    },
                    "app": {
                        "influenced": 13,
                        "direct": 12,
                        "indirect": 10,
                        "rich_read": 5
                    }
                },
                "delivery": {
                    "web": {
                        "total": 13
                    },
                    "app": {
                        "silent": 125,
                        "alerting": 13,
                        "rich": 5,
                        "in_app": {
                            "impressions": 10,
                            "impressions_opted_in": 5,
                            "impressions_opted_out": 5
                        }
                    }
                }
            }
        }
    ]
}

Returns the activity log data, including non-unicast pushes. The series begins with the earliest time given in which the group of pushes were sent.

Security:

Query parameters:

  • start stringREQUIRED
    A date-time for start of report.
  • end stringREQUIRED
    A date-time for end of report.
  • limit integer
    Number of results to return per request. Defaults to 100. Results paginate if requesting narrow precision over a long period of time.

    Min: 1

Responses

  • 200

    Returned on success.

    Response body:

    • Content-Type: application/json;

      The activity log data.

      OBJECT PROPERTIES
      • activities array[object]

        An array of activity log data.

      • app_key string

        The app key for the application.

      • end string

        The end date-time for the report.

      • limit integer

        The optional limit for the number of entries to return per request. Defaults to 100.

      • next_page string

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

      • start string

        The start date-time for the report.

Devices report

GET /api/reports/devices

Example

GET /api/reports/devices?date=2020-08-28T00:00:00 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "total_unique_devices": 13186,
    "date_closed": "2020-08-28 00:00:00",
    "date_computed": "2020-08-29 13:30:45",
    "counts": {
        "ios": {
            "unique_devices": 231,
            "opted_in": 142,
            "opted_out": 89,
            "uninstalled": 2096
        },
        "android": {
            "unique_devices": 11795,
            "opted_in": 226,
            "opted_out": 11569,
            "uninstalled": 1069
        },
        "amazon": {
            "unique_devices": 29,
            "opted_in": 22,
            "opted_out": 7,
            "uninstalled": 9
        },
        "sms": {
            "unique_devices": 26,
            "opted_in": 23,
            "opted_out": 3,
            "uninstalled": 17
        }
    }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

DevicesReportRequest request = DevicesReportRequest.newRequest()
        .setDate(DateTime.parse("2020-08-28T10:34:22Z"));

Response<DevicesReportResponse> response = client.execute(request);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, DevicesReport
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
date = datetime(2020, 8, 28)
response = DevicesReport(airship=client).get(date=date)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

d = UA::DevicesReport.new(client: airship)
devices = d.get(date: '2020/08/28')

Get an app’s opted-in and installed device counts by device type.

Security:

Query parameters:

  • date stringREQUIRED
    All device events counted occurred before this date-time.

Responses

  • 200

    Returned on success, with the JSON representation of the device counts in the body of the response.

    Response body:

    • Content-Type: application/json;

      The response body for the device report.

      OBJECT PROPERTIES
      • counts object

        The counts for each device type.

        OBJECT PROPERTIES
        • amazon object

          The count object for a device type.

          OBJECT PROPERTIES
          • opted_in integer

            Opted in to receiving push notifications.

          • opted_out integer

            Opted out of receiving push notifications.

          • uninstalled integer

            Devices for which Reports has seen an uninstall event.

          • unique_devices integer

            Devices considered by Airship Reports to have the app installed.

        • android object

          The count object for a device type.

          OBJECT PROPERTIES
          • opted_in integer

            Opted in to receiving push notifications.

          • opted_out integer

            Opted out of receiving push notifications.

          • uninstalled integer

            Devices for which Reports has seen an uninstall event.

          • unique_devices integer

            Devices considered by Airship Reports to have the app installed.

        • ios object

          The count object for a device type.

          OBJECT PROPERTIES
          • opted_in integer

            Opted in to receiving push notifications.

          • opted_out integer

            Opted out of receiving push notifications.

          • uninstalled integer

            Devices for which Reports has seen an uninstall event.

          • unique_devices integer

            Devices considered by Airship Reports to have the app installed.

      • date_closed string

        All device events counted occurred before this date-time.

      • date_computed string

        The date-time the device event data was tallied and stored.

      • total_unique_devices integer

        Sum of the unique devices for every device type.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Custom Events detail listing

GET /api/reports/events

Example

GET /api/reports/events?start=2020-08-01T10:00:00.000Z&end=2020-08-15T20:00:00.000Z&precision=MONTHLY&page_size=20 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "total_value": 2,
    "total_count": 709,
    "next_page": "https://go.urbanairship.com/api/reports/events?start=2020-08-01T10:00:00.000Z&end=2020-08-15T20:00:00.000Z&precision=MONTHLY&page_size=20&page=2",
    "events": [
        {
            "name": "banner_image",
            "conversion": "indirect",
            "location": "ua_mcrap",
            "count": 1,
            "value": 1
        },
        {
            "name": "bounce",
            "conversion": "direct",
            "location": "custom",
            "count": 23,
            "value": 0
        },
        {
            "name": "button-click-Do it ",
            "conversion": "direct",
            "location": "in_app_message",
            "count": 1,
            "value": 0
        },
        {
            "name": "button-click-Get Notifications",
            "conversion": "unattributed",
            "location": "in_app_message",
            "count": 3,
            "value": 0
        },
        {
            "name": "button-click-RATE NOW",
            "conversion": "direct",
            "location": "in_app_message",
            "count": 1,
            "value": 0
        },
        {
            "name": "button-click-Rate the app.",
            "conversion": "direct",
            "location": "in_app_message",
            "count": 1,
            "value": 0
        }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

DateTime startDate = DateTime.parse("2022-01-01T10:00:00");
DateTime endDate =  DateTime.parse("2023-01-01T10:00:00");

CustomEventsDetailsListingRequest customEventsDetailsListingRequest = CustomEventsDetailsListingRequest
        .newRequest(startDate, endDate)
        .setPageSize(10)
        .setPrecision(Precision.MONTHLY)
        .setPage(2);

Response<CustomEventsDetailsListingResponse> response = client.execute(customEventsDetailsListingRequest);
List<CustomEventsDetailResponse> customEventsDetailResponses = response.getBody().get().getEvents().get();

from datetime import datetime
from urbanairship import (
    BasicAuthClient, CustomEventsList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
start_date = datetime(2020, 8, 1)
end_date = datetime(2020, 8, 15)
for event in CustomEventsList(airship=client, start_date=start_date, end_date=end_date, precision='MONTHLY'):
    print(event)

Get a summary of Custom Event counts and values, by Custom Event, within the specified time period.

Security:

Query parameters:

  • start stringREQUIRED
    A date-time for start of report.
  • end stringREQUIRED
    A date-time for end of report.
  • precision string
    Granularity of results to return. Defaults to DAILY.

    Possible values: HOURLY, DAILY, MONTHLY

    Default: DAILY

  • page integer
    Identifies the desired page number. Defaults to 1. If page is given a negative or out of bounds value, the default value will be used.
  • page_size integer
    Specifies how many results to return per page. Has a default value of 25 and a maximum value of 100.

Responses

  • 200

    Returned on success, with the JSON representation of the events in the body of the response.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      The response body for Custom Events detail listing.

      OBJECT PROPERTIES
      • events array[object]

        An array of Custom Events and its details.

      • next_page string

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

      • ok boolean

        Success.

      • prev_page string

        Link to the previous page, if available.

      • total_count integer

        Sum of all the count fields in the above array.

      • total_value integer

        Sum of all the value fields in the above array.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Custom Events per group summary

GET /api/reports/events/summary/pergroup/{group_id}

Example request

GET /api/reports/events/summary/pergroup/8bd09679-f672-4783-a31a-d4e516f9e99c HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

Response with Group ID parameter

GET /api/reports/events/summary/pergroup/8bd09679-f672-4783-a31a-d4e516f9e99c HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "group_id": "8bd09679-f672-4783-a31a-d4e516f9e99c",
    "events": [
        {
            "name": "custom_event_name",
            "location": "custom",
            "conversion": "direct",
            "count": 4,
            "value": 16.4
        },
        ...
    ],
    "total_count": 12,
    "total_value": 321.2,
    "next_page": "https://go.urbanairship.com/api/reports/events/summary/pergroup/...",
    "prev_page": "https://go.urbanairship.com/api/reports/events/summary/pergroup/..."
}

Get a summary of Custom Event counts and values associated with the provided Push ID. Includes all Custom Events from the time of the push up to current time.

Security:

Query parameters:

  • variant integer
    Variant number (0 to 25), or -1 for control events.
  • page integer
    Identifies the desired page number. Defaults to 1. If page is given a negative or out of bounds value, the default value will be used.
  • page_size integer
    Specifies how many results to return per page. Has a default value of 25 and a maximum value of 100.

Path parameters:

  • group_id stringREQUIRED
    The UUID for the requested group push ID.

Responses

  • 200

    Returned on success, with the JSON representation of the events in the body of the response.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      The response body for Custom Events per group.

      All of
      • OBJECT PROPERTIES
        • group_id string

          The UUID representing a specific group push.

      • The response body for Custom Events per push or per group.

        OBJECT PROPERTIES
        • events array[object]

          An array of Custom Events and its details.

        • next_page string

          There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results. Will only be present if there are successive pages.

        • ok boolean

          Success.

        • prev_page string

          Link to the previous page, if available. Will only be present if there are preceding pages.

        • total_count integer

          Sum of all the count fields in the above array.

        • total_value integer

          Sum of all the value fields in the above array.

        • variant integer

          Variant number (0 to 25) or -1 for control events.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Custom Events per push summary

GET /api/reports/events/summary/perpush/{push_id}

Example request

GET /api/reports/events/summary/perpush/8bd09679-f672-4783-a31a-d4e516f9e99c HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

Response with Push ID parameter

GET /api/reports/events/summary/perpush/8bd09679-f672-4783-a31a-d4e516f9e99c HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "push_id": "8bd09679-f672-4783-a31a-d4e516f9e99c",
    "events": [
        {
            "name": "custom_event_name",
            "location": "custom",
            "conversion": "direct",
            "count": 4,
            "value": 16.4
        },
        ...
    ],
    "total_count": 12,
    "total_value": 321.2,
    "next_page": "https://go.urbanairship.com/api/reports/events/summary/perpush/...",
    "prev_page": "https://go.urbanairship.com/api/reports/events/summary/perpush/..."
}

Response with variant parameter

GET /api/reports/events/summary/perpush/8bd09679-f672-4783-a31a-d4e516f9e99c HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "push_id": "8bd09679-f672-4783-a31a-d4e516f9e99c",
    "events": [
        {
            "name": "custom_event_name",
            "location": "custom",
            "conversion": "direct",
            "count": 4,
            "value": 16.4
        },
        ...
    ],
    "total_count": 12,
    "total_value": 321.2,
    "next_page": "https://go.urbanairship.com/api/reports/events/summary/perpush/...",
    "prev_page": "https://go.urbanairship.com/api/reports/events/summary/perpush/..."
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "push_id": "8bd09679-f672-4783-a31a-d4e516f9e99c",
    "variant": 1,
    "events": [
        {
            "name": "custom_event_name",
            "location": "custom",
            "conversion": "direct",
            "count": 4,
            "value": 16.4
        },
        ...
    ],
    "total_count": 12,
    "total_value": 321.2,
    "next_page": "https://go.urbanairship.com/api/reports/events/summary/perpush/...",
    "prev_page": "https://go.urbanairship.com/api/reports/events/summary/perpush/..."
}

Get a summary of Custom Event counts and values associated with the provided Push ID. Includes all Custom Events from the time of the push up to current time.

Security:

Query parameters:

  • variant integer
    Variant number (0 to 25), or -1 for control events.
  • page integer
    Identifies the desired page number. Defaults to 1. If page is given a negative or out of bounds value, the default value will be used.
  • page_size integer
    Specifies how many results to return per page. Has a default value of 25 and a maximum value of 100.

Path parameters:

  • push_id stringREQUIRED
    The UUID for the requested push.

Responses

  • 200

    Returned on success, with the JSON representation of the events in the body of the response.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3

      The response body for Custom Events per push.

      All of
      • OBJECT PROPERTIES
        • push_id string

          The UUID representing a specific push.

      • The response body for Custom Events per push or per group.

        OBJECT PROPERTIES
        • events array[object]

          An array of Custom Events and its details.

        • next_page string

          There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results. Will only be present if there are successive pages.

        • ok boolean

          Success.

        • prev_page string

          Link to the previous page, if available. Will only be present if there are preceding pages.

        • total_count integer

          Sum of all the count fields in the above array.

        • total_value integer

          Sum of all the value fields in the above array.

        • variant integer

          Variant number (0 to 25) or -1 for control events.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Experiment variant report

GET /api/reports/experiment/detail/{push_id}/{variant_id}

Example

GET /api/reports/experiment/detail/b43ae1b2-3ff6-4c02-adb2-79deac0bbb19/2 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "app_key": "some_app_key",
    "experiment_id": "a7806815-6483-4cb9-9d74-bc3b4f3dc1b8",
    "push_id": "b43ae1b2-3ff6-4c02-adb2-79deac0bbb19",
    "created": "2020-02-25 23:03:12",
    "variant": 2,
    "variant_name": "thing_two",
    "sends": 64,
    "direct_responses": 3,
    "influenced_responses": 1,
    "platforms": {
        "android": {
            "direct_responses": 0,
            "influenced_responses": 0,
            "sends": 22
        },
        "ios": {
            "direct_responses": 0,
            "influenced_responses": 1,
            "sends": 36
        },
        "amazon": {
            "direct_responses": 0,
            "influenced_responses": 0,
            "sends": 0
        },
        "web": {
            "direct_responses": 3,
            "indirect_responses": 0,
            "sends": 6
        }
    }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ExperimentVariantReportRequest experimentVariantReportRequest = ExperimentVariantReportRequest.newRequest("b43ae1b2-3ff6-4c02-adb2-79deac0bbb19", "1");
Response<ExperimentVariantReportResponse> response = client.execute(experimentVariantReportRequest);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, ExperimentReport
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

experiment_report = ExperimentReport(airship=client)
variant_report = experiment_report.get_variant(
  push_id="b43ae1b2-3ff6-4c02-adb2-79deac0bbb19",
  variant=2
)
print(variant_report)

Returns statistics and metadata about a specific variant in an experiment (A/B Test).

Security:

Path parameters:

  • push_id stringREQUIRED
    The push_id of the requested experiment.
  • variant_id integerREQUIRED
    The specific variant you want to return results for.

    Min: 1

    Max: 26

Responses

  • 200

    Returned on success.

    Response body:

    • Content-Type: application/json;

      Type: object

Experiment overview report

GET /api/reports/experiment/overview/{push_id}

Example

GET /api/reports/experiment/overview/b43ae1b2-3ff6-4c02-adb2-79deac0bbb19 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "app_key": "some_app_key",
   "experiment_id": "a7806815-6483-4cb9-9d74-bc3b4f3dc1b8",
   "push_id": "b43ae1b2-3ff6-4c02-adb2-79deac0bbb19",
   "created": "2020-02-25 23:03:12",
   "sends": 532,
   "direct_responses": 50,
   "influenced_responses": 60,
   "web_clicks": 6,
   "web_sessions": 8,
   "variants": [
      {
         "id" : 0,
         "name": "call to action",
         "audience_pct": 45.0,
         "sends": 238,
         "direct_responses": 32,
         "direct_response_pct": 13.44,
         "indirect_responses": 0,
         "indirect_response_pct": 0.0
      },
      {
         "id" : 1,
         "name": "gentle reminder",
         "audience_pct": 45.0,
         "sends": 251,
         "direct_responses": 20,
         "direct_response_pct": 7.97,
         "indirect_responses": 4,
         "indirect_response_pct": 1.59
      }
   ],
   "control": {
     "audience_pct": 10.0,
     "sends": 50,
     "responses": 1,
     "response_rate_pct": 2.0
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ExperimentOverviewReportRequest experimentOverviewReportRequest = ExperimentOverviewReportRequest.newRequest("4b83d756-cc64-45e0-b140-3f5ec04170fb");
Response<ExperimentOverviewReportResponse> response = client.execute(experimentOverviewReportRequest);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, ExperimentReport
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

experiment_report = ExperimentReport(airship=client)
overview_report = experiment_report.get_overview(
                    push_id="b43ae1b2-3ff6-4c02-adb2-79deac0bbb19"
                  )
print(overview_report)

Returns statistics and metadata about an experiment (A/B Test).

Security:

Path parameters:

  • push_id stringREQUIRED
    The push_id of the requested experiment.

Responses

  • 200

    Returned on success.

    Response body:

    • Content-Type: application/json;

      Type: object

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

App opens report

GET /api/reports/opens

Example

GET /api/reports/opens?start=2020-08-01T10:00&end=2020-08-15T20:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "opens": [
        {
            "date": "2020-08-01 00:00:00",
            "ios": 350,
            "android": 250
        }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PlatformStatsRequest request = PlatformStatsRequest.newRequest(PlatformStatsRequestType.APP_OPENS)
        .setStart(DateTime.parse("2020-08-01T10:34:22Z"))
        .setEnd(DateTime.parse("2020-08-15T10:34:22Z"))
        .setPrecision(Precision.MONTHLY);

Response<PlatformStatsResponse> response = client.execute(request);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, AppOpensList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
start_date = datetime(2020, 8, 1)
end_date = datetime(2020, 8, 15)
for open in AppOpensList(airship=client, start_date=start_date, end_date=end_date, precision='DAILY'):
    print(open)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

listing = UA::AppOpensList.new(
    client: airship,
    start_date: '2020-08-01',
    end_date: '2020-08-15',
    precision: 'MONTHLY')
listing.each do |app_opens|
    puts(app_opens)
end

Get the number of users who have opened your app within the specified time period.

Security:

Query parameters:

  • start stringREQUIRED
    A date-time for start of report.
  • end stringREQUIRED
    A date-time for end of report.
  • precision stringREQUIRED
    Granularity of results to return. Defaults to DAILY.

    Possible values: HOURLY, DAILY, MONTHLY

    Default: DAILY

Responses

  • 200

    Returned on success, with the JSON representation of the app opens in the body of the response.

    Response body:

    • Content-Type: application/json;

      The response body for app opens report.

      OBJECT PROPERTIES
      • next_page string

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

      • opens array[object]

        An array of App opens objects.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Opt-in report

GET /api/reports/optins

Example

GET /api/reports/optins?start=2020-08-01T10:00&end=2020-08-15T20:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "optins": [
      {
         "android": 50,
         "date": "2020-05-01 00:00:00",
         "ios": 500
      }
   ],
   "next_page": "https://go.urbanairship.com/api/reports/..."
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PlatformStatsRequest request = PlatformStatsRequest.newRequest(PlatformStatsRequestType.OPT_INS)
        .setStart(DateTime.parse("2020-08-01T10:34:22Z"))
        .setEnd(DateTime.parse("2020-08-15T10:34:22Z"))
        .setPrecision(Precision.MONTHLY);

Response<PlatformStatsResponse> response = client.execute(request);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, OptInList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
start_date = datetime(2020, 8, 1)
end_date = datetime(2020, 8, 15)
for opt_in in OptInList(airship=client, start_date=start_date, end_date=end_date, precision='DAILY'):
    print(opt_in)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

listing = UA::OptInList.new(
    client: airship,
    start_date: '2020-08-01',
    end_date: '2020-08-15',
    precision: 'MONTHLY')
listing.each do |opt_ins|
    puts(opt_ins)
end

Get the number of opted-in Push users who access the app within the specified time period.

Security:

Query parameters:

  • start stringREQUIRED
    A date-time for start of report.
  • end stringREQUIRED
    A date-time for end of report.
  • precision stringREQUIRED
    Granularity of results to return. Defaults to DAILY.

    Possible values: HOURLY, DAILY, MONTHLY

    Default: DAILY

Responses

  • 200

    Returned on success, with the JSON representation of the opt-ins in the body of the response.

    Response body:

    • Content-Type: application/json;

      The response body for opt-in report.

      OBJECT PROPERTIES
      • next_page string

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

      • optins array[object]

        An array of OptIn objects.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Opt-out report

GET /api/reports/optouts

Example

GET /api/reports/optouts?start=2020-08-01T10:00&end=2020-08-15T20:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "optouts": [
      {
         "android": 5,
         "date": "2020-05-01 00:00:00",
         "ios": 25
      }
   ],
   "next_page": "https://go.urbanairship.com/api/reports/..."
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PlatformStatsRequest request = PlatformStatsRequest.newRequest(PlatformStatsRequestType.OPT_OUTS)
        .setStart(DateTime.parse("2020-08-01T10:34:22Z"))
        .setEnd(DateTime.parse("2020-08-15T10:34:22Z"))
        .setPrecision(Precision.MONTHLY);

Response<PlatformStatsResponse> response = client.execute(request);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, OptOutList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
start_date = datetime(2020, 8, 1)
end_date = datetime(2020, 8, 15)
for opt_out in OptOutList(airship=client, start_date=start_date, end_date=end_date, precision='DAILY'):
    print(opt_out)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

listing = UA::OptOutList.new(
    client: airship,
    start_date: '2020-08-01',
    end_date: '2020-08-15',
    precision: 'MONTHLY')
listing.each do |opt_outs|
    puts(opt_outs)
end

Get the number of opted-out Push users who access the app within the specified time period.

Security:

Query parameters:

  • start stringREQUIRED
    A date-time for start of report.
  • end stringREQUIRED
    A date-time for end of report.
  • precision stringREQUIRED
    Granularity of results to return. Defaults to DAILY.

    Possible values: HOURLY, DAILY, MONTHLY

    Default: DAILY

Responses

  • 200

    Returned on success, with the JSON representation of the opt-outs in the body of the response.

    Response body:

    • Content-Type: application/json;

      The response body for opt-out report.

      OBJECT PROPERTIES
      • next_page string

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

      • optouts array[object]

        An array of OptOut objects.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Per group push detail report

GET /api/reports/pergroup/detail/{group_id}

Example

GET /api/reports/pergroup/detail/57ef3728-79dc-46b1-a6b9-20081e561f97 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/json

{
    "app_key": "some_app_key",
    "group_id": "57ef3728-79dc-46b1-a6b9-20081e561f97",
    "created": "2023-07-25 23:03:12",
    "rich_deletions": 0,
    "rich_responses": 0,
    "rich_sends": 0,
    "sends": 103,
    "alerting_sends": 103,
    "silent_sends": 0,
    "direct_responses": 0,
    "influenced_responses": 3,
    "platforms": {
        "android": {
            "direct_responses": 0,
            "influenced_responses": 0,
            "sends": 22
        },
        "ios": {
            "direct_responses": 0,
            "influenced_responses": 1,
            "sends": 36
        },
        "amazon": {
            "direct_responses": 0,
            "influenced_responses": 1,
            "sends": 5
        },
        "web": {
            "direct_responses": 0,
            "influenced_responses": 1,
            "sends": 40
        }
    }
}

Returns statistics and other information for a given group push message.

Security:

Path parameters:

  • group_id stringREQUIRED
    The group_id of the requested report.

Responses

  • 200

    Returned on success.

    Response body:

    • Content-Type: application/json;

      The response body for detail reporting per push group.

      All of
      • OBJECT PROPERTIES
        • group_id string

          The UUID representing a specific group push.

      • The response body for detail reporting per push or per group.

        OBJECT PROPERTIES
        • alerting_sends integer

          The number of alerting sends.

        • app_key string

          The app key for the given push.

        • created string

          The date-time when the push was created.

        • direct_responses integer

          The number of direct responses.

        • influenced_responses integer

          The total number of influenced responses.

        • platforms object
          OBJECT PROPERTIES
          • amazon object
            OBJECT PROPERTIES
            • direct_responses integer

              The number of direct responses (clicks/app opens) to the notification on this platform as measured by the SDK.

            • influenced_responses integer

              The number of opens or clicks resulting from your notification (directly or indirectly).

            • sends integer

              The total number of audience members accounted on the specified platform.

          • android object
            OBJECT PROPERTIES
            • direct_responses integer

              The number of direct responses (clicks/app opens) to the notification on this platform as measured by the SDK.

            • influenced_responses integer

              The number of opens or clicks resulting from your notification (directly or indirectly).

            • sends integer

              The total number of audience members accounted on the specified platform.

          • ios object
            OBJECT PROPERTIES
            • direct_responses integer

              The number of direct responses (clicks/app opens) to the notification on this platform as measured by the SDK.

            • influenced_responses integer

              The number of opens or clicks resulting from your notification (directly or indirectly).

            • sends integer

              The total number of audience members accounted on the specified platform.

          • web object
            OBJECT PROPERTIES
            • direct_responses integer

              The number of direct responses (clicks/app opens) to the notification on this platform as measured by the SDK.

            • influenced_responses integer

              The number of opens or clicks resulting from your notification (directly or indirectly).

            • sends integer

              The total number of audience members accounted on the specified platform.

        • rich_deletions integer

          The number of rich deletions.

        • rich_responses integer

          The number of rich responses.

        • rich_sends integer

          The number of rich sends.

        • sends integer

          The number of pushes sent.

        • silent_sends integer

          The number of silent sends.

Per group push time series report

GET /api/reports/pergroup/series/{group_id}

Example (response truncated to 2 items)

GET /api/reports/pergroup/series/57ef3728-79dc-46b1-a6b9-20081e561f97 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/json

{
    "app_key": "some_app_key",
    "group_id": "57ef3728-79dc-46b1-a6b9-20081e561f97",
    "start": "2023-07-25 23:00:00",
    "end": "2023-07-26 11:00:00",
    "precision": "HOURLY",
    "counts": [
        {
            "push_platforms": {
                "all": {
                    "direct_responses": 0,
                    "influenced_responses": 1,
                    "sends": 58
                },
                "android": {
                    "direct_responses": 0,
                    "influenced_responses": 0,
                    "sends": 22
                },
                "ios": {
                    "direct_responses": 0,
                    "influenced_responses": 1,
                    "sends": 36
                }
            },
            "rich_push_platforms": {
                "all": {
                    "responses": 0,
                    "sends": 0
                }
            },
            "time": "2023-07-25 23:00:00"
        },
        {
            "push_platforms": {
                "all": {
                    "direct_responses": 0,
                    "influenced_responses": 0,
                    "sends": 0
                },
                "android": {
                    "direct_responses": 0,
                    "influenced_responses": 0,
                    "sends": 0
                },
                "ios": {
                    "direct_responses": 0,
                    "influenced_responses": 0,
                    "sends": 0
                }
            },
            "rich_push_platforms": {
                "all": {
                    "responses": 0,
                    "sends": 0
                }
            },
            "time": "2023-07-26 00:00:00"
        }
    ]
}

Returns the default time series data (hourly precision for 12 hours) for a given group push message. The series begins with the hour in which the push was sent. By specifying the precision without providing a time range, the default number of periods at each precision returned are as follows: Hourly: 12, Daily: 7, Monthly: 3. Results paginate if requesting narrow precision over a long period of time.

Security:

Query parameters:

  • precision string
    The precision of the report. Defaults to HOURLY.

    Possible values: HOURLY, DAILY, MONTHLY

  • start string
    A date-time for start of report.
  • end string
    A date-time for end of report.

Path parameters:

  • group_id stringREQUIRED
    The group_id of the requested report.

Responses

  • 200

    Returned on success.

    Response body:

    • Content-Type: application/json;

      The response body for per push time series report.

      All of
      • OBJECT PROPERTIES
        • group_id string

          The UUID representing a specific group push.

      • OBJECT PROPERTIES
        • app_key string

          The app key for the application.

        • end string

          The end date-time for the report.

        • precision string

          The precision of the report.

          Possible values: HOURLY, DAILY, MONTHLY

        • start string

          The start date-time for the report.

      • OBJECT PROPERTIES
        • counts array[object]

          Array of total count objects, each representing counts within the given date-time range and precision.

Per push detail report

GET /api/reports/perpush/detail/{push_id}

Example

GET /api/reports/perpush/detail/57ef3728-79dc-46b1-a6b9-20081e561f97 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/json

{
    "app_key": "some_app_key",
    "push_id": "57ef3728-79dc-46b1-a6b9-20081e561f97",
    "created": "2023-07-25 23:03:12",
    "rich_deletions": 0,
    "rich_responses": 0,
    "rich_sends": 0,
    "sends": 103,
    "alerting_sends": 103,
    "silent_sends": 0,
    "direct_responses": 0,
    "influenced_responses": 3,
    "platforms": {
        "android": {
            "direct_responses": 0,
            "influenced_responses": 0,
            "sends": 22
        },
        "ios": {
            "direct_responses": 0,
            "influenced_responses": 1,
            "sends": 36
        },
        "amazon": {
            "direct_responses": 0,
            "influenced_responses": 1,
            "sends": 5
        },
        "web": {
            "direct_responses": 0,
            "influenced_responses": 1,
            "sends": 40
        }
    }
}

Returns statistics and other information for a given push message.

Security:

Path parameters:

  • push_id stringREQUIRED
    The push_id of the requested report.

Responses

  • 200

    Returned on success.

    Response body:

    • Content-Type: application/json;

      The response body for detail reporting per push.

      All of
      • OBJECT PROPERTIES
        • push_id string

          The UUID representing a specific push.

      • The response body for detail reporting per push or per group.

        OBJECT PROPERTIES
        • alerting_sends integer

          The number of alerting sends.

        • app_key string

          The app key for the given push.

        • created string

          The date-time when the push was created.

        • direct_responses integer

          The number of direct responses.

        • influenced_responses integer

          The total number of influenced responses.

        • platforms object
          OBJECT PROPERTIES
          • amazon object
            OBJECT PROPERTIES
            • direct_responses integer

              The number of direct responses (clicks/app opens) to the notification on this platform as measured by the SDK.

            • influenced_responses integer

              The number of opens or clicks resulting from your notification (directly or indirectly).

            • sends integer

              The total number of audience members accounted on the specified platform.

          • android object
            OBJECT PROPERTIES
            • direct_responses integer

              The number of direct responses (clicks/app opens) to the notification on this platform as measured by the SDK.

            • influenced_responses integer

              The number of opens or clicks resulting from your notification (directly or indirectly).

            • sends integer

              The total number of audience members accounted on the specified platform.

          • ios object
            OBJECT PROPERTIES
            • direct_responses integer

              The number of direct responses (clicks/app opens) to the notification on this platform as measured by the SDK.

            • influenced_responses integer

              The number of opens or clicks resulting from your notification (directly or indirectly).

            • sends integer

              The total number of audience members accounted on the specified platform.

          • web object
            OBJECT PROPERTIES
            • direct_responses integer

              The number of direct responses (clicks/app opens) to the notification on this platform as measured by the SDK.

            • influenced_responses integer

              The number of opens or clicks resulting from your notification (directly or indirectly).

            • sends integer

              The total number of audience members accounted on the specified platform.

        • rich_deletions integer

          The number of rich deletions.

        • rich_responses integer

          The number of rich responses.

        • rich_sends integer

          The number of rich sends.

        • sends integer

          The number of pushes sent.

        • silent_sends integer

          The number of silent sends.

Push body per push

GET /api/reports/perpush/pushbody/{push_id}

Example

GET /api/reports/perpush/pushbody/57ef3728-79dc-46b1-a6b9-20081e561f97 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/json

{
    "push_body": "<Base64-encoded string>"
}

Returns the push body for the given push message.

Security:

Path parameters:

  • push_id stringREQUIRED
    The push_id of the requested push body.

Responses

  • 200

    Returned on success.

    Response body:

    • Content-Type: application/json;

      Type: object

Per push time series report

GET /api/reports/perpush/series/{push_id}

Example (response truncated to 2 items)

GET /api/reports/perpush/series/57ef3728-79dc-46b1-a6b9-20081e561f97 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/json

{
    "app_key": "some_app_key",
    "push_id": "57ef3728-79dc-46b1-a6b9-20081e561f97",
    "start": "2023-07-25 23:00:00",
    "end": "2023-07-26 11:00:00",
    "precision": "HOURLY",
    "counts": [
        {
            "push_platforms": {
                "all": {
                    "direct_responses": 0,
                    "influenced_responses": 1,
                    "sends": 58
                },
                "android": {
                    "direct_responses": 0,
                    "influenced_responses": 0,
                    "sends": 22
                },
                "ios": {
                    "direct_responses": 0,
                    "influenced_responses": 1,
                    "sends": 36
                }
            },
            "rich_push_platforms": {
                "all": {
                    "responses": 0,
                    "sends": 0
                }
            },
            "time": "2023-07-25 23:00:00"
        },
        {
            "push_platforms": {
                "all": {
                    "direct_responses": 0,
                    "influenced_responses": 0,
                    "sends": 0
                },
                "android": {
                    "direct_responses": 0,
                    "influenced_responses": 0,
                    "sends": 0
                },
                "ios": {
                    "direct_responses": 0,
                    "influenced_responses": 0,
                    "sends": 0
                }
            },
            "rich_push_platforms": {
                "all": {
                    "responses": 0,
                    "sends": 0
                }
            },
            "time": "2023-07-26 00:00:00"
        }
    ]
}

Returns the default time series data (hourly precision for 12 hours) for a given push message. The series begins with the hour in which the push was sent. By specifying the precision without providing a time range, the default number of periods at each precision returned are as follows: Hourly: 12, Daily: 7, Monthly: 3. Results paginate if requesting narrow precision over a long period of time.

Security:

Query parameters:

  • precision string
    The precision of the report. Defaults to HOURLY.

    Possible values: HOURLY, DAILY, MONTHLY

  • start string
    A date-time for start of report.
  • end string
    A date-time for end of report.

Path parameters:

  • push_id stringREQUIRED
    The push_id of the requested report.

Responses

  • 200

    Returned on success.

    Response body:

    • Content-Type: application/json;

      The response body for per push time series report.

      All of
      • OBJECT PROPERTIES
        • push_id string

          The UUID representing a specific push.

      • OBJECT PROPERTIES
        • app_key string

          The app key for the application.

        • end string

          The end date-time for the report.

        • precision string

          The precision of the report.

          Possible values: HOURLY, DAILY, MONTHLY

        • start string

          The start date-time for the report.

      • OBJECT PROPERTIES
        • counts array[object]

          Array of total count objects, each representing counts within the given date-time range and precision.

Response report

GET /api/reports/responses

Example

GET /api/reports/responses?start=2020-05-01T10:00&end=2020-05-30T10:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "next_page": "https://go.urbanairship.com/api/reports/...",
   "responses": [
      {
         "android": {
            "direct": 25,
            "influenced": 118
         },
         "date": "2020-05-01 00:00:00",
         "ios": {
            "direct": 16,
            "influenced": 87
         }
      }
   ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ResponseReportRequest request = ResponseReportRequest
        .newRequest(DateTime.parse("2020-05-01T10:34:22Z"),
                    DateTime.parse("2020-05-30T10:34:22Z"),
                    Precision.MONTHLY);

Response<ResponseReportResponse> response = client.execute(request);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, ResponseReportList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
start_date = datetime(2020, 5, 1)
end_date = datetime(2020, 5, 30)
for response in ResponseReportList(airship=client, start_date=start_date, end_date=end_date, precision='DAILY'):
    print(response)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

listing = UA::ResponseReportList.new(
    client: airship,
    start_date: '2020-05-01',
    end_date: '2020-05-30',
    precision: 'MONTHLY'
)
listing.each do |resp|
    puts(resp)
end

Get the number of direct and influenced opens of your app.

Security:

Query parameters:

  • start stringREQUIRED
    A date-time for start of report.
  • end stringREQUIRED
    A date-time for end of report.
  • precision string
    Granularity of results to return. Defaults to DAILY.

    Possible values: HOURLY, DAILY, MONTHLY

    Default: DAILY

Responses

  • 200

    Returned on success, with the JSON representation of the responses in the body of the response.

    Response body:

    • Content-Type: application/json;

      The response body for response report.

      OBJECT PROPERTIES
      • next_page string

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

      • responses array[object]

        An array of response objects.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Response listing

GET /api/reports/responses/list

Example

GET /api/reports/responses/list?start=2020-08-01T10:00&end=2020-08-15T10:00&limit=20 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "next_page": "https://go.urbanairship.com/api/reports/responses/list?start=2020-08-01+10%...",
    "pushes": [
        {
            "push_uuid": "f4db3752-a982-4a2b-994e-7b5fd1c7f02f",
            "push_time": "2020-08-15 02:12:22",
            "push_type": "UNICAST_PUSH",
            "group_id": "4e768dc7-4ebc-4206-890a-60b5627763a7",
            "direct_responses": 0,
            "sends": 1,
            "open_channels_sends": {
                "platforms": []
            }
        },
        {
            "push_uuid": "5a4ade58-fbd3-43a2-ac3c-e834ee190151",
            "push_time": "2020-08-14 19:58:15",
            "push_type": "UNICAST_PUSH",
            "group_id": "c5664e1f-106e-4616-9820-7d9ecce8a3f3",
            "direct_responses": 1,
            "sends": 2,
            "open_channels_sends": {
                "platforms": []
            }
        }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PushListingRequest request = PushListingRequest.newRequest()
        .setStart(DateTime.parse("2020-08-01T10:34:22Z"))
        .setEnd(DateTime.parse("2020-08-15T10:34:22Z"))
        .setLimit(20);

Response<PushListingResponse> response = client.execute(request);

// Get the first item in an array of push info responses. You can use all of the getters
// listed in the "Individual Push Response Statistics" section.
PushInfoResponse pushInfo = response.getBody().get().getPushInfoList().get().get(0);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, ResponseList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
start_date = datetime(2020, 8, 1)
end_date = datetime(2020, 8, 15)
for response in ResponseList(airship=client, start_date=start_date, end_date=end_date):
    print(response)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

response_list = UA::ResponseList.new(
    client: airship,
    start_date: '2020-08-01',
    end_date: '2020-08-30',
    limit: 20,
    push_id_start: 'start_id'
)
response_list.each do |resp|
    puts(resp)
end

Get a listing of all pushes, plus basic response information, for a given time period. Start and end date times are required parameters. The time defaults to 00:00 UTC if not specified.

 Note

If you don’t specify a start and end time, the system assumes 00:00 UTC, which will provide results through the previous day.

Use timestamps to get results for a specific time period. If only using the date, set it in the future to ensure you will see the most recent listing.

Security:

Query parameters:

  • start stringREQUIRED
    A date-time for start of report.
  • end stringREQUIRED
    A date-time for end of report.
  • limit integer
    Number of results to return at one time (for pagination).

    Min: 1

Responses

  • 200

    Returned on success, with the JSON representation of the listing in the body of the response.

    Response body:

    • Content-Type: application/json;

      The response body for response listing.

      OBJECT PROPERTIES
      • next_page string

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

      • pushes array[object]

        An array of all pushes and its basic response information.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Individual push response statistics

GET /api/reports/responses/{push_id}

Example

GET /api/reports/responses/90f28bc6-6c9b-4c99-b970-973afc266e08 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "push_uuid": "90f28bc6-6c9b-4c99-b970-973afc266e08",
   "push_time": "2020-02-25 23:03:12",
   "push_type": "UNICAST_PUSH",
   "sends": 167,
   "direct_responses": 15,
   "open_channels_sends": {
      "platforms": [
        {
           "id": "PLATFORM_NAME",
           "sends": 22
        },
        {
           "id": "ANOTHER_PLATFORM",
           "sends": 145
        }
      ]
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PushInfoRequest request = PushInfoRequest.newRequest("90f28bc6-6c9b-4c99-b970-973afc266e08");

Response<PushInfoResponse> response = client.execute(request);
PushInfoResponse pushInfo = response.getBody().get();

// Number of sends
int sends = pushInfo.getSends();
// Number of direct responses to the push
int directResponses = pushInfo.getDirectResponses();
// When the push was sent
DateTime date = pushInfo.getPushTime();
// The push type - can be one of BROADCAST_PUSH, SCHEDULED_PUSH, TAG_PUSH, UNICAST_PUSH
PushInfoResponse.PushType type = pushInfo.getPushType();
// The unique identifier for the push
UUID pushId = pushInfo.getPushId();

from datetime import datetime
from urbanairship import (
    BasicAuthClient, IndividualResponseStats
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
push_id = '90f28bc6-6c9b-4c99-b970-973afc266e08'
response = IndividualResponseStats(airship=client).get(push_id)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

d = UA::IndividualResponseStats.new(client: airship)
statistics = d.get(push_id: '90f28bc6-6c9b-4c99-b970-973afc266e08')

Returns detailed reports information about a specific push notification. Use the push_id, which is the identifier returned by the API that represents a specific push message delivery.

Security:

Path parameters:

  • push_id stringREQUIRED
    The UUID for the requested push.

Responses

  • 200

    Returned on success, with the JSON representation of the push statistics in the body of the response.

    Response body:

    • Content-Type: application/json;

      The response body for an individual push response statistics report.

      OBJECT PROPERTIES
      • direct_responses integer

        The number of native-platform direct responses to the notification measured by the SDK.

      • open_channels_sends object

        Contains an array of the number of send counts per open platform. If there were no open channels sends associated with the push ID, an empty result will be returned.

        OBJECT PROPERTIES
        • platforms array[object]

          An array of objects indicating the total sends by open platform.

      • push_time string

        The date-time indicating the time that the push was initially sent.

      • push_type string

        This string describes the push operation, which is often comparable to the audience selection.

        Possible values: BROADCAST_PUSH, TAG_PUSH, SCHEDULED_PUSH, SEGMENTS_PUSH, UNICAST_PUSH

      • push_uuid string

        The UUID for the requested push.

      • sends integer

        The number of pushes sent to native mobile platforms, e.g., iOS. Exclusive of open_channel_sends, which are broken out under open_channel_sends.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Push report

GET /api/reports/sends

Example

GET /api/reports/sends?start=2020-05-01T10:00&end=2020-05-30T20:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "sends": [
      {
         "android": 50,
         "date": "2020-05-01 00:00:00",
         "ios": 500
      }
   ],
   "next_page": "https://go.urbanairship.com/api/reports/..."
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PlatformStatsRequest request = PlatformStatsRequest.newRequest(PlatformStatsRequestType.SENDS)
        .setStart(DateTime.parse("2020-05-01T10:34:22Z"))
        .setEnd(DateTime.parse("2020-05-30T10:34:22Z"))
        .setPrecision(Precision.MONTHLY);

Response<PlatformStatsResponse> response = client.execute(request);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, PushList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
start_date = datetime(2020, 5, 1)
end_date = datetime(2020, 5, 30)
precision = 'MONTHLY'
listing = PushList(airship=client, start_date=start_date, end_date=end_date, precision=precision)

for resp in listing:
  print(resp.date, resp.android, resp.ios)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

listing = UA::PushList.new(
    client: airship,
    start_date: '2020/05/01',
    end_date: '2020/05/30',
    precision: 'MONTHLY'
)
listing.each do |resp|
    puts(resp)
end

Get the number of pushes you have sent within a specified time period.

Security:

Query parameters:

  • start stringREQUIRED
    A date-time for start of report.
  • end stringREQUIRED
    A date-time for end of report.
  • precision stringREQUIRED
    Granularity of results to return. Defaults to DAILY.

    Possible values: HOURLY, DAILY, MONTHLY

    Default: DAILY

Responses

  • 200

    Returned on success, with the JSON representation of the sends in the body of the response.

    Response body:

    • Content-Type: application/json;

      The response body for push report.

      OBJECT PROPERTIES
      • next_page string

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

      • sends array[object]

        An array of send objects.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Time in app report

GET /api/reports/timeinapp

Example

GET /api/reports/timeinapp?start=2020-05-01T10:00&end=2020-05-15T20:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "timeinapp": [
      {
         "android": 50,
         "date": "2020-05-01 00:00:00",
         "ios": 500
      }
   ],
   "next_page": "https://go.urbanairship.com/api/reports/..."
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PlatformStatsRequest request = PlatformStatsRequest.newRequest(PlatformStatsRequestType.TIME_IN_APP)
        .setStart(DateTime.parse("2020-05-01T10:34:22Z"))
        .setEnd(DateTime.parse("2020-05-15T10:34:22Z"))
        .setPrecision(Precision.MONTHLY);

Response<PlatformStatsResponse> response = client.execute(request);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, TimeInAppList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
start_date = datetime(2020, 5, 1)
end_date = datetime(2020, 5, 15)
precision = 'MONTHLY'
listing = TimeInAppList(airship=client, start_date=start_date, end_date=end_date, precision=precision)
for resp in listing:
    print(resp.date, resp.android, resp.ios)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

listing = UA::TimeInAppList.new(
    client: airship,
    start_date: '2020-05-01',
    end_date: '2020-05-30',
    precision: 'MONTHLY')
listing.each do |time_in_app|
    puts(time_in_app)
end

Get the average amount of time users have spent in your app within the specified time period.

Security:

Query parameters:

  • start stringREQUIRED
    A date-time for start of report.
  • end stringREQUIRED
    A date-time for end of report.
  • precision stringREQUIRED
    Granularity of results to return. Defaults to DAILY.

    Possible values: HOURLY, DAILY, MONTHLY

    Default: DAILY

Responses

  • 200

    Returned on success, with the JSON representation of the time in app in the body of the response.

    Response body:

    • Content-Type: application/json;

      The response body for time in app report.

      OBJECT PROPERTIES
      • next_page string

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.

      • sends array[object]

        An array of TimeInApp objects.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Web response report

GET /api/reports/web/interaction

Example

GET /api/reports/web/interaction?app_key=ZGIwZTY3YjEtZTRiMi00ZG&start=2020-05-01T10:00&end=2020-05-03T20:00&precision=HOURLY HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "app_key": "ZGIwZTY3YjEtZTRiMi00ZG",
   "end": "2020-05-03 00:00:00",
   "precision": "HOURLY",
   "start": "2020-05-01 00:00:00",
   "total_counts": [
      {"counts": {"clicks": 36, "sessions": 55 }, "date": "2020-05-01 10:00:00"},
      {"counts": {"clicks": 50, "sessions": 79 }, "date": "2020-05-01 11:00:00"},
      {"..."},
      {"..."},
      {"counts": {"clicks": 67, "sessions": 75 }, "date": "2020-05-03 20:00:00"}
  ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

WebResponseReportRequest webResponseReportRequest = WebResponseReportRequest.newRequest("<app key>", DateTime.parse("2020-08-01T10:34:22Z"));
Response<WebResponseReportResponse> response = client.execute(webResponseReportRequest);

from datetime import datetime
from urbanairship import (
    BasicAuthClient, WebResponseReport
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
start_date = datetime(2020, 5, 1)
end_date = datetime(2020, 5, 3)
for web_response in WebResponseReport(airship=client, start_date=start_date, end_date=end_date, precision='DAILY'):
    print(web_response)

Get the web interaction data for the given app key. Accepts a required start time and optional end time and precision parameters.

 Note

If you don’t specify an end time, the system assumes 00:00 UTC, which will provide results through the previous day.

Security:

Query parameters:

  • app_key stringREQUIRED
    The app key for your web project.
  • start stringREQUIRED
    A date-time for start of report.
  • end string
    A date-time for end of report.
  • precision string
    The precision of the report. Defaults to HOURLY.

    Possible values: HOURLY, DAILY, MONTHLY

Responses

  • 200

    Returned on success, with the JSON representation of the web data in the body of the response.

    Response body:

    • Content-Type: application/json;

      The response body for web response report.

      All of
      • OBJECT PROPERTIES
        • app_key string

          The app key for the application.

        • end string

          The end date-time for the report.

        • precision string

          The precision of the report.

          Possible values: HOURLY, DAILY, MONTHLY

        • start string

          The start date-time for the report.

      • OBJECT PROPERTIES
        • total_counts array[object]

          Array of total count objects, each representing counts within the given date-time range and precision.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Contacts

A Contact is any user in your project. Contacts are identified as either an Anonymous Contact or a Named User. Airship can set targeting data on these identifiers, which are also used to map devices and channels to a specific user.

Look up Contact ID by Channel ID

GET /api/contacts/lookup/channel/{channel_id}

Example get Contact ID from a Channel ID

GET /api/contacts/lookup/channel/164c3a13-9c75-4ea9-be2c-1bed2c97f9c3 HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "contact_id": "7c24ebdd-ec06-47d4-9a56-ced8611f5b52",
   "is_anonymous": false
}

Looks up a Contact ID for the given Channel ID.

Security:

Path parameters:

  • channel_id stringREQUIRED
    The Channel ID for which to retrieve the associated Contact ID.

Responses

  • 200

    The request was accepted.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • contact_id stringREQUIRED

        The resolved Contact ID.

      • is_anonymous booleanREQUIRED

        Specifies whether the Contact is anonymous or not.

      • ok booleanREQUIRED

        Set to true when status code is 200.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Look up Contact ID by Named User ID

GET /api/contacts/lookup/named_user/{named_user_id}

Example get Contact ID from a Named User ID

GET /api/contacts/lookup/named_user/90ae282f-f56e-4037-8174-482ef7e3e5f4 HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "contact_id": "7c24ebdd-ec06-47d4-9a56-ced8611f5b52"
}

Looks up a Contact ID for the given Named User ID.

Security:

Path parameters:

  • named_user_id stringREQUIRED
    The URL-encoded Named User ID for which to retrieve the associated Contact ID.

Responses

  • 200

    The request was accepted.

    Response body:

    • Content-Type: application/json

      The Contact ID in the response will be based on these precedence rules:

      • From the Named User if it exists
      • From the channel if it is associated to an Anonymous Contact
      • From the payload if provided
      • Randomly generated

      OBJECT PROPERTIES
      • contact_id stringREQUIRED

        The resolved Contact ID.

      • ok booleanREQUIRED

        Set to true when status code is 200.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Data Privacy Laws Compliance

Uninstall channels

POST /api/channels/uninstall

Example

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

[
   {
      "channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881",
      "device_type": "ios"
   },
   {
      "channel_id": "13863b3c-f860-4bbf-a9f1-4d785379b8a2",
      "device_type": "android"
   }
]

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

 Set<ChannelUninstallDevice> channels = ImmutableSet.of(
       new ChannelUninstallDevice("00f74677-4616-4958-bd91-30e949814d2c", ChannelUninstallDeviceType.IOS),
       new ChannelUninstallDevice("007f7156-9b82-4cb6-a2f9-e2c8e7fce13d", ChannelUninstallDeviceType.ANDROID)
 );

 ChannelUninstallPayload payload = ChannelUninstallPayload.newBuilder()
       .setChannels(channels)
       .build();

 ChannelUninstallRequest request = ChannelUninstallRequest.newRequest(payload);
 Response<ChannelUninstallResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, ChannelUninstall
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

channel_uninstall = ChannelUninstall(client)
channel = {
    "channel_id": 'b8f9b663-0a3b-cf45-587a-be880946e881',
    "device_type": "ios"
}

channel_uninstall.uninstall(channel)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

cu = UA::ChannelUninstall.new(client: airship)

chans = [{"channel_id" => "b8f9b663-0a3b-cf45-587a-be880946e881",
          "device_type" => "ios"},
         {"channel_id" => "13863b3c-f860-4bbf-a9f1-4d785379b8a2",
          "device_type" => "android"}]

cu.uninstall(channels: chans)

Uninstalls a channel, removing it and all accompanying analytic data (including Performance Analytics) from Airship systems in accordance with data privacy law compliance.

Uninstallation is handled automatically by the Airship SDK and push systems. If a user decides to opt in to communications again (either by using your app or other user preferences), they will create a new channel and a new set of analytic data. The value of a Channel ID may be the same as before however none of the associated metadata will persist when a user opts in again. A new Channel ID will be created if the user clears their browser’s cookies and data, deletes and reinstalls the app, etc.

See Individual Data Privacy Rights Under Data Privacy Laws for more information about data privacy law compliance.

 Note

Channel uninstallation, like channel creation, is an asynchronous operation and may take some time to complete.

Security:

Request body:

  • Content-Type: application/json

    array<object>

    Min items: 1, Max items: 1000

    ARRAY ITEM

    • Specifies the Channel ID and device type you want to uninstall.

      OBJECT PROPERTIES
      • channel_id stringREQUIRED
        The Channel ID.
      • device_type stringREQUIRED
        The device type of the channel.

        Possible values: ios, android, amazon, web, open

Responses

  • 202

    Returns OK for success.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named Users uninstall

POST /api/named_users/uninstall

Example delete all users and their associated channels

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

{
   "named_user_id": ["user-id-1234","user-id-5678"]
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserUninstallRequest namedUserUninstallRequest = NamedUserUninstallRequest
        .newUninstallRequest(ImmutableList.of("user-id-1234","user-id-5678"));

Response<GenericResponse> response = client.execute(namedUserUninstallRequest);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

response = NamedUser.uninstall(
    client=client,
    named_users=["user-id-1234", "user-id-5678"]
  )

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

named_user_uninstall = UA::NamedUserUninstaller.new(client: airship)
named_user_uninstall.named_user_ids = ['user-id-1234']
named_user_uninstall.uninstall

Disassociate and delete all channels associated with the named_user_id(s) and also delete the named_user_id(s). This call removes all channels associated with a Named User from Airship systems in compliance with data privacy laws.

Uninstalling channels also removes accompanying analytic data (including Performance Analytics) from the system.

See Individual Data Privacy Rights Under Data Privacy Laws for more information about data privacy law compliance.

 Note

Channel uninstallation, like channel creation, is an asynchronous operation and may take some time to complete.

Security:

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • named_user_id array[string]REQUIRED

      Array of strings representing the named_user_id(s) you wish to be uninstalled. Must have between 1 to 100 items in the array with a 128 character/byte maximum per item.

Responses

  • 200

    All channels have been deleted and disassociated from the Named User.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Subscription Lists

Subscription lists listing

GET /api/subscription_lists

Example

GET /api/subscription_lists HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : true,
   "subscription_lists": [
       {
           "list_id": "example_listId-1",
           "name": "A nice readable name 1",
           "scopes": ["email"],
           "messaging_type": "transactional",
           "default_opted_in": false
       },
       {
           "list_id": "example_listId-2",
           "name": "A nice readable name 2",
           "description": "A very nice description for you.",
           "scopes": ["app", "web"],
           "default_opted_in": true
       }
   ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SubscriptionListListingRequest subscriptionListListingRequest = SubscriptionListListingRequest.newRequest();
Response<SubscriptionListListingResponse> response = client.execute(subscriptionListListingRequest);

from urbanairship import (
    BasicAuthClient, SubscriptionList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# List all subscription lists
subscription_lists = SubscriptionList(client).list()

Provides a list of subscription lists IDs that are associated with this app key.

Security:

Responses

  • 200

    Returns OK for success, with the list of subscription lists for the app.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        Success.

      • subscription_lists array

        An array of subscription list result objects.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named User subscription lists listing

GET /api/subscription_lists/named_users/{named_user_id}

Example

GET /api/subscription_lists/named_users/4cbd1c1c-42e1-4606-bc93-9b707bcedcbc HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : true,
   "subscription_lists": [
      {
         "list_ids": ["example_listId-2", "example_listId-4"],
         "scope": "app"
      },
      {
         "list_ids": ["example_listId-2"],
         "scope": "web"
      }
   ],
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserSubscriptionListsListingRequest namedUserSubscriptionListsListingRequest = NamedUserSubscriptionListsListingRequest.newRequest("4cbd1c1c-42e1-4606-bc93-9b707bcedcbc");
Response<NamedUserSubscriptionListsListingResponse> response = client.execute(namedUserSubscriptionListsListingRequest);

from urbanairship import (
    BasicAuthClient, SubscriptionList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Get subscription lists for a named user
named_user_lists = SubscriptionList(client).list_by_named_user('4cbd1c1c-42e1-4606-bc93-9b707bcedcbc')

Provides the subscription lists that are associated with a given Named User.

Security:

Path parameters:

  • named_user_id stringREQUIRED
    The Named User being looked up.

Responses

  • 200

    Returns OK for success, with the Named User subscription list IDs.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • ok boolean

        Success.

      • subscription_lists array

  • 304

    An If-Modified-Since request header exists and the result is unchanged.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Tag Lists

Retrieve lists

GET /api/tag-lists

Example

GET /api/tag-lists HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Tag: lists
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : true,
  "lists" : [
    {
      "name" : "ua_tags_foo",
      "description" : "",
      "extra" : { "key": "value" },
      "add":{
        "tag-group-name": [
          "tag-value"
        ],
        "tag-group-name2": [
          "tag-value2a",
          "tag-value2b"
        ]
      },
      "remove": {
        "tag-group-name3": [
          "tag-value"
        ]
      },
      "set": {
        "tag-group-name4": [
          "tag-value"
        ]
      },
      "created" : "2013-08-08T20:41:06",
      "last_updated" : "2014-05-01T18:00:27",
      "channel_count" : 0,
      "mutation_success_count": 1000,
      "mutation_error_count": 10,
      "error_path":  "https://go.urbanairship.com/api/tag-lists/users_a/errors",
      "status" : "ready"
    },
    {
      "..." : "..."
    }
  ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TagListListingRequest tagListListingRequest = TagListListingRequest.newRequest();
Response<TagListListingResponse> response = client.execute(tagListListingRequest);

from urbanairship import (
    BasicAuthClient, TagList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# List all tag lists
response = TagList.list(airship=client)
tag_lists = response.json()

require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: 'app_key', secret: 'master_secret')

tag_list = UA::TagList.new(client: airship)
list_response = tag_list.list

Retrieve information about all tag lists. This call returns a list of metadata that will not contain the actual lists of users.

 Note

The tag list content will return the data provided in the tag list creation operation. Although add, remove, and set are optional, one or more must be present.

Security:

Responses

  • 200

    Lists metadata retrieved successfully.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OBJECT PROPERTIES
      • lists array

        An array of list objects.

      • ok boolean

        Success.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create a tag list

POST /api/tag-lists

Example

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

{
  "name":"ua_tags_foobar",
  "description":"Description of the file being uploaded",
  "extra":{
      "key":"value",
      "another":"etc..."
  },
  "add":{
      "tag-group-name":[
        "tag-value"
      ],
      "tag-group-name2":[
        "tag-value2a",
        "tag-value2b"
      ]
  },
  "remove":{
      "tag-group-name3":[
        "tag-value"
      ]
  },
  "set":{
      "tag-group-name4":[
        "tag-value"
      ]
  }
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://go.urbanairship.com/api/tag-lists/ua_tags_foobar

{
  "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TagListRequest tagListRequest = TagListRequest.newRequest()
        .setName("ua_tags_my_new_list");
        .setDescription("First of many tags lists!")
        .addTags("tag_group1", ImmutableSet.of("tag1","tag2"))
        .removeTags("tag_group2", ImmutableSet.of("tag3","tag4"))
        .setTags("tag_group3", ImmutableSet.of("tag4","tag5"))
        .addExtra("test","value")
Response<GenericResponse> response = client.execute(tagListRequest);

from urbanairship import (
    BasicAuthClient, TagList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

tag_list = TagList(
    client=client,
    list_name="ua_tags_my_new_list",
    description="First of many tags lists!",
    extra={
        "filename": "tags.csv",
        "source": "CRM"
    },
    add_tags={
        "tag-group-name": ["tag-value"],
        "tag-group-name2": ["tag-value2a", "tag-value2b"]
    },
    remove_tags={
        "tag-group-name3": ["tag-value"]
    },
    set_tags={
        "tag-group-name4": ["tag-value"]
    }
)

tag_list.create()

require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: 'app_key', secret: 'master_secret')
tags = {'tag_group_name': ['tag1', 'tag2']}

tag_list = UA::TagList.new(client: airship)
tag_list.name = 'ua_tags_list_name'
tag_list.create(description: 'description', extra: {'key': 'value'}, add: tags)

Add tags to your contacts by creating a list and uploading CSV file with user identifiers. The body of the request contains the name, description, and optional metadata for the list. After you define a list, you populate it with a call to the Upload Tag List endpoint.

Security:

Request body:

  • Content-Type: application/json

    Tag list metadata object

    Contains all user-specified data when defining a tag list in Airship. Although add, remove, and set are optional, one or more must be present.

Responses

  • 201

    The list was created successfully.

    Response headers:

    • Location string

      The URI of the list, used for later updates.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 409

    The request conflicts with another request.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete tag list

DELETE /api/tag-lists/{list_name}

Example

DELETE /api/tag-lists/ua_tags_foobar HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+csv; version=3

HTTP/1.1 204 No Content

Delete a list. Deleting a list will not affect any previous uploads but will prevent new uploads to the deleted list. For example, this does not remove the tags associated with the previously-uploaded file from the channels in that file.

Security:

Path parameters:

  • list_name stringREQUIRED
    The name of the list.

Responses

  • 204

    The delete operation was successful.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Upload tag list

PUT /api/tag-lists/{list_name}/csv

Example

PUT /api/tag-lists/ua_tags_foobar/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

channel_id
c543f3a3-bc1d-4830-8dee-7532c6a23b9a
6ba360a0-1f73-4ee7-861e-95f6c1ed6410
15410d17-687c-46fa-bbd9-f255741a1523
c2c64ef7-8f5c-470e-915f-f5e3da04e1df

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();
        
TagListUploadRequest tagListUploadRequest = TagListUploadRequest.newRequest("ua_tags_cool_list", "path/to/file.csv");
Response<GenericResponse> response = client.execute(tagListUploadRequest);

from urbanairship import (
    BasicAuthClient, TagList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

tag_list = TagList(
    client=client,
    list_name="ua_tags_cool_list",
    description="example list"
)

tag_list.upload(file_path="path/to/file.csv")

require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: 'app_key', secret: 'master_secret')

tag_list = UA::TagList.new(client: airship)
tag_list.name = 'ua_tags_list_name'
tag_list.upload(csv_file: 'file_content', gzip: true)

Tag list CSV upload for SMS

PUT /api/tag-lists/ua_tags_foobar/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

channel_id
c543f3a3-bc1d-4830-8dee-7532c6a23b9a
6ba360a0-1f73-4ee7-861e-95f6c1ed6410
15410d17-687c-46fa-bbd9-f255741a1523
c2c64ef7-8f5c-470e-915f-f5e3da04e1df

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();
        
TagListUploadRequest tagListUploadRequest = TagListUploadRequest.newRequest("ua_tags_cool_list", "path/to/file.csv");
Response<GenericResponse> response = client.execute(tagListUploadRequest);

from urbanairship import (
    BasicAuthClient, TagList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

tag_list = TagList(
    client=client,
    list_name="ua_tags_cool_list",
    description="example list"
)

tag_list.upload(file_path="path/to/file.csv")

require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: 'app_key', secret: 'master_secret')

tag_list = UA::TagList.new(client: airship)
tag_list.name = 'ua_tags_list_name'
tag_list.upload(csv_file: 'file_content', gzip: true)

PUT /api/tag-lists/ua_tags_foobar/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

msisdn,sms_sender,firstName
5035556789,18588675309,Jane
4155551212,18588675309,Rory

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TagListUploadRequest tagListUploadRequest = TagListUploadRequest.newRequest("ua_tags_cool_list", "path/to/sms_file.csv.csv");
Response<GenericResponse> response = client.execute(tagListUploadRequest);

from urbanairship import (
    BasicAuthClient, TagList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

tag_list = TagList(
    client=client,
    list_name="ua_tags_foobar",
    description="example list"
)

tag_list.upload(file_path="path/to/sms_file.csv")

require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: 'app_key', secret: 'master_secret')

tag_list = UA::TagList.new(client: airship)
tag_list.name = 'ua_tags_list_name'
tag_list.upload(csv_file: 'sms_file_content', gzip: true)

Upload a CSV that will set tag values on the specified channels or Named Users.

The first entry in the uploaded CSV must be a header row. The first field must be one of the following identifier types: channel_id, msisdn, named_user, email_address.

Only one identifier type is allowed per file.

You must include both msisdn and sms_sender columns when targeting SMS or MMS channel types. See example to the right.

Uploads must be newline-delimited identifiers (text/CSV) as described in RFC 4180, with commas as the delimiter, optionally double-quoted values, UTF-8 encoded, and with CRLF or LF line separators.

Target typeRequired column headers
Webchannel_id
Open Channelchannel_id
iOSchannel_id
Androidchannel_id
Named Usernamed_user
Emailemail_address
SMS
  • msisdn (numeric and no leading 0)
  • sms_sender (numeric)
MMS
  • msisdn (numeric and no leading 0)
  • sms_sender (numeric)

Optional Fields: Opt-in dates can optionally be set for new channels when the identifier is an email_address or msisdn.

Target typeOptional column headers
SMSua_opted_in (UTC Timestamp)
MMSua_opted_in (UTC Timestamp)
Email
  • ua_transactional_opted_in (UTC Timestamp)
  • ua_commercial_opted_in (UTC Timestamp)

 Note

The maximum number of rows that may be uploaded to a list is 10 million. Content-Encoding: gzip is supported and recommended on this endpoint to reduce network traffic.

 Warning

If your upload times out due to a poor connection, you must re-upload the list from scratch. Because we want to ensure that the entirety of a given list is successfully uploaded, we do not support partial list uploads.

Security:

Path parameters:

  • list_name stringREQUIRED
    The name of the list you want to retrieve or update.

Request body:

  • Content-Type: text/csv

    Type: string

Responses

  • 202

    The request has been accepted for processing.

    Response body:

    • Content-Type: application/json
      OK response

      Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

  • 400

    Bad Request. Parsing or validating the request failed.

    Error codeDescription
    40002CSV contains too many identifiers
    40003CSV header contains too many columns
    40013CSV header’s first field must be an identifier
    40018CSV header does not contain required column for identifier type

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

    Response body:

    • Content-Type: application/json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Download list errors

GET /api/tag-lists/{list_name}/errors

Example

GET /api/tag-lists/ua_tags_foobar/errors HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+csv; version=3

HTTP/1.1 200 OK
Content-Type: text/csv

8b4de669-16f1-4e71-9a1f-0c62a8235a65,ERROR,"Unknown channel"
abcd,ERROR,"Invalid msisdn"

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TagListErrorsRequest request = TagListErrorsRequest.newRequest("ua_tags_foobar");
Response<String> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, TagList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

tag_list = TagList(
  airship=client, 
  list_name="ua_tags_foobar", 
  description="example list", 
)

errors = tag_list.get_errors()

require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: 'app_key', secret: 'master_secret')

tag_list = UA::TagList.new(client: airship)
error_csv = tag_list.errors

During processing, after a list is uploaded, errors can occur. Depending on the type of list processing, an error file may be created, showing a user exactly what went wrong.

Security:

Path parameters:

  • list_name stringREQUIRED
    The name of the list.

Responses

  • 200

    Returns OK for success. The response will contain the errors found during list processing.

    Response body:

    • Content-Type: text/csv

      Type: string

  • 401

    Authentication information (the app key and secret or bearer token) was either incorrect or missing.

    Response body:

    • Content-Type: text/plain
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    Response body:

    • Content-Type: application/vnd.urbanairship+json
      Error response

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Data Formats

Automation timing

Options to set delays and delivery time windows for automated messages.

Absolute window of time

Example absolute time window

{ "audience":
   {
      "date": {
         "days": {
            "start": "2020-01-01",
            "end": "2020-01-15"
         }
      }
   }
}

An object with start and end attributes containing ISO-formatted dates specifying an absolute window of time.

OBJECT PROPERTIES
  • end stringREQUIRED

    A date-time specifying the end date.

  • start stringREQUIRED

    A date-time specifying the start date.

Relative window of time

Example relative time window

{
  "date": {
     "days": {
        "recent": 1
     }
  }
}

A relative window of time is indicated by setting the recent attribute. The value is an object with a single integer-valued attribute set.

OBJECT PROPERTIES
  • recent integer

    The hours valid range is 1-48 (Up to the last two days). The days valid range is 1-60 (Up to the last 60 days). The weeks valid range is 1-10 (Up to the last 10 weeks). The months valid range is 1-48 (Up to the last 4 years). The years valid range is 1-10 (Up to the last 10 years).

Event Segmentation

Event Segmentation lets you target audiences based on lifecycle actions or Custom Events that have occurred.

To Segment based on event activity, include an Activity Object in your audience, and an optional Where Object to filter on specific event properties.

Activity audience object

Activity audience object

{
   "audience": {
      "activity": "app_open",
      "operator": "greater",
      "value": 2,
      "after": 3,
      "precision": "days",
      "where": {
         "property": "/_triggering_push/campaigns/categories",
         "operator": "equals",
         "value": "neowise"
      }
   }
}

The activity object defines the target audience based on lifecycle actions or Custom Event activity, using comparison operators on activity count and recency. Optionally include a where object, which filters for specific activity values.

In the example to the right, the target audience is users who have opened your app from a notification from the “neowise” campaign at least twice, 3 days ago.

OBJECT PROPERTIES
  • activity stringREQUIRED

    The target event activity, e.g., app_open.

    Default event values are enumerated below. If you create a custom or predefined event that you wish to segment users on, you must register the event in the Airship dashboard. See Manage events.

    Possible values: app_open, message_received, message_center_read, message_center_delivered, message_center_deleted, in_app_message_display, in_app_message_resolution, in_app_message_expiration, screen_view, web_session, web_click, short_link_click, first_seen, sms_aborted, sms_delivered, sms_dispatched, sms_expired, sms_failed, sms_rejected, sms_undeliverable, sms_unknown, email_bounce, email_click, email_delay, email_delivered, email_injection, email_open, email_unsubscribe, scene_displayed, scene_completed, scene_incomplete, survey_displayed, survey_submitted, survey_not_submitted

  • after object

    A date value for an absolute comparison or an integer value for a relative comparison.

    One of
    • string

      A date-time, for example: "after": "2020-08-01T12:00:00".

  • before object

    A date value for an absolute comparison or an integer value for a relative comparison.

    One of
    • string

      A date-time, for example: "before": "2020-08-01T12:00:00".

  • metric string

    The metric you are targeting for the event.

    When using the metric count or total_value, operator and value are required.

    When using either first or last, operator and value are not allowed. Use one of the following combinations instead:

    • before/precision
    • after/precision
    • on/on_precision
    MetricDescription
    countEvaluate based on the number of event occurrences.
    total_valueEvaluate based on the cumulative event value associated with the target user.
    lastEvaluate based on the last occurrence of an event for a given user/time window.
    firstEvaluate based on the first occurrence of an event for a given user/time window.

    Possible values: count, total_value, last, first

  • on string

    Use on in conjunction with the first or last metric to indicate either a specific date or period with precision. Use either:

    • A date in ISO 8601 format, e.g., 2020-08-10T17:28:34+0000 or
    • An integer that, when combined with the on_precision property, specifies the time period. For example, use "on": 12 with "on_precision: "month" to target events that occurred in December.

    One of
  • on_precision string

    When using the first or last metric with the on property to target events on. For example, for the 5th of any month, or only in March, use on_precision.

    Possible values: day, month, month_day, year_month, year_month_day

  • operator stringREQUIRED

    The comparison operator used to evaluate the activity expression. Use these operators (greater/less than, equal to, equal or greater/equal or less) when the metric is either count or total_value.

    Possible values: greater, less, equals, greater_eq, less_eq

  • precision string

    If using a relative number (integer) for the before/after/on property, the precision value will be interpreted as the number of time units ago, e.g., 7 days ago. Defaults to days.

    Possible values: days, weeks, months, years

  • value numberREQUIRED

    The value that the operator uses to evaluate the target audience.

  • where object

    The Where Object.

Where object

Example payload to an audience of users who have opened your app as a result of receiving a specific push ID.

{
   "audience": {
      "activity": "app_open",
      "metric": "count",
      "operator": "greater",
      "value": 0,
      "where": {
         "property": "/_triggering_push/push_id",
         "operator": "equals",
         "compare_as": "text",
         "value": "636abb88-5642-4035-998d-a04c93c499ad"
      }
   },
   "device_types": [
      "ios", "android"
   ],
   "notification": {
      "alert": "Did you get that thing I sent you?"
   }
}

where is an object that filters on the existence of prior user activity, specified by event properties that you provide.

OBJECT PROPERTIES
  • compare_as string

    Selects the property type for comparison.

    Possible values: text, number, date, boolean

  • operator stringREQUIRED

    The operator in question

    Possible values: greater, less, equals, greater_eq, less_eq, contains, present, range, before, after

  • precision string

    Used only for date values.

    Possible values: minutes, days, months, years

  • property stringREQUIRED

    The Custom Event property on which to filter for inclusion in the audience. See Event Segmentation Properties for properties reference.

  • relative_to string

    Used only for date values.

    Possible values: future, past

  • value objectREQUIRED

    The value of the property you are filtering for in the where object. Use compare_as to select the type for comparison.

    One of
    • string

      A date-time, e.g., 2020-08-10T17:28:34+0000.

Platform overrides

Override push settings and provide content for specific platforms (selected by device_type). The following schemas represent overrides for each platform.

Fire OS override

The platform override section for Kindle Fire (for Amazon Device Messaging).

OBJECT PROPERTIES
  • actions object<Actions>

    Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

  • alert string

    A string that override the alert value provided at the top level, if any.

  • consolidation_key string

    A string representing a key to suppress previous messages sent with the same key.

  • expires_after object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • extra object

    A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.

  • icon string

    A string representing an image file included in the application’s resources.

  • icon_color string

    A string representing the icon color in API Color Format. i.e., #rrggbb

  • interactive object<Interactive notification object>

    An interactive notification.

    Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

  • notification_channel string

    A string representing a notification channel. Used to group notifications with similar behavior.

  • notification_tag string

    A string representing a notification tag. If a message is currently displaying and has a tag set, sending another message with the same tag will replace the posted notification.

  • sound string

    A string representing a sound file name included in the application’s resources.

  • style object

    Advanced styles big text, big picture, and inbox are available on Android 4.3+ by adding the style to the platform specific notification payload on Android platforms. This object must contain a string field type which must be one of big_picture, big_text, or inbox. It may also contain title and summary override fields.

    OBJECT PROPERTIES
    • big_picture string

      If the type is set to big_picture, then there must also be a big_picture string field which contains the URL for an image.

    • big_text string

      If the type is set to big_text, then a big_text string field must be present with the text to be shown in big text style.

    • lines array[string]

      An array of strings if the type field is set to inbox.

    • summary string

      A string field which will override the summary of the notification.

    • title string

      A string field which will override the title of the notification.

    • type stringREQUIRED

      Possible values: big_picture, big_text, inbox

  • summary string

    A string representing a summary/subtitle of the notification.

  • title string

    A string representing the title of the notification. The default value is the name of the app.

Android override

Android override in a notification

{
   "android": {
      "title": "Shoe sale",
      "alert": "All the shoes are on sale!",
      "summary": "Don't miss out!",
      "extra": {
          "url": "http://example.com",
          "story_id": "1234",
          "moar": "{\"key\": \"value\"}"
      },
      "icon": "shoes",
      "icon_color": "#8B4513",
      "notification_channel": "promos"
   }
 }

Example wearable notification

{
   "android": {
      "title": "Shoe sale",
      "alert": "All the shoes are on sale!",
      "summary": "Don't miss out!",
      "extra": {
          "url": "http://example.com",
          "story_id": "1234",
          "moar": "{\"key\": \"value\"}"
      },
      "icon": "shoes",
      "icon_color": "#8B4513",
      "notification_channel": "promos"
   }
 }

{
   "android": {
      "local_only": true,
      "wearable": {
         "background_image": "http://example.com/background.png",
         "extra_pages": [
            {
               "title": "Page 1 title - optional title",
               "alert": "Page 1 title - optional alert"
            },
            {
               "title": "Page 2 title - optional title",
               "alert": "Page 2 title - optional alert"
            }
         ],
         "interactive": {
            "type": "ua_yes_no_foreground",
            "button_actions": {
               "yes": {
                  "add_tag": "butter",
                  "remove_tag": "cake",
                  "open": {
                     "type": "url",
                     "content": "http://www.urbanairship.com"
                  }
               },
               "no": {
                  "add_tag": "nope"
               }
            }
         }
      }
   }
}

Android override in a notification with notification_tag

{
   "android": {
      "title": "Shoe sale",
      "alert": "All the shoes are on sale!",
      "summary": "Don't miss out!",
      "extra": {
          "url": "http://example.com",
          "story_id": "1234",
          "moar": "{\"key\": \"value\"}"
      },
      "icon": "shoes",
      "icon_color": "#8B4513",
      "notification_channel": "promos"
   }
 }

{
   "android": {
      "local_only": true,
      "wearable": {
         "background_image": "http://example.com/background.png",
         "extra_pages": [
            {
               "title": "Page 1 title - optional title",
               "alert": "Page 1 title - optional alert"
            },
            {
               "title": "Page 2 title - optional title",
               "alert": "Page 2 title - optional alert"
            }
         ],
         "interactive": {
            "type": "ua_yes_no_foreground",
            "button_actions": {
               "yes": {
                  "add_tag": "butter",
                  "remove_tag": "cake",
                  "open": {
                     "type": "url",
                     "content": "http://www.urbanairship.com"
                  }
               },
               "no": {
                  "add_tag": "nope"
               }
            }
         }
      }
   }
}

{
   "android": {
       "notification_tag": "push-xyz"
   }
 }

The platform override section for Android. Maximum 4,096 bytes.

OBJECT PROPERTIES
  • actions object<Actions>

    Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

  • alert string

    A string that override the alert value provided at the top level, if any.

  • category string

    Helps determine notification sort order. Available on Android Lollipop+.

    Possible values: alarm, call, email, err, event, msg, promo, recommendation, service, social, status, sys, transport

  • collapse_key string

    A key indicating that this message can replace, or be replaced by, another message with the same collapse_key. This feature comes into play when a device is offline (e.g., airplane mode) or in doze mode; if multiple messages are available with the same collapse_key when a device comes back online, it will display only the most recent message and discard previous messages using the same collapse_key.

  • delay_while_idle booleanDEPRECATED

    After November 15, 2016, this was still accepted by GCM, but ignored. When set to true, it indicates that the message should not be sent until the device becomes active. The default value is false.

  • deliver_to string

    Filters out Android channels that are not able to receive notifications. If the value is opted_in, the payload is only sent to opted-in devices. If the value is all, the payload is sent to opted-in and background enabled devices. Defaults to all if not provided.

    Possible values: all, opted_in

  • delivery_priority string

    Sets the FCM/GCM priority of the message. Defaults to normal if not provided.

    Possible values: high, normal

  • extra object

    A JSON dictionary of string-to-string key-value pairs. The keys from, message_type, data and keys that start with google or gcm are disallowed.

  • icon string

    A string representing an image file included in the application’s resources.

  • icon_color string

    A string representing the icon color in API Color Format. i.e., #rrggbb

  • interactive object<Interactive notification object>

    An interactive notification.

    Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

  • live_update object

    JSON object that represents the content sent to a Live Update notification. Live Updates are an AXP feature.

    Note: Using this object transforms the Android notification to a Live Update notification. When event is equal to start, the entire targeted audience will receive the Live Update content. When event is equal to update or end, only devices that have a Live Update started for the specified name field will receive the Live Update content.

    OBJECT PROPERTIES
    • content_state object

      A dictionary of string keys to arbitrary JSON values that represents the content state to be updated by the Live Activity or Live Update notification.

    • dismissal_date integer

      An optional epoch timestamp in seconds, used when you end the Live Update.

    • event string

      Use start to start a Live Update. Use update to update a current Live Update. Use end to emit the last update and end the Live Update.

      Possible values: start, update, end

    • name string

      The name of the Live Update to target. When event is equal to update or end, the audience will be limited to devices that have a Live Update started for the specified name.

    • timestamp integer

      An optional epoch timestamp in seconds, used to enforce the Live Update ordering. If you don’t provide one, the current timestamp is used.

    • type string

      Used to map Live Update events to the corresponding handler in your app.

  • local_only boolean

    If true, the notification is only shown on wearable devices.

  • notification_channel string

    A string representing a notification channel. Used to group notifications with similar behavior.

  • notification_tag string

    A string representing a notification tag. If a message is currently displaying and has a tag set, sending another message with the same tag will replace the posted notification. Similar to the iOS collapse_id.

  • priority integer

    An integer in the range from -2 to 2 inclusive. Used to help determine notification sort order. 2 is the highest priority, -2 is the lowest, and 0 is the default priority.

  • public_notification object

    An optional notification to show on lock screen instead of the redacted one. This is only useful with visibility set to -1 (private). The object may contain any of the following string fields title, alert, and summary.

    OBJECT PROPERTIES
    • alert string
    • summary string
    • title string
  • sound string

    A string representing a sound file name included in the application’s resources.

  • style object

    Advanced styles big text, big picture, and inbox are available on Android 4.3+ by adding the style to the platform specific notification payload on Android platforms. This object must contain a string field type which must be one of big_picture, big_text, or inbox. It may also contain title and summary override fields.

    OBJECT PROPERTIES
    • big_picture string

      If the type is set to big_picture, then there must also be a big_picture string field which contains the URL for an image.

    • big_text string

      If the type is set to big_text, then a big_text string field must be present with the text to be shown in big text style.

    • lines array[string]

      An array of strings if the type field is set to inbox.

    • summary string

      A string field which will override the summary of the notification.

    • title string

      A string field which will override the title of the notification.

    • type stringREQUIRED

      Possible values: big_picture, big_text, inbox

  • summary string

    A string representing a summary/subtitle of the notification.

  • time_to_live object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • title string

    A string representing the title of the notification. The default value is the name of the app.

  • visibility integer

    An integer in the range from -1 to 1 inclusive. 1 = public (default), 0 = private, -1 = secret. Secret does not show any notifications. Private shows a redacted version of the notification.

    Possible values: -1, 0, 1

  • wearable object

    Provides options for messages displayed on wearable Android devices.

    OBJECT PROPERTIES
    • background_image string

      The URL to a background image to display on the wearable device.

    • extra_pages array[object]

      An array of objects, each with a title and alert string attributes specifying extra pages of text to appear as pages after the notification alert on the wearable device.

    • interactive object<Interactive notification object>

      An interactive notification.

      Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

Email override

Example with email notification

{
   "audience": {
      "named_user": "jane_doe"
   },
   "device_types": [
      "email",
      "android"
   ],
   "notification": {
      "android": {
         "alert": "Hello Android user!"
      },
      "email": {
         "subject": "Did you get that thing I sent you?",
         "html_body": "<h2>Richtext body goes here</h2><p>Wow!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
         "plaintext_body": "Plaintext version goes here [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
         "message_type": "transactional",
         "sender_name": "Airship",
         "sender_address": "team@urbanairship.com",
         "reply_to": "no-reply@urbanairship.com",
         "click_tracking": false,
         "open_tracking": false,
         "attachments": [
            {
               "id": "0e10a6b9-725c-4f6b-9af2-9ef5b31328c0",
            },
            {
               "id": "5503b5fe-ed69-4609-bef6-6fef0e6e428f"
            }
         ],
         "url_parameters": {
           "utm_source": "airship",
           "utm_channel": "email"
         }
      }
   }
}

Example email with dynamic sender name, sender address, and reply-to address

{
   "audience": {
      "named_user": "jane_doe"
   },
   "device_types": [
      "email",
      "android"
   ],
   "notification": {
      "android": {
         "alert": "Hello Android user!"
      },
      "email": {
         "subject": "Did you get that thing I sent you?",
         "html_body": "<h2>Richtext body goes here</h2><p>Wow!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
         "plaintext_body": "Plaintext version goes here [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
         "message_type": "transactional",
         "sender_name": "Airship",
         "sender_address": "team@urbanairship.com",
         "reply_to": "no-reply@urbanairship.com",
         "click_tracking": false,
         "open_tracking": false,
         "attachments": [
            {
               "id": "0e10a6b9-725c-4f6b-9af2-9ef5b31328c0",
            },
            {
               "id": "5503b5fe-ed69-4609-bef6-6fef0e6e428f"
            }
         ],
         "url_parameters": {
           "utm_source": "airship",
           "utm_channel": "email"
         }
      }
   }
}

{
   "audience": {
      "named_user": "jane_doe"
   },
   "device_types": [
      "email"
   ],
   "notification": {
      "email": {
         "subject": "Did you get that thing I sent you?",
         "html_body": "<h2>Richtext body goes here</h2><p>Wow!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
         "plaintext_body": "Plaintext version goes here [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
         "message_type": "transactional",
         "sender_name": "{{email_sender_name}}",
         "sender_address": "{{email_sender_username}}@airship.com",
         "reply_to": "{{email_reply_to_username}}@airship.com",
      }
   }
}

Notification fields specific to email messages. This object is required when email is specified in the payload’s device_types field.

OBJECT PROPERTIES
  • attachments array[object]

    Optional list of objects, each containing an id string which represents an email attachment.

    See Email Attachments

  • bcc array[string]

    An array of email addresses that you want to blind copy on this email. Contact your Account Manager to enable BCC addresses. Using addresses that your Airship Account Manager has not enabled for BCC will return a 400.

  • bypass_opt_in_level boolean

    You can set this toggle when message_type is set to transactional to send a business-critical email. If true, the message will be sent to your entire audience, ignoring transactional_opted_out status.

  • click_tracking boolean

    True by default. Set to false to prevent click tracking for GDPR compliance.

  • html_body string

    The rich-text HTML body of the email, no larger than 100 KB.

    • When "message_type": "commercial", the body must contain an unsubscribe link in the format <a data-ua-unsubscribe=“1” title=“unsubscribe”>Unsubscribe</a>. You can send the user to a custom “goodbye” page by providing an href attribute in the link: <a data-ua-unsubscribe=“1” title=“unsubscribe” href=“YOUR_URL”>Unsubscribe</a>. If your unsubscribe link includes an href, Airship unsubscribes the user before redirecting to your page. Additionally, <a data-ua-opt-in=“1” title=“subscribe”>Subscribe and <a data-ua-opt-in=“1” title subscribe" href=“YOUR_URL_HERE”>Subscribe will be replaced by a link that will opt the user in to both commercial and transactional messaging and optionally redirect the user to a customer-supplied landing page.
    • See: Email image recommendations.

  • message_type stringREQUIRED

    Must be transactional or commercial. If a message type is specified in the push payload, the email message type must match. Otherwise, it will result in a 400-level error.

    Possible values: transactional, commercial

  • open_tracking boolean

    True by default. Set to false to prevent open tracking for GDPR compliance.

  • plaintext_body stringREQUIRED

    The plain text body of the email, no larger than 100 KB.

    When "message_type": "commercial", the body must contain a [[ua_unsubscribe]] link, which will be replaced by the unsubscribe link in Airship. You can send the user to a custom “goodbye” page by providing an href in the format [[ua-unsubscribe href=“your url here”]]. If you include an href, Airship unsubscribes the user before redirecting to your page. Additionally, [[ua-opt-in]] and [[ua-opt-in href=“YOUR_URL_HERE”]] will be replaced by a link that will opt the user in to both commercial and transactional messaging and optionally redirect the user to a customer-supplied landing page.

  • reply_to stringREQUIRED

    The reply-to address. The username portion of the reply-to address can be set dynamically using Handlebars. The domain portion of the reply-to address can be any correctly formatted domain.

  • sender_address stringREQUIRED

    The email address of the sender. The domain of the email must be enabled in the email provider at the delivery tier (ie: SparkPost). The username portion of the sender address can be set dynamically using Handlebars. The domain portion of the sender address must match one of your project’s configured email sending domains.

  • sender_name stringREQUIRED

    The common name for the sender, visible to email recipients. The sender name can be set dynamically using Handlebars.

  • subject stringREQUIRED

    The subject line of the email.

  • url_parameters object

    A JSON dictionary of string-to-string key-value pairs as UTM or custom parameters. Each key and value will become a query parameter key and URL-encoded value that are automatically appended to all link URLs in an email. These parameters are used for tracking campaign performance.

    If a query parameter defined in this object already exists in a link, it will not be overwritten in the link. Dynamic values are supported using Handlebars, with limitations. See URL parameters in the Email content guide for more information.

iOS override

Example with media attachment

{
    "audience": "all",
    "device_types": [
            "ios"
        ],
    "notification": {
        "ios": {
            "thread_id": "sfGiants_news",
            "alert": {
                "title": "Kevin Gausman Throws a Perfect Game",
                "body": "Kevin Gausman stymies the Houston Astros for San Francisco's second perfect game in franchise history.",
                "summary-arg": "San Francisco Giants",
                "summary-arg-count": 1
            },
            "relevance-score": 1.0,
            "interruption_level": "passive",
            "sound": "strike-call",
            "media_attachment": {
                "content": {
                    "title": "Kevin Gausman",
                    "body": "Gausman strikes out Justin Turner"
                },
                "options": {
                    "crop": {
                        "height": 0.5,
                        "width": 0.5,
                        "x": 0.25,
                        "y": 0.25
                    },
                    "time": 15
                },
                "url": "https://media.example.com/media/6nJmrhlu4aL1m/giphy.gif"
            },
            "mutable_content": 1
        }
    }
}

iOS override in a notification with collapse_id

{
    "audience": "all",
    "device_types": [
            "ios"
        ],
    "notification": {
        "ios": {
            "thread_id": "sfGiants_news",
            "alert": {
                "title": "Kevin Gausman Throws a Perfect Game",
                "body": "Kevin Gausman stymies the Houston Astros for San Francisco's second perfect game in franchise history.",
                "summary-arg": "San Francisco Giants",
                "summary-arg-count": 1
            },
            "relevance-score": 1.0,
            "interruption_level": "passive",
            "sound": "strike-call",
            "media_attachment": {
                "content": {
                    "title": "Kevin Gausman",
                    "body": "Gausman strikes out Justin Turner"
                },
                "options": {
                    "crop": {
                        "height": 0.5,
                        "width": 0.5,
                        "x": 0.25,
                        "y": 0.25
                    },
                    "time": 15
                },
                "url": "https://media.example.com/media/6nJmrhlu4aL1m/giphy.gif"
            },
            "mutable_content": 1
        }
    }
}

{
   "ios": {
       "collapse_id": "push-xyz"
   }
 }

The platform override section for iOS. Maximum 4,096 bytes.

OBJECT PROPERTIES
  • actions object<Actions>

    Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

  • alert object

    Override the alert value provided at the top level, if any. May be a JSON string or an object which conforms to Apple’s push service spec.

    One of
    • string

      Alert override text for iOS devices.

    • JSON object that conforms to Apple’s Payload Key Reference .

      When using thread_id to group notifications, you might want to use the summary-arg and summary-arg-count keys to help users identify the group.

      OBJECT PROPERTIES
      • action-loc-key string

        If a string is specified, the system displays an alert that includes the Close and View buttons. The string is used as a key to get a localized string in the current localization to use for the right button’s title instead of “View”.

      • body string

        The content of the alert message.

      • launch-image string

        The name of the launch image file you want to display with the alert. If the user chooses to launch your app, the contents of the specified image or storyboard file are displayed instead of your app’s normal launch image.

      • loc-args array[string]

        An array of strings containing replacement values for variables in your message text. Each %@ character in the string specified by loc-key is replaced by a value from this array. The first item in the array replaces the first instance of the %@ character in the string, the second item replaces the second instance, and so on.

      • loc-key string

        The key for a localized message string. Use this key, instead of the body key, to retrieve the message text from your app’s Localizable.strings file. The value must contain the name of a key in your strings file.

      • subtitle string

        Additional information explaining the purpose of the notification.

      • subtitle-loc-args array[string]

        An array of strings containing replacement values for variables in your subtitle string. Each %@ character in the string specified by subtitle-loc-key is replaced by a value from this array. The first item in the array replaces the first instance of the %@ character in the string, the second item replaces the second instance, and so on.

      • subtitle-loc-key string

        The key for a localized subtitle string. Use this key, instead of the subtitle key, to retrieve the subtitle from your app’s Localizable.strings file. The value must contain the name of a key in your strings file.

      • summary-arg string

        A string added to the summary of grouped notifications represented by the thread_id

      • summary-arg-count integer

        The number of summary-arg strings that a group of notifications represented by a thread_id will display.

      • title string

        The title of the notification. Apple Watch displays this string in the short look notification interface. Specify a string that is quickly understood by the user.

      • title-loc-args array[string]

        An array of strings containing replacement values for variables in your title string. Each %@ character in the string specified by the title-loc-key is replaced by a value from this array. The first item in the array replaces the first instance of the %@ character in the string, the second item replaces the second instance, and so on.

      • title-loc-key string

        The key for a localized title string. Specify this key instead of the title key to retrieve the title from your app’s Localizable.strings files. The value must contain the name of a key in your strings file.

  • badge integer

    May be an integer, the value auto, or an increment value. Increments are expressed by integers formatted as strings, and prefixed with either + (U+002B) or - (U+002D). The numeric portion may be an integer value.

  • category string

    Sets the APNs category for the push. This maps directly to the category field in the aps section of the APNs payload. Any interactive notification specified for the IOS platform will take precedence and this value will be ignored (the interactive notification type will be used for the category).

  • collapse_id string

    When there is a newer message that renders an older, related message irrelevant to the client app, the new message replaces the older message with the same collapse_id. Similar to the Android notification_tag. The value of this key must not exceed 64 bytes. iOS 10 or above.

  • content_available boolean

    If true, the payload is delivered to your app in the background.

    This flag is automatically set to true if there is an In-App Message in the payload. Attempting to override this value to false when there is an in-app message will result in a 400 Bad Request response from the API.

  • expiry object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • extra object

    A dictionary of string keys to arbitrary JSON values. The key aps would conflict with the generated APNs payload and is disallowed.

  • filter_criteria string

    The criteria the system evaluates to determine if it displays the notification in the current Focus.

  • interactive object<Interactive notification object>

    An interactive notification.

    Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

  • interruption_level string

    Indicates the importance and delivery timing of a notification.

    Note: Using a critical interruption level requires a special entitlement from Apple. If you have this entitlement, please contact your Airship Account Manager or our Support team to enable usage for your project.

    Possible values: passive, active, time-sensitive, critical

  • live_activity object

    JSON object that represents the content sent to a Live Activity Notification . Live Activities are an AXP feature.

    Note: Using this object transforms the iOS notification to a Live Activity notification. Only devices targeted by the Live Activity name field will receive the Live Activity update. Fields outside of the live_activity object will be ignored.

    OBJECT PROPERTIES
    • alert object

      An optional alert content for the Live Activity push payload.

      On Apple Watch, the system uses the title and body attributes for the alert. On iPhone, the system doesn’t show a regular alert but instead shows the expanded Live Activity in the Dynamic Island. On devices that don’t support the Dynamic Island, the system displays a banner on the Home Screen that uses the expanded view of your Live Activity.

      OBJECT PROPERTIES
      • body string

        The content of the Apple Watch alert message.

      • sound string

        The name of the sound file in your app’s bundle that you want to play for the alert.

      • title string

        The title of the Apple Watch notification. Apple Watch displays this string in the short look notification interface. Specify a string that is quickly understood by the user.

    • attributes object

      The attributes that describe the Live Activity for a start event.

    • attributes_type string

      The type of attributes that describe the Live Activity for a start event.

    • content_state object

      A dictionary of string keys to arbitrary JSON values that represents the content state to be updated by the Live Activity or Live Update notification.

    • dismissal_date integer

      An optional epoch timestamp in seconds, used when you end the Live Activity. If you don’t provide one, the default behavior (after 4 hours) is used.

    • event string

      Use start to start a Live Activity. Use update to update a current Live Activity. Use end to emit the last update and end the Live Activity.

      Possible values: start, update, end

    • name string

      The name of the Live Activity to target. The audience will be limited to devices that have a Live Activity registered for the specified name.

    • priority integer

      Sets the APNs priority of the Live Activity delivery. Valid values are 10 (immediate delivery) and 5 (conserve battery). enum: [5, 10]

    • relevance_score number

      An optional number, determines which of the Live Activities appears in the Dynamic Island and the order of your Live Activities on the lock screen.

    • stale_date integer

      An optional epoch timestamp in seconds, tells the system when the Live Activity content becomes outdated.

    • timestamp integer

      An optional epoch timestamp in seconds, used to enforce the Live Activity updates ordering. If you don’t provide one, the current timestamp is used.

  • media_attachment object

    The media_attachment key on the iOS override is a JSON object that describes a media attachment to be handled by the Airship Media Attachment extension in iOS 10.

    OBJECT PROPERTIES
    • content object

      A JSON object that describes portions of the notification that should be modified if the media attachment succeeds, with any of the following fields

      OBJECT PROPERTIES
      • body string
      • subtitle string
      • title string
    • options object

      A JSON object that describes how to display the resource at the URL specified above, with any of the following fields.

      OBJECT PROPERTIES
      • crop object

        A JSON object that describes the crop parameters to be used in the thumbnail. Each field is a decimal, normalized from 0 to 1. Before displaying the thumbnail, iOS additionally crops the thumbnail down to a square. See: Media guidelines.

        OBJECT PROPERTIES
        • height number

          The height of the final crop.

        • width number

          The width of the final crop.

        • x number

          The X offset where the crop begins.

        • y number

          The Y offset where the crop begins.

      • hidden boolean

        A boolean, when true, the thumbnail will be hidden.

      • time integer

        A decimal, the frame of the animated resource that should be used in the thumbnail . For GIFs, this value should be the frame number (an integer, with the first frame being frame 1) to show in the thumbnail. For video, the value should be the time (in seconds) into the video from which to grab the thumbnail. This value should not be set for static resources like JPGs. If the time does not exist in the resource, either because it is out of bounds or because the resource is static, the thumbnail will not show.

    • url stringREQUIRED

      The URL to be downloaded by the Airship Media Attachment extension. The media file should be one of the following types, and not exceed the maximum file size. Image (5 MB): JPEG, GIF, PNG. Audio (10 MB): AIFF, WAV, MP3, M4A. Video (50 MB): MPEG, MPEG2, MP4, AVI. Although these are the theoretical file size maximums, for performance the actual resources should be much smaller. See Media Guidelines.

  • mutable_content boolean

    When set to true, content may be modified by an extension. This flag will be automatically set to true if there is a media_attachment in the payload. iOS 10 or above. Defaults to false.

  • priority integer

    Sets the APNs priority of the delivery. Valid values are 10 (immediate delivery) and 5 (conserve battery). The default value will be 10 if the notification is user-visible (In-App Message payload does not count towards visibility) which means there is either an alert, badge, or sound. If the notification is not user-visible, the priority will default to 5 and it is not legal to override this value to 10. Attempts to do so will cause the API respond with a 400 Bad Request response. enum: [5, 10]

  • relevance_score number

    A number from 0.0 to 1.0. Used to sort notifications for an app. The notification with highest score is featured in the notification summary.

  • sound string

    The name of the sound file in your app’s bundle that you want to play for the alert. If the notification is critical, the dictionary has a key for "name" (equivalent to the current sound string), "volume" (a number between 0 and 1 indicating the volume), and "critical" (a boolean indicating if the alert should override local device settings and still notify).

  • subtitle string

    A string that will display below the title of the notification. This is provided as a convenience for setting the subtitle in the alert JSON object. If a subtitle is also defined in the alert JSON object, this value is ignored. iOS 10.

  • target_content_id string

    The identifier of the window to bring forward when the notification is opened. Used for multi-window content, such as App Clips.

  • thread_id string

    A unique identifier used to group notifications into separate threads in the Notification Center and on the lock screen. Grouped notifications are available beginning with iOS 12.

  • title string

    A short string describing the purpose of the notification. This is provided as a convenience for setting the title in the alert JSON object. If a title is also defined in the alert JSON object, this value is ignored.

MMS platform overrides

Example MMS notification

{
   "mms": {
      "subject" : "Double Rainbows",
      "fallback_text": "See https://urbanairship.com/double-rainbows?ua-tag-add=rainbows:used_fallback_text for double rainbows!",
      "shorten_links": true,
      "slides" : [
         {
            "text": "A double rainbow is a wonderful sight where you get two spectacular natural displays for the price of one.",
            "media": {
               "url": "https://www.metoffice.gov.uk/binaries/content/gallery/mohippo/images/learning/learn-about-the-weather/rainbows/full_featured_double_rainbow_at_savonlinna_1000px.jpg",
               "content_type": "image/jpeg",
               "content_length": 238686
            }
         }
      ]
   },
   "device_types": ["sms"]
}

Provides the content for a push to MMS channels. If sms is in the device_type array, your request may include this object. It cannot be combined with an SMS Platform Override as a single push can only include either an SMS or MMS payload.

OBJECT PROPERTIES
  • fallback_text stringREQUIRED

    If a member of your audience cannot receive MMS messages, they will receive your fallback text with a link to the original content.

  • shorten_links boolean

    If true, Airship will shorten HTTP/HTTPS links (space delimited) in the message text fields, producing unique, 25 character URLs for each member of your audience. Airship produces short_link_click events in the Real-Time Data Stream for each link that a user engages with.

    When this setting is enabled, you can add or remove tags from users who click your links by adding query strings to your URLs. You can serialize tag operations with &:

    • ?ua-tag-add=tag_group:tag&another_group:tag2 — adds a tag in tag_group to the channel_id.
    • ?ua-tag-remove=tag_group:tag&another_group:tag2 — removes a tag in tag group from the channel_id.
    • ?ua-list-add=subscription_list_id — adds the user’s channel to the subscription list.
    • ?ua-list-remove=subscription_list_id — removes the user’s channel from the subscription list.

  • slides array[object]REQUIRED

    An array containing a single slide object. A slide is a multimedia object.

  • subject string

    The subject for the MMS message, normally displayed in bold. The subject might not appear for recipients if the Sender is a Toll-Free number. An empty string is valid.

Open channel override

Example push with open channel override

{
   "audience" : {
      "OR" : [
            { "tag" : ["sports", "entertainment"]},
            { "device_token" : "871922F4F7C6DF9D51AC7ABAE9AA5FCD7188D7BFA19A2FA99E1D2EC5F2D76506" },
            { "open_channel" : "6bcf3e63-a38a-44d8-8b0d-2fb5941e74ab" } ]
   },
   "notification" : {
      "alert" : "Someone did sports!",
      "ios" : {
         "extra" : {
            "url" : "http://www.example.com" } },
      "open::sms" : {
         "alert" : "SMS override alert value! I will replace the top-level alert.",
         "extra" : {
            "sms_key" : "Some SMS specific payload data for all SMS devices." } },
      "open::email" : {
         "alert" : "Email override alert value! I will replace the top-level alert.",
         "title" : "A title for email payloads - neat!" }
   },
   "options" : { "expiry" : 60 },
   "device_types" : [ "ios", "open::sms", "open::email" ]
}

Open platform example

{
   "audience" : {
      "OR" : [
            { "tag" : ["sports", "entertainment"]},
            { "device_token" : "871922F4F7C6DF9D51AC7ABAE9AA5FCD7188D7BFA19A2FA99E1D2EC5F2D76506" },
            { "open_channel" : "6bcf3e63-a38a-44d8-8b0d-2fb5941e74ab" } ]
   },
   "notification" : {
      "alert" : "Someone did sports!",
      "ios" : {
         "extra" : {
            "url" : "http://www.example.com" } },
      "open::sms" : {
         "alert" : "SMS override alert value! I will replace the top-level alert.",
         "extra" : {
            "sms_key" : "Some SMS specific payload data for all SMS devices." } },
      "open::email" : {
         "alert" : "Email override alert value! I will replace the top-level alert.",
         "title" : "A title for email payloads - neat!" }
   },
   "options" : { "expiry" : 60 },
   "device_types" : [ "ios", "open::sms", "open::email" ]
}

{
   "alert": "A generic alert sent to all open platforms",
   "device_types" : ["open::sms", "open::email"],
   "open::sms": {
      "title": "SMS Alert!",
      "alert": "A shorter alert for SMS users",
      "summary": "A longer summary of some content or whatever",
      "media_attachment": "https://example.com/cat_standing_up.jpeg",
      "extra": {
         "some_info": "For SMS only",
         "some_id": "671ecd12-ad56-4b2f-98f1-107ce33d33e6" },
      "interactive": {
         "type": "ua_yes_no_foreground",
         "button_actions": {
            "yes": {
               "open": {
                  "type": "url",
                  "content": "http://www.example.com" } },
            "no": {
               "app_defined": {
                  "foo": "bar" } } } }
   },
   "open::email": {
      "alert": "A longer alert for users of email, who have more space." }
}

The platform override section for open platforms uses the prefix attribute open:: before the configured open platform name. The open::<open_platform_name> object will contain an object with the following attributes.

OBJECT PROPERTIES
  • alert string

    Override the alert value provided at the top level, if any.

  • extra object

    A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.

  • interactive object<Interactive notification object>

    An interactive notification.

    Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

  • media_attachment string

    A URI for an image or video somewhere on the internet.

  • summary string

    A string value for providing a content summary.

  • title string

    A string representing the title of the notification.

SMS platform overrides

Example SMS notification

{
    "audience": {
       "named_user": "user"
    },
    "notification": {
       "alert": "A generic alert sent to all platforms without overrides in device_types",
       "sms": {
          "alert": "A shorter alert with a link for SMS users to click https://www.example.com/long/form/url?ua-tag-add=this_group:this_tag",
          "expiry": 172800,
          "shorten_links": true
       }
    },
    "device_types": [ "sms" ]
}

Provides override options when sms is one of the device_types specified in the payload.

OBJECT PROPERTIES
  • alert string

    Overrides the alert provided at the top level of the notification for SMS channels. The maximum length of an SMS alert is 1,600 characters. The alert will be split into multiple messages by CLX if needed.

  • expiry object

    The time after which Airship will stop trying to deliver an SMS message. The maximum expiry period is 48 hours; this is also the default expiry period.

    One of
    • string

      A date-time. The timestamp must be within the next 48 hours.

  • shorten_links boolean

    If true, Airship will shorten HTTP/HTTPS links (space delimited) in the message text fields, producing unique, 25 character URLs for each member of your audience. Airship produces short_link_click events in the Real-Time Data Stream for each link that a user engages with.

    When this setting is enabled, you can add or remove tags from users who click your links by adding query strings to your URLs. You can serialize tag operations with &:

    • ?ua-tag-add=tag_group:tag&another_group:tag2 — adds a tag in tag_group to the channel_id.
    • ?ua-tag-remove=tag_group:tag&another_group:tag2 — removes a tag in tag group from the channel_id.
    • ?ua-list-add=subscription_list_id — adds the user’s channel to the subscription list.
    • ?ua-list-remove=subscription_list_id — removes the user’s channel from the subscription list.

Web override

Example with web override

{
   "audience": {
      "channel": "cab69081-0196-4f6b-91dc-53bc88a2e6ce"
   },
   "device_types": [
      "web"
   ],
   "notification": {
      "alert": "Hello, world!",
      "web": {
         "alert": "Hello Web World",
         "title": "A Custom Web Title",
         "require_interaction": true,
         "buttons": [
            {
               "id": "yes",
               "label": "Yes",
               "actions": {
                  "open": {
                     "type": "home"
                  },
                  "add_tag": [
                     "new_tag"
                  ]
               }
            },
            {
               "id": "no",
               "label": "No"
            }
         ],
         "extra": {
            "story_id": "1234",
            "moar": "{\"key\": \"value\"}"
         }
      }
   }
}

The web platform overrides determine message behaviors for web notifications.

Safari behaves differently from other browsers and supports only the alert and title overrides. It ignores all other web overrides.

OBJECT PROPERTIES
  • actions object<Actions>

    Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

  • alert string

    Override the alert value provided at the top level, if any.

  • buttons array[object]

    Contains one or two buttons that perform actions for the web notification. If you do not specify actions for a button, the button closes the notification without performing an action.

  • extra object

    A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.

  • icon object

    A JSON object that describes an icon to be used with the notification.

    OBJECT PROPERTIES
    • url stringREQUIRED

      The URL to be used for the icon.

  • image object

    A JSON object that describes an image to be used with the web alert.

    OBJECT PROPERTIES
    • url stringREQUIRED

      The URL to be used for the image.

  • require_interaction boolean

    If true, a feature that requires a user to interact with the notification in order to remove it from their computer screen.

  • time_to_live object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • title string

    A string representing the title of the notification.

Platform overrides with templates

Override push settings and provide content for specific platforms (selected by device_type) using a template. Templated platform overrides automatically allow personalization using Handlebars.

Fire OS override with template

Fire OS override with a template

{
   "amazon": {
      "title": "Shoe sale on {{level}} floor!",
      "alert": "All the shoes are on sale {{name}}!",
      "summary": "Don't miss out!",
      "icon": "shoes",
      "icon_color": "{{iconColor}}"
   }
}

Fire OS override with a template_id

{
   "amazon": {
      "title": "Shoe sale on {{level}} floor!",
      "alert": "All the shoes are on sale {{name}}!",
      "summary": "Don't miss out!",
      "icon": "shoes",
      "icon_color": "{{iconColor}}"
   }
}

{
   "amazon": {
       "template": {
           "template_id": "608f1f6c-8860-c617-a803-b187b491568e"
       }
   }
}

Use a template with a Fire OS-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

OBJECT PROPERTIES
  • actions object<Actions>

    Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

  • consolidation_key string

    A string representing a key to suppress previous messages sent with the same key.

  • expires_after object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • extra object

    A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.

  • interactive object<Interactive notification object>

    An interactive notification.

    Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

  • notification_channel string

    A string representing a notification channel. Used to group notifications with similar behavior.

  • notification_tag string

    A string representing a notification tag. If a message is currently displaying and has a tag set, sending another message with the same tag will replace the posted notification.

  • sound string

    A string representing a sound file name included in the application’s resources.

  • style object

    Advanced styles big text, big picture, and inbox are available on Android 4.3+ by adding the style to the platform specific notification payload on Android platforms. This object must contain a string field type which must be one of big_picture, big_text, or inbox. It may also contain title and summary override fields.

    OBJECT PROPERTIES
    • big_picture string

      If the type is set to big_picture, then there must also be a big_picture string field which contains the URL for an image.

    • big_text string

      If the type is set to big_text, then a big_text string field must be present with the text to be shown in big text style.

    • lines array[string]

      An array of strings if the type field is set to inbox.

    • summary string

      A string field which will override the summary of the notification.

    • title string

      A string field which will override the title of the notification.

    • type stringREQUIRED

      Possible values: big_picture, big_text, inbox

  • template object
    One of
    • OBJECT PROPERTIES
    • OBJECT PROPERTIES
      • fields object

        Items in the field object are personalizable with handlebars.

        OBJECT PROPERTIES
        • alert string

          A string that override the alert value provided at the top level, if any.

        • icon string

          A string representing an image file included in the application’s resources.

        • icon_color string

          A string representing the icon color in API Color Format. i.e., #rrggbb

        • summary string

          A string representing a summary/subtitle of the notification.

        • title string

          A string representing the title of the notification. The default value is the name of the app.

Android override with template

Android override with a template

{
   "android": {
      "title": "Shoe sale on {{level}} floor!",
      "alert": "All the shoes are on sale {{name}}!",
      "summary": "Don't miss out!",
      "icon": "shoes",
      "icon_color": "{{iconColor}}",
      "extra": {
            "url": "http://example.com",
            "story_id": "1234",
            "moar": "{\"key\": \"value\"}"
      },
      "notification_channel": "promos"
   }
}

Android override with a template_id

{
   "android": {
      "title": "Shoe sale on {{level}} floor!",
      "alert": "All the shoes are on sale {{name}}!",
      "summary": "Don't miss out!",
      "icon": "shoes",
      "icon_color": "{{iconColor}}",
      "extra": {
            "url": "http://example.com",
            "story_id": "1234",
            "moar": "{\"key\": \"value\"}"
      },
      "notification_channel": "promos"
   }
}

{
   "android": {
      "template": {
            "template_id": "608f1f6c-8860-c617-a803-b187b491568e"
      },
      "extra": {
            "url": "http://example.com",
            "story_id": "1234",
            "moar": "{\"key\": \"value\"}"
      },
      "notification_channel": "promos"
   }
}

Use a template with an Android-specific fields. You can reference a template by ID, or use {{handlebars}} directly in your message.

OBJECT PROPERTIES
  • actions object<Actions>

    Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

  • category string

    Helps determine notification sort order. Available on Android Lollipop+.

    Possible values: alarm, call, email, err, event, msg, promo, recommendation, service, social, status, sys, transport

  • collapse_key string

    A key indicating that this message can replace, or be replaced by, another message with the same collapse_key. This feature comes into play when a device is offline (e.g., airplane mode) or in doze mode; if multiple messages are available with the same collapse_key when a device comes back online, it will display only the most recent message and discard previous messages using the same collapse_key.

  • delay_while_idle booleanDEPRECATED

    After November 15, 2016, this was still accepted by GCM, but ignored. When set to true, it indicates that the message should not be sent until the device becomes active. The default value is false.

  • deliver_to string

    Filters out Android channels that are not able to receive notifications. If the value is opted_in, the payload is only sent to opted-in devices. If the value is all, the payload is sent to opted-in and background enabled devices. Defaults to all if not provided.

    Possible values: all, opted_in

  • delivery_priority string

    Sets the FCM/GCM priority of the message. Defaults to normal if not provided.

    Possible values: high, normal

  • extra object

    A JSON dictionary of string-to-string key-value pairs. The keys from, message_type, data and keys that start with google or gcm are disallowed.

  • interactive object<Interactive notification object>

    An interactive notification.

    Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

  • local_only boolean

    If true, the notification is only shown on wearable devices.

  • notification_channel string

    A string representing a notification channel. Used to group notifications with similar behavior.

  • notification_tag string

    A string representing a notification tag. If a message is currently displaying and has a tag set, sending another message with the same tag will replace the posted notification. Similar to the iOS collapse_id.

  • priority integer

    An integer in the range from -2 to 2 inclusive. Used to help determine notification sort order. 2 is the highest priority, -2 is the lowest, and 0 is the default priority.

  • public_notification object

    An optional notification to show on lock screen instead of the redacted one. This is only useful with visibility set to -1 (private). The object may contain any of the following string fields title, alert, and summary.

    OBJECT PROPERTIES
    • alert string
    • summary string
    • title string
  • sound string

    A string representing a sound file name included in the application’s resources.

  • style object

    Advanced styles big text, big picture, and inbox are available on Android 4.3+ by adding the style to the platform specific notification payload on Android platforms. This object must contain a string field type which must be one of big_picture, big_text, or inbox. It may also contain title and summary override fields.

    OBJECT PROPERTIES
    • big_picture string

      If the type is set to big_picture, then there must also be a big_picture string field which contains the URL for an image.

    • big_text string

      If the type is set to big_text, then a big_text string field must be present with the text to be shown in big text style.

    • lines array[string]

      An array of strings if the type field is set to inbox.

    • summary string

      A string field which will override the summary of the notification.

    • title string

      A string field which will override the title of the notification.

    • type stringREQUIRED

      Possible values: big_picture, big_text, inbox

  • template object
    One of
    • OBJECT PROPERTIES
    • OBJECT PROPERTIES
      • fields object

        Items in the field object are personalizable with handlebars.

        OBJECT PROPERTIES
        • alert string

          A string that override the alert value provided at the top level, if any.

        • icon string

          A string representing an image file included in the application’s resources.

        • icon_color string

          A string representing the icon color in API Color Format. i.e., #rrggbb

        • summary string

          A string representing a summary/subtitle of the notification.

        • title string

          A string representing the title of the notification. The default value is the name of the app.

  • time_to_live object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • visibility integer

    An integer in the range from -1 to 1 inclusive. 1 = public (default), 0 = private, -1 = secret. Secret does not show any notifications. Private shows a redacted version of the notification.

    Possible values: -1, 0, 1

  • wearable object

    Provides options for messages displayed on wearable Android devices.

    OBJECT PROPERTIES
    • background_image string

      The URL to a background image to display on the wearable device.

    • extra_pages array[object]

      An array of objects, each with a title and alert string attributes specifying extra pages of text to appear as pages after the notification alert on the wearable device.

    • interactive object<Interactive notification object>

      An interactive notification.

      Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

Email notification with template

Example with inline template

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver"
        },
        "cart" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "message_type": "commercial",
      "sender_name": "Airship",
      "sender_address": "team@airship.com",
      "reply_to": "no-reply@airship.com",
      "template": {
        "fields": {
          "subject": "Hi {{customer.first_name}}, your products are ready!",
          "plaintext_body": "Hi {{customer.first_name}},/n Your order is ready for pickup at our {{customer.location}} store!/n Your order:/n {{#each cart}}{{this.qty}}x {{this.name}}/n{{/each}} Thanks,/n Your local AwesomeStore."
        }
      },
      "url_parameters": {
        "utm_source": "airship",
        "utm_channel": "email"
      }
    }
  }
}

Example with template_id

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver"
        },
        "cart" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "message_type": "commercial",
      "sender_name": "Airship",
      "sender_address": "team@airship.com",
      "reply_to": "no-reply@airship.com",
      "template": {
        "fields": {
          "subject": "Hi {{customer.first_name}}, your products are ready!",
          "plaintext_body": "Hi {{customer.first_name}},/n Your order is ready for pickup at our {{customer.location}} store!/n Your order:/n {{#each cart}}{{this.qty}}x {{this.name}}/n{{/each}} Thanks,/n Your local AwesomeStore."
        }
      },
      "url_parameters": {
        "utm_source": "airship",
        "utm_channel": "email"
      }
    }
  }
}

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver"
        },
        "cart" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "message_type": "commercial",
      "sender_name": "Airship",
      "sender_address": "team@airship.com",
      "reply_to": "no-reply@airship.com",
      "template": {
        "template_id": "9335bb2a-2a45-456c-8b53-42af7898236a"
      },
      "url_parameters": {
        "utm_source": "airship",
        "utm_channel": "email"
      }
    }
  }
}

Notification fields specific to email messages with an inline template for use in a Create and Send payload. Using a template enables you to provide and populate variables in your notification. You can also add conditional statements based on those variables, determining message text that to send to each member of your audience. Conditionals begin with {{#operator}} and end with {{/operator}}. For more information, see Handlebars.

OBJECT PROPERTIES
  • bcc array[string]

    An array of email addresses that you want to blind copy on this email. Contact your Account Manager to enable BCC addresses. Using addresses that your Airship Account Manager has not enabled for BCC will return a 400.

  • click_tracking boolean

    True by default. Set to false to prevent click tracking for GDPR compliance.

  • message_type stringREQUIRED

    The type of email you are sending, transactional or commercial.

    Possible values: transactional, commercial

  • open_tracking boolean

    True by default. Set to false to prevent open tracking for GDPR compliance.

  • reply_to stringREQUIRED

    The reply-to address. The username portion of the reply-to address can be set dynamically using Handlebars. The domain portion of the reply-to address can be any correctly formatted domain.

  • sender_address stringREQUIRED

    The email address of the sender. The domain of the email must be enabled in the email provider at the delivery tier (ie: SparkPost). The username portion of the sender address can be set dynamically using Handlebars. The domain portion of the sender address must match one of your project’s configured email sending domains.

  • sender_name stringREQUIRED

    The common name for the sender, visible to email recipients. The sender name can be set dynamically using Handlebars.

  • template objectREQUIRED

    Specify a template_id created in the Airship UI or use an inline template.

    One of
    • OBJECT PROPERTIES
    • OBJECT PROPERTIES
      • fields objectREQUIRED

        The template you want to construct for the message. Provide variables in the template in double curly brackets — {{variable_name}}. The variable name must be a case-sensitive match of a key in your create_and_send objects to be replaced as a part of the template.

        OBJECT PROPERTIES
        • html_body string

          The rich-text HTML body of the email, no larger than 100 KB.

          • When "message_type": "commercial", the body must contain an unsubscribe link in the format <a data-ua-unsubscribe=“1” title=“unsubscribe”>Unsubscribe</a>. You can send the user to a custom “goodbye” page by providing an href attribute in the link: <a data-ua-unsubscribe=“1” title=“unsubscribe” href=“YOUR_URL”>Unsubscribe</a>. If your unsubscribe link includes an href, Airship unsubscribes the user before redirecting to your page. Additionally, <a data-ua-opt-in=“1” title=“subscribe”>Subscribe and <a data-ua-opt-in=“1” title subscribe" href=“YOUR_URL_HERE”>Subscribe will be replaced by a link that will opt the user in to both commercial and transactional messaging and optionally redirect the user to a customer-supplied landing page.
          • See Email image recommendations.

        • plaintext_body stringREQUIRED

          The plain text body of the email, no larger than 100 KB.

          When "message_type": "commercial", the body must contain a [[ua_unsubscribe]] link, which will be replaced by the unsubscribe link in Airship. You can send the user to a custom “goodbye” page by providing an href in the format [[ua-unsubscribe href=“your url here”]]. If you include an href, Airship unsubscribes the user before redirecting to your page. Additionally, [[ua-opt-in]] and [[ua-opt-in href=“YOUR_URL_HERE”]] will be replaced by a link that will opt the user in to both commercial and transactional messaging and optionally redirect the user to a customer-supplied landing page.

        • subject stringREQUIRED

          The subject line of the email you want to send.

  • url_parameters object

    A JSON dictionary of string-to-string key-value pairs as UTM or custom parameters. Each key and value will become a query parameter key and URL-encoded value that are automatically appended to all link URLs in an email. These parameters are used for tracking campaign performance.

    If a query parameter defined in this object already exists in a link, it will not be overwritten in the link. Dynamic values are supported using Handlebars, with limitations. See URL parameters in the Email content guide for more information.

iOS override with template

iOS override with a template

{
   "ios": {
      "thread_id": "sfGiants_news",
      "title": "{{NAME}} Throws a Perfect Game",
      "body": "{{NAME}} stymies the {{OTHER_TEAM}} for San Francisco's first perfect game in franchise history.",
      "subtitle": "San Francisco Giants {{DATE}}",
      "sound": "strike-call",
      "media_attachment": {
         "content": {
            "title": "Kevin Gausman",
            "body": "Gausman strikes out Justin Turner"
         },
         "options": {
            "crop": {
               "height": 0.5,
               "width": 0.5,
               "x": 0.25,
               "y": 0.25
            },
            "time": 15
         },
         "url": "https://media.example.com/media/6nJmrhlu4aL1m/giphy.gif"
      },
      "mutable_content": 1
   }
}

iOS override with a template_id

{
   "ios": {
      "thread_id": "sfGiants_news",
      "title": "{{NAME}} Throws a Perfect Game",
      "body": "{{NAME}} stymies the {{OTHER_TEAM}} for San Francisco's first perfect game in franchise history.",
      "subtitle": "San Francisco Giants {{DATE}}",
      "sound": "strike-call",
      "media_attachment": {
         "content": {
            "title": "Kevin Gausman",
            "body": "Gausman strikes out Justin Turner"
         },
         "options": {
            "crop": {
               "height": 0.5,
               "width": 0.5,
               "x": 0.25,
               "y": 0.25
            },
            "time": 15
         },
         "url": "https://media.example.com/media/6nJmrhlu4aL1m/giphy.gif"
      },
      "mutable_content": 1
   }
}

{
   "ios": {
      "template": {
            "template_id": "608f1f6c-8860-c617-a803-b187b491568e"
      }
   }
}

Use a template with iOS-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

OBJECT PROPERTIES
  • actions object<Actions>

    Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

  • badge integer

    May be an integer, the value auto, or an increment value. Increments are expressed by integers formatted as strings, and prefixed with either + (U+002B) or - (U+002D). The numeric portion may be an integer value.

  • category string

    Sets the APNs category for the push. This maps directly to the category field in the aps section of the APNs payload. Any interactive notification specified for the IOS platform will take precedence and this value will be ignored (the interactive notification type will be used for the category).

  • collapse_id string

    When there is a newer message that renders an older, related message irrelevant to the client app, the new message replaces the older message with the same collapse_id. Similar to the Android notification_tag. The value of this key must not exceed 64 bytes. iOS 10 or above.

  • content_available boolean

    If true, the payload is delivered to your app in the background.

    This flag is automatically set to true if there is an In-App Message in the payload. Attempting to override this value to false when there is an in-app message will result in a 400 Bad Request response from the API.

  • expiry object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • extra object

    A dictionary of string keys to arbitrary JSON values. The key aps would conflict with the generated APNs payload and is disallowed.

  • interactive object<Interactive notification object>

    An interactive notification.

    Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

  • media_attachment object

    The media_attachment key on the iOS override is a JSON object that describes a media attachment to be handled by the Airship Media Attachment extension in iOS 10.

    OBJECT PROPERTIES
    • content object

      A JSON object that describes portions of the notification that should be modified if the media attachment succeeds, with any of the following fields.

      OBJECT PROPERTIES
      • body string
      • subtitle string
      • title string
    • options object

      A JSON object that describes how to display the resource at the URL specified above, with any of the following fields.

      OBJECT PROPERTIES
      • crop object

        A JSON object that describes the crop parameters to be used in the thumbnail. Each field is a decimal, normalized from 0 to 1. Before displaying the thumbnail, iOS additionally crops the thumbnail down to a square. See: Media guidelines.

        OBJECT PROPERTIES
        • height number

          The height of the final crop.

        • width number

          The width of the final crop.

        • x number

          The X offset where the crop begins.

        • y number

          The Y offset where the crop begins.

      • hidden boolean

        A boolean, when true, the thumbnail will be hidden.

      • time integer

        A decimal, the frame of the animated resource that should be used in the thumbnail . For GIFs, this value should be the frame number (an integer, with the first frame being frame 1) to show in the thumbnail. For video, the value should be the time (in seconds) into the video from which to grab the thumbnail. This value should not be set for static resources like JPGs. If the time does not exist in the resource, either because it is out of bounds or because the resource is static, the thumbnail will not show.

    • url stringREQUIRED

      The URL to be downloaded by the Airship Media Attachment extension. The media file should be one of the following types, and not exceed the maximum file size. Image (5 MB): JPEG, GIF, PNG. Audio (10 MB): AIFF, WAV, MP3, M4A. Video (50 MB): MPEG, MPEG2, MP4, AVI. Although these are the theoretical file size maximums, for performance the actual resources should be much smaller. See Media Guidelines.

  • mutable_content boolean

    When set to true, content may be modified by an extension. This flag will be automatically set to true if there is a media_attachment in the payload. iOS 10 or above. Defaults to false.

  • priority integer

    Sets the APNs priority of the delivery. Valid values are 10 (immediate delivery) and 5 (conserve battery). The default value will be 10 if the notification is user-visible (In-App Message payload does not count towards visibility) which means there is either an alert, badge, or sound. If the notification is not user-visible, the priority will default to 5 and it is not legal to override this value to 10. Attempts to do so will cause the API respond with a 400 Bad Request response. enum: [5, 10]

  • sound string

    The name of the sound file in your app’s bundle that you want to play for the alert. If the notification is critical, the dictionary has a key for "name" (equivalent to the current sound string), "volume" (a number between 0 and 1 indicating the volume), and "critical" (a boolean indicating if the alert should override local device settings and still notify).

  • template object
    One of
    • OBJECT PROPERTIES
    • OBJECT PROPERTIES
      • fields object

        Items in the field object are personalizable with handlebars.

        OBJECT PROPERTIES
        • alert string

          Alert override text for iOS devices.

        • subtitle string

          A string that will display below the title of the notification. This is provided as a convenience for setting the subtitle in the alert JSON object. If a subtitle is also defined in the alert JSON object, this value is ignored. iOS 10.

        • title string

          A short string describing the purpose of the notification. This is provided as a convenience for setting the title in the alert JSON object. If a title is also defined in the alert JSON object, this value is ignored.

  • thread_id string

    A unique identifier used to group notifications into separate threads in the Notification Center and on the lock screen. Grouped notifications are available beginning with iOS 12.

Message Center with template

Message Center with template using handlebars example

{
   "message": {
      "title": "Save on {{product}} through {{end_date}}!",
      "body": "<html><body><h1>here's a cool {{offer}}</h1> etc...</html>",
      "content_type": "text/html",
      "expiry": "2020-04-01T12:00:00",
      "extra": {
         "offer_id": "608f1f6c-8860-c617-a803-b187b491568e"
      },
      "icons": {
         "list_icon": "http://cdn.example.com/message.png"
      }
   }
}

Message Center with template by ID example

{
   "message": {
      "title": "Save on {{product}} through {{end_date}}!",
      "body": "<html><body><h1>here's a cool {{offer}}</h1> etc...</html>",
      "content_type": "text/html",
      "expiry": "2020-04-01T12:00:00",
      "extra": {
         "offer_id": "608f1f6c-8860-c617-a803-b187b491568e"
      },
      "icons": {
         "list_icon": "http://cdn.example.com/message.png"
      }
   }
}

{
   "message": {
      "template": {
         "template_id": "my_template_id"
      }
   }
}

Use a template with a message center message. You can reference a template by ID, or use {{handlebars}} directly in your message.

OBJECT PROPERTIES
  • content_encoding string

    A string denoting encoding type of the data in body. Defaults to utf-8. base64 encoding can be used in cases which would be complex to escape properly, just as HTML containing embedded javascript code, which itself may contain embedded JSON data.

  • content_type string

    A string denoting the MIME type of the data in body. Defaults to text/html.

  • expiry object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • extra object

    A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.

  • icons object

    A JSON dictionary of string key and value pairs representing icons. At this time, only the list_icon key is supported. Values must be URI/URLs to icon resources. For resources hosted by UA, use the following URI format ua:<resource_id>.

    OBJECT PROPERTIES
    • list_icon string
  • template object
    One of
    • OBJECT PROPERTIES
    • OBJECT PROPERTIES
      • fields object

        Items in the field object are personalizable with handlebars.

        OBJECT PROPERTIES
        • html_body string

          The body of the message. This can be a full HTML message.

        • title string

          The title of the message.

MMS notification with inline template

Example object with merge fields in audience object

{
  "audience": {
    "create_and_send" : [
      {
        "ua_sender" : "12345",
        "ua_msisdn" : "15558675309",
        "ua_opted_in" : "2020-08-30T22:35:00",
        "delivery_image": "url",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver"
        },
        "order" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "mms" ],
  "notification" : {
    "mms" : {
      "subject" : "Your order is on the way!",
      "fallback_text": "Hi, {{customer.first_name}}, your {{#each order}}{{order.name}}{{/each}} just shipped",
      "slides": [
        {
          "media": {
            "url": "https://www.example.com/order12345.jpg",
            "content_type": "image/jpeg",
            "content_length": 123100
          },
          "text": "Hi, {{customer.first_name}}, your {{#each order}}{{order.name}}{{/each}} just shipped."
        }
      ]
    }
  }
}

Example with inline template

{
  "audience": {
    "create_and_send" : [
      {
        "ua_sender" : "12345",
        "ua_msisdn" : "15558675309",
        "ua_opted_in" : "2020-08-30T22:35:00",
        "delivery_image": "url",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver"
        },
        "order" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "mms" ],
  "notification" : {
    "mms" : {
      "subject" : "Your order is on the way!",
      "fallback_text": "Hi, {{customer.first_name}}, your {{#each order}}{{order.name}}{{/each}} just shipped",
      "slides": [
        {
          "media": {
            "url": "https://www.example.com/order12345.jpg",
            "content_type": "image/jpeg",
            "content_length": 123100
          },
          "text": "Hi, {{customer.first_name}}, your {{#each order}}{{order.name}}{{/each}} just shipped."
        }
      ]
    }
  }
}

{
  "audience": {
    "create_and_send" : [
      {
        "ua_sender" : "12345",
        "ua_msisdn" : "15558675309",
        "ua_opted_in" : "2020-08-30T22:35:00",
        "delivery_image": "https://www.example.com/order12345.jpg",
        "content-length": "1234567",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver"
        },
        "order" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "mms" ],
  "notification" : {
    "mms" : {
      "subject": "Your order is on the way!",
      "fallback_text": "Hi, {{customer.first_name}}, your {{#each order}}{{order.name}}{{/each}} was delivered!",
      "slides": [
        {
          "media": {
            "url": "https://www.example.com/order12345.jpg",
            "content_type": "image/jpeg",
            "content_length": 123100
          },
          "text" : "Hi, {{customer.first_name}}, your {{#each order}}{{order.name}}{{/each}} was delivered!"
        }
      ]
    }
  }
}

Example with template_id

{
  "audience": {
    "create_and_send" : [
      {
        "ua_sender" : "12345",
        "ua_msisdn" : "15558675309",
        "ua_opted_in" : "2020-08-30T22:35:00",
        "delivery_image": "url",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver"
        },
        "order" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "mms" ],
  "notification" : {
    "mms" : {
      "subject" : "Your order is on the way!",
      "fallback_text": "Hi, {{customer.first_name}}, your {{#each order}}{{order.name}}{{/each}} just shipped",
      "slides": [
        {
          "media": {
            "url": "https://www.example.com/order12345.jpg",
            "content_type": "image/jpeg",
            "content_length": 123100
          },
          "text": "Hi, {{customer.first_name}}, your {{#each order}}{{order.name}}{{/each}} just shipped."
        }
      ]
    }
  }
}

{
  "audience": {
    "create_and_send" : [
      {
        "ua_sender" : "12345",
        "ua_msisdn" : "15558675309",
        "ua_opted_in" : "2020-08-30T22:35:00",
        "delivery_image": "https://www.example.com/order12345.jpg",
        "content-length": "1234567",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver"
        },
        "order" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "mms" ],
  "notification" : {
    "mms" : {
      "subject": "Your order is on the way!",
      "fallback_text": "Hi, {{customer.first_name}}, your {{#each order}}{{order.name}}{{/each}} was delivered!",
      "slides": [
        {
          "media": {
            "url": "https://www.example.com/order12345.jpg",
            "content_type": "image/jpeg",
            "content_length": 123100
          },
          "text" : "Hi, {{customer.first_name}}, your {{#each order}}{{order.name}}{{/each}} was delivered!"
        }
      ]
    }
  }
}

{
  "audience": {
    "create_and_send" : [
      {
        "ua_sender" : "12345",
        "ua_msisdn" : "15558675309",
        "ua_opted_in" : "2020-08-30T22:35:00",
        "delivery_image": "https://www.example.com/order12345.jpg",
        "content-length": "1234567",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver"
        },
        "order" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "mms" ],
  "notification" : {
    "mms" : {
      "template" : {
        "template_id" : "9335bb2a-2a45-456c-8b53-42af7898236a"
      },
      "slides": [
        {
          "media": {
            "url": "https://cdn.example.com/coolImage.jpg",
            "content_type": "image/jpeg",
            "content_length": 123100
          }
        }
      ]
    }
  }
}

Template and notification overrides for a Create and Send payload with device_types set to mms. With a template, you can provide and populate variables and conditional statements based on those variables. Conditionals begin with {{#operator}} and end with {{/operator}}. For more information, see Handlebars.

OBJECT PROPERTIES
  • slides array[object]

    An array containing a single slide object. A slide is a multimedia object.

  • template object

    Specify a template_id created in the Airship UI or use an inline template.

    One of
    • OBJECT PROPERTIES
    • OBJECT PROPERTIES
      • fields object
        OBJECT PROPERTIES
        • fallback_text stringREQUIRED

          If a member of your audience cannot receive MMS messages, they will receive your fallback text with a link to the original content.

        • subject string

          The subject for the MMS message, normally displayed in bold. The subject might not appear for recipients if the Sender is a Toll-Free number. An empty string is valid.

        • text object

          Text that you want to display along with the media attachment. The order of media and text in the message is not guaranteed.

Open channel override with template

Use a template with an open channel-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

OBJECT PROPERTIES
  • extra object

    A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.

  • interactive object<Interactive notification object>

    An interactive notification.

    Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

  • template objectREQUIRED
    One of
    • OBJECT PROPERTIES
    • OBJECT PROPERTIES
      • fields object
        OBJECT PROPERTIES
        • alert string

          Override the alert value provided at the top level, if any.

        • media_attachment string

          A URI for an image or video somewhere on the internet.

        • summary string

          A string value for providing a content summary.

        • title string

          A string representing the title of the notification.

SMS notification with template

Example object with merge fields in audience object

{
  "audience": {
    "create_and_send" : [
      {
        "ua_sender" : "12345",
        "ua_msisdn" : "15558675309",
        "ua_opted_in" : "2020-08-30T22:35:00",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver"
        },
        "cart" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "sms" ],
  "notification" : {
    "sms" : {
      "alert" : "Hi, {{customer.first_name}}, your {{#each cart}}{{this.name}}{{/each}} are ready to pickup at our {{customer.location}} location!"
    }
  },
  "campaigns" : {
    "categories" : [ "order-pickup" ]
  }
}

Example object with template_id

{
  "audience": {
    "create_and_send" : [
      {
        "ua_sender" : "12345",
        "ua_msisdn" : "15558675309",
        "ua_opted_in" : "2020-08-30T22:35:00",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver"
        },
        "cart" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "sms" ],
  "notification" : {
    "sms" : {
      "alert" : "Hi, {{customer.first_name}}, your {{#each cart}}{{this.name}}{{/each}} are ready to pickup at our {{customer.location}} location!"
    }
  },
  "campaigns" : {
    "categories" : [ "order-pickup" ]
  }
}

{
  "audience": {
    "create_and_send" : [
      {
        "ua_sender" : "12345",
        "ua_msisdn" : "15558675309",
        "ua_opted_in" : "2020-08-30T22:35:00",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver"
        },
        "cart" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "sms" ],
  "notification" : {
    "sms" : {
      "template" : {
        "template_id": "9335bb2a-2a45-456c-8b53-42af7898236a"
      }
    }
  }
}

Notification fields specific to SMS messages with an inline template for use in a Create and Send payload. Using a template enables you to provide and populate variables in your notification. You can also add conditional statements based on those variables, determining message text that to send to each member of your audience. Conditionals begin with {{#operator}} and end with {{/operator}}. For more information, see Handlebars.

OBJECT PROPERTIES
  • expiry object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • template objectREQUIRED

    Specify a template_id created in the Airship UI or use an inline template.

    One of
    • OBJECT PROPERTIES
    • OBJECT PROPERTIES
      • fields object

        The template you want to construct for the message. Provide variables in the template in double curly brackets — {{variable_name}}. The variable name must be a case-sensitive match of a key in your create_and_send objects to be replaced as a part of the template.

        OBJECT PROPERTIES
        • alert stringREQUIRED

          The notification you want to send to an SMS audience.

Web override with template

Web override with a template

{
   "web": {
      "alert": "Vote now, {{name}}!",
      "title": "Geese? Or ducks!",
      "icon": "{{icon}}",
      "require_interaction": true,
      "buttons": [
         {
            "id": "yes",
            "label": "Yes",
            "actions": {
               "open": {
                  "type": "home"
               },
               "add_tag": ["new_tag"]
            }
         },
         {
         "id": "no",
         "label": "No"
         }
      ],
      "extra": {
         "story_id": "1234",
         "moar": "{\"key\": \"value\"}"
      }
   }
}

Web override with a template_id

{
   "web": {
      "alert": "Vote now, {{name}}!",
      "title": "Geese? Or ducks!",
      "icon": "{{icon}}",
      "require_interaction": true,
      "buttons": [
         {
            "id": "yes",
            "label": "Yes",
            "actions": {
               "open": {
                  "type": "home"
               },
               "add_tag": ["new_tag"]
            }
         },
         {
         "id": "no",
         "label": "No"
         }
      ],
      "extra": {
         "story_id": "1234",
         "moar": "{\"key\": \"value\"}"
      }
   }
}

{
   "web": {
      "template": {
         "template_id": "1ad69081-c196-af21-41dc-53bc89a2edc5"
      },
      "require_interaction": true,
      "extra": {
         "story_id": "1234",
         "moar": "{\"key\": \"value\"}"
      }
   }
}

Use a template with a Web-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

Safari behaves differently from other browsers and supports only the alert and title overrides. It ignores all other web overrides.

OBJECT PROPERTIES
  • actions object<Actions>

    Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

  • buttons array[object]

    Contains one or two buttons that perform actions for the web notification. If you do not specify actions for a button, the button closes the notification without performing an action.

  • extra object

    A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.

  • icon object

    A JSON object that describes an icon to be used with the notification.

    OBJECT PROPERTIES
    • url stringREQUIRED

      The URL to be used for the icon.

  • image object

    A JSON object that describes an image to be used with the web alert.

    OBJECT PROPERTIES
    • url stringREQUIRED

      The URL to be used for the image.

  • require_interaction boolean

    If true, a feature that requires a user to interact with the notification in order to remove it from their computer screen.

  • template object
    One of
    • OBJECT PROPERTIES
    • OBJECT PROPERTIES
      • fields object

        Items in the field object are personalizable with handlebars.

        OBJECT PROPERTIES
        • alert string

          Override the alert value provided at the top level, if any.

        • icon object

          A JSON object that describes a icon to be used with the web alert.

          OBJECT PROPERTIES
          • url stringREQUIRED

            The URL to be used for the icon.

        • title string

          A string representing the title of the notification.

  • time_to_live object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of

Audience selection

Objects that help you select and target an audience.

Atomic selector

Example audience selection by tag

{
   "audience": {
      "tag": "sfGiants",
      "group": "favorite_teams"
   }
}

Example SMS channel audience

{
   "audience": {
      "tag": "sfGiants",
      "group": "favorite_teams"
   }
}

{
    "audience" : {
        "sms_id" :  {
            "sender" : "12345",
            "msisdn" : "15552243311"
        }
    }
}

Example audience segment

{
   "audience": {
      "tag": "sfGiants",
      "group": "favorite_teams"
   }
}

{
    "audience" : {
        "sms_id" :  {
            "sender" : "12345",
            "msisdn" : "15552243311"
        }
    }
}

{
    "audience" : {
        "segment" : "<segment-id>"
    }
}

Example audience of Named Users

{
   "audience": {
      "tag": "sfGiants",
      "group": "favorite_teams"
   }
}

{
    "audience" : {
        "sms_id" :  {
            "sender" : "12345",
            "msisdn" : "15552243311"
        }
    }
}

{
    "audience" : {
        "segment" : "<segment-id>"
    }
}

{
   "audience" : {
      "named_user" : "user-id-54320"
   }
}

Example audience of static list

{
   "audience": {
      "tag": "sfGiants",
      "group": "favorite_teams"
   }
}

{
    "audience" : {
        "sms_id" :  {
            "sender" : "12345",
            "msisdn" : "15552243311"
        }
    }
}

{
    "audience" : {
        "segment" : "<segment-id>"
    }
}

{
   "audience" : {
      "named_user" : "user-id-54320"
   }
}

{
   "audience" : {
      "static_list" : "name_of_list"
   }
}

Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.

One of
  • string

    The simplest selector, which targets the entire audience.

  • Tag selector object

    A tag is an arbitrary bit of metadata used for targeting devices. A tag specifier may or may not have an associated group declaration, indicating a tag group the tag belongs to, for example, {"tag": "silver-member", "group": "loyalty"}. If no tag group is specified, the default device group is used.

    OBJECT PROPERTIES
    • group string
    • tag objectREQUIRED
      One of
      • string
      • array<string>

        Min items: 1, Max items: 100

  • Segment selector object

    The Segment ID.

    OBJECT PROPERTIES
    • segment objectREQUIRED
      One of
      • string
      • array<string>

        Min items: 1, Max items: 100

  • Channel selector object

    The unique channel identifier used to target an open channel device or web device, i.e., web browser.

    OBJECT PROPERTIES
    • channel objectREQUIRED
      One of
      • string
      • array<string>

        Min items: 1, Max items: 100

  • Named User selector object

    A named_user is an alternate, non-unique name, mapped to a user profile in a different database, e.g., CRM, that can be used to target devices associated with that profile.

    OBJECT PROPERTIES
    • named_user objectREQUIRED
      One of
      • string
      • array<string>

        Min items: 1, Max items: 100

  • Fire OS channel selector object

    The unique channel identifier used to target a Fire OS device.

    OBJECT PROPERTIES
    • amazon_channel objectREQUIRED
      One of
      • string
      • array<string>

        Min items: 1, Max items: 100

  • Android channel selector object

    The unique channel identifier used to target an Android device.

    OBJECT PROPERTIES
    • android_channel objectREQUIRED
      One of
      • string
      • array<string>

        Min items: 1, Max items: 100

  • Open channel selector object

    The unique channel identifier used to target a device on an open platform.

    OBJECT PROPERTIES
    • open_channel objectREQUIRED
      One of
      • string
      • array<string>

        Min items: 1, Max items: 100

  • string

    A long or short code the app is configured to send from. For example, 12345.

  • SMS ID selector object

    Selects a single SMS device. The msisdn must be opted_in to receive notifications.

    OBJECT PROPERTIES
    • msisdn stringREQUIRED

      The recipient phone number.

    • sender stringREQUIRED

      The sender that the app is configured to send SMS messages from.

  • Static list selector object

    A static_list is a subset of your audience defined by a CSV file containing Channel IDs or Named Users.

    OBJECT PROPERTIES
    • static_list objectREQUIRED
      One of
      • string
      • array<string>

        Min items: 1, Max items: 100

  • Subscription List selector object

    An single instance or array of subscription list IDs.

    OBJECT PROPERTIES
    • subscription_list objectREQUIRED
      One of
      • string
      • array<ref>
  • Text Attribute

    An attribute object with a TEXT schema type. Evaluates for the inclusion or exclusion of a text (string) attribute on a channel or Named User.

  • Number Attribute

    An attribute object with a NUMBER schema type. Performs value comparisons based on the number value for an attribute on a channel or Named User.

  • Date Attribute

    An attribute object with a DATE schema type. Performs absolute date comparisons for ISO-formatted date values or a relative date comparisons given an integer value and precision, e.g., days, months. Use a date attribute to target a channel or Named User based on the date values.

  • Json Attribute

    An attribute object with a JSON schema type. Performs value comparisons based on the JSON value for an attribute on a channel or Named User.

  • Alias selector object

    A legacy mechanism used for mapping devices to a customer ID, e.g., a CRM identifier. Superseded by named_user.

    OBJECT PROPERTIES
    • alias objectREQUIRED
      One of
      • string
      • array<string>

        Min items: 1, Max items: 100

  • APID selector object

    A legacy identifier for targeting Android and Windows devices, superseded by android_channel.

    OBJECT PROPERTIES
    • apid objectREQUIRED
      One of
      • string
      • array<string>

        Min items: 1, Max items: 100

  • Activity Object

    The activity object defines the target audience based on lifecycle actions or Custom Event activity, using comparison operators on activity count and recency. Optionally include a where object, which filters for specific activity values.

    In the example to the right, the target audience is users who have opened your app from a notification from the “neowise” campaign at least twice, 3 days ago.

  • string

    A special selector used in Pipelines to indicate that the audience of the push is composed of the device or devices that activated the trigger. See Pipeline objects for more information.

Audience selector (max 100)

An audience selector forms the expression that determines the set of channels to target.

One of
  • Compound Selector

    Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

  • Atomic Selector

    Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.

Audience selector (max 1000)

An audience selector forms the expression that determines the set of channels to target.

One of
  • Compound Selector

    Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

  • Atomic Selector

    Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.

Compound selector

Example with implicit `OR`

{
   "audience" : {
      "tag" : ["apples", "oranges", "bananas"]
   }
}

Example with nested selectors

{
   "audience" : {
      "tag" : ["apples", "oranges", "bananas"]
   }
}

{
   "audience": {
      "AND": [
         {"OR": [
            {"tag": "sports"},
            {"tag": "entertainment"}
         ]},
         {"tag": "language_en"}
      ]
   }
}

Example `NOT` selector

{
   "audience" : {
      "tag" : ["apples", "oranges", "bananas"]
   }
}

{
   "audience": {
      "AND": [
         {"OR": [
            {"tag": "sports"},
            {"tag": "entertainment"}
         ]},
         {"tag": "language_en"}
      ]
   }
}

{
   "audience": {
      "AND": [
         { "tag": "Federer fan" },
         { "NOT":
            { "tag": "Messi fan" }
         }
      ]
   }
}

Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

One of
  • AND selector object

    AND selector

    OBJECT PROPERTIES
    • AND array
  • OR Selector object

    OR selector

    OBJECT PROPERTIES
    • OR array
  • NOT Selector object

    NOT selector

    OBJECT PROPERTIES
    • NOT object
      One of
      • Compound Selector

        Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

      • Atomic Selector

        Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.

Attributes

Attributes appear on channels and Named Users. You can target an audience using attribute selectors. Available attribute types are Text, Number, Date, and JSON.

Custom and predefined Attributes

Example Attributes object

{
   "device_attributes": {
      "ua_device_os": "10",
      "ua_country": "US",
      "ua_device_model": "SM-G973U",
      "ua_local_tz": "America/Los_Angeles",
      "ua_app_version": "2020-02-01T002322-goat",
      "ua_location_settings": "true",
      "ua_language": "en",
      "ua_sdk_version": "13.1.0",
      "ua_carrier": "Verizon "
   },
   "attributes": {
      "first_name": "Cool",
      "last_name": "Person",
      "birthdate": "1983-03-15T00:00:00",
   }
}

Attributes associated with a channel or Named User. This object contains predefined attributes that you enable and assign to the channel, or custom attributes that you create and assign.

This object enumerates predefined attributes, but you can create your own in the Airship dashboard.

OBJECT PROPERTIES
  • account_creation string

    The date-time when the user created their account.

  • advertising_id string

    The IDFA associated with a user.

  • age integer

    The user’s age.

  • altitude number

    The altitude associated with a user.

  • birthdate string

    The user’s birthdate.

  • city string

    The city associated with the user.

  • company string

    The company that a user is associated with.

  • country string

    The country associated with the user.

  • email string

    A user’s email address.

  • first_name string

    The first name of a user.

  • full_name string

    A user’s first and last names.

  • gender string

    A user’s gender.

  • home_phone integer

    The user’s home phone number — similar to an SMS channel msisdn.

  • last_name string

    The last name of a user.

  • latitude number

    The latitude associated with a user — maybe their default location.

  • longitude number

    The longitude associated with a user — maybe their default location.

  • loyalty_tier string

    The loyalty program tier that a user is associated with, e.g., gold, platinum, etc.

  • mobile_phone integer

    The user’s mobile phone number — similar to an SMS channel msisdn.

  • region string

    The state, province, principality, etc. associated with the user.

  • title string

    A default attribute. You must enable this attribute in the dashboard before you can assign it.

  • username string

    A user’s username — generally a part of their login information.

  • work_phone integer

    The user’s work phone number — similar to an SMS channel msisdn.

  • zipcode integer

    A user’s zipcode. This is different from the SMS channel ua_ndc attribute, that records user’s area code or phone number prefix.

  • * object
    One of
    • string

Attribute assignment

Attributes assignment

{
  "attributes": [
    {
      "action": "remove",
      "key": "minor_league"
    },
    {
      "action": "set",
      "key": "position",
      "value": "LF"
    }
  ]
}
OBJECT PROPERTIES
  • attributes arrayREQUIRED

    The attributes that you want to set for, or remove from, your audience. You can have both set and remove actions in the same request.

Date Attribute selector

Date Attribute example

{ "audience":
   {
      "attribute": "birth_date",
      "operator": "equals",
      "precision": "month_day",
      "value": "05-04"
   }
}

Add four days to the current date

{ "audience":
   {
      "attribute": "birth_date",
      "operator": "equals",
      "precision": "month_day",
      "value": "05-04"
   }
}

{ "audience":
   {
      "attribute": "day_of_travel",
      "operator": "equals",
      "value": "4",
      "precision": "days",
      "relative_to": "future"
   }
}

Compound selector using before and after date operators

{ "audience":
   {
      "attribute": "birth_date",
      "operator": "equals",
      "precision": "month_day",
      "value": "05-04"
   }
}

{ "audience":
   {
      "attribute": "day_of_travel",
      "operator": "equals",
      "value": "4",
      "precision": "days",
      "relative_to": "future"
   }
}

{
   "audience": {
      "AND": [
            {
               "attribute": "birth_date",
               "operator": "after",
               "value": 55,
               "precision": "years"
            },
            {
               "attribute": "birth_date",
               "operator": "before",
               "value": 40,
               "precision": "years"
            }
      ]
   },
   "device_types": [
      "android"
   ],
   "notification": {
      "alert": "Hello, Generation X!"
   }
}

Audience who purchased jeans

{ "audience":
   {
      "attribute": "birth_date",
      "operator": "equals",
      "precision": "month_day",
      "value": "05-04"
   }
}

{ "audience":
   {
      "attribute": "day_of_travel",
      "operator": "equals",
      "value": "4",
      "precision": "days",
      "relative_to": "future"
   }
}

{
   "audience": {
      "AND": [
            {
               "attribute": "birth_date",
               "operator": "after",
               "value": 55,
               "precision": "years"
            },
            {
               "attribute": "birth_date",
               "operator": "before",
               "value": 40,
               "precision": "years"
            }
      ]
   },
   "device_types": [
      "android"
   ],
   "notification": {
      "alert": "Hello, Generation X!"
   }
}

{ "audience":
   {
      "attribute": "item_purchased",
      "operator": "contains",
      "value": "jeans"
   }
}

Audience who did not purchase jeans

{ "audience":
   {
      "attribute": "birth_date",
      "operator": "equals",
      "precision": "month_day",
      "value": "05-04"
   }
}

{ "audience":
   {
      "attribute": "day_of_travel",
      "operator": "equals",
      "value": "4",
      "precision": "days",
      "relative_to": "future"
   }
}

{
   "audience": {
      "AND": [
            {
               "attribute": "birth_date",
               "operator": "after",
               "value": 55,
               "precision": "years"
            },
            {
               "attribute": "birth_date",
               "operator": "before",
               "value": 40,
               "precision": "years"
            }
      ]
   },
   "device_types": [
      "android"
   ],
   "notification": {
      "alert": "Hello, Generation X!"
   }
}

{ "audience":
   {
      "attribute": "item_purchased",
      "operator": "contains",
      "value": "jeans"
   }
}

{ "audience":
   {
      "NOT":{
         "attribute": "item_purchased",
         "operator": "contains",
         "value": "jeans"
      }
   }
}

Audience who did not make any purchase

{ "audience":
   {
      "attribute": "birth_date",
      "operator": "equals",
      "precision": "month_day",
      "value": "05-04"
   }
}

{ "audience":
   {
      "attribute": "day_of_travel",
      "operator": "equals",
      "value": "4",
      "precision": "days",
      "relative_to": "future"
   }
}

{
   "audience": {
      "AND": [
            {
               "attribute": "birth_date",
               "operator": "after",
               "value": 55,
               "precision": "years"
            },
            {
               "attribute": "birth_date",
               "operator": "before",
               "value": 40,
               "precision": "years"
            }
      ]
   },
   "device_types": [
      "android"
   ],
   "notification": {
      "alert": "Hello, Generation X!"
   }
}

{ "audience":
   {
      "attribute": "item_purchased",
      "operator": "contains",
      "value": "jeans"
   }
}

{ "audience":
   {
      "NOT":{
         "attribute": "item_purchased",
         "operator": "contains",
         "value": "jeans"
      }
   }
}

{ "audience":
   {
      "attribute": "item_purchased",
      "operator": "is_empty",
   }
}

Integer value range

{ "audience":
   {
      "attribute": "birth_date",
      "operator": "equals",
      "precision": "month_day",
      "value": "05-04"
   }
}

{ "audience":
   {
      "attribute": "day_of_travel",
      "operator": "equals",
      "value": "4",
      "precision": "days",
      "relative_to": "future"
   }
}

{
   "audience": {
      "AND": [
            {
               "attribute": "birth_date",
               "operator": "after",
               "value": 55,
               "precision": "years"
            },
            {
               "attribute": "birth_date",
               "operator": "before",
               "value": 40,
               "precision": "years"
            }
      ]
   },
   "device_types": [
      "android"
   ],
   "notification": {
      "alert": "Hello, Generation X!"
   }
}

{ "audience":
   {
      "attribute": "item_purchased",
      "operator": "contains",
      "value": "jeans"
   }
}

{ "audience":
   {
      "NOT":{
         "attribute": "item_purchased",
         "operator": "contains",
         "value": "jeans"
      }
   }
}

{ "audience":
   {
      "attribute": "item_purchased",
      "operator": "is_empty",
   }
}

{ "audience":
   {
      "AND":[
         {
            "attribute": "size",
            "operator": "greater",
            "value":12
         },
         {
            "attribute": "size",
            "operator": "less",
            "value": 15
         }
      ]
   }
}

An attribute object with a DATE schema type. Performs absolute date comparisons for ISO-formatted date values or a relative date comparisons given an integer value and precision, e.g., days, months. Use a date attribute to target a channel or Named User based on the date values.

OBJECT PROPERTIES
  • attribute stringREQUIRED

    The key for the date attribute that you previously defined in the Airship UI, e.g., "birth_date".

  • operator stringREQUIRED

    The operator used to evaluate the attribute expression. The operator that you use with a date attribute will determine which additional properties will be required in the object. See table for required fields.

    OperatorRequired properties
    is_emptyattribute
    beforeattribute, value, precision*
    afterattribute, value, precision*
    rangeattribute, value
    equalsattribute, value, precision**

    * precision is required, but enum values are different than with an equals operator

    ** precision is required, but enum values are different than with a before or after operator

    Date Attribute Operators:

    • is_empty— Evaluates to true if a channel or Named User does not have a value for the attribute.

    • before— Value is one of:

      • String, ISO 8601 inclusive date, optionally including an offset, e.g., 2007-03-01T13:00:00+08:00. The value will be converted and stored as UTC.

      • Integer, Relative number of units from the current time (i.e., now) into the past. Example: "before": 20 indicates “at least 20 years ago” given a precision of years.

      • String with the value "now", representing the current date-time, i.e., “before now”. When using the now value, no precision is required.

        Note: When using the before operator, precision value must be one of years, months, days, hours, or minutes.

    • after— Values for after behave identically to before, as described above.

    • range— An ISO 8601 time interval. The format consists of an inclusive start and an exclusive end time date separated with a /, e.g., 2019-03-01T13:00:00/2019-05-11T15:30:00. range does not have a precision.

    • equals— allows for selecting specific or non-specific dates as determined by the precision provided in the attribute object.

      Note: When using the equals operator, precision must be one of:

      • day — an integer which represents the day of the month or “now”.
      • month — an integer which represents the month of the year starting with 1 for Jan or “now” which will use the value of the current month.
      • month_day — a string in the format of “mm-dd” which represents a month and day. Ex. 05-04 is May 4th. Value can also be “now”. If today is 2020-03-09, then value will be “03-09”.
      • year_month — a string in the format of “yyyy-mm” which represents a year and month. Ex. 2020-05 is May 2020. Value can also be “now”. If today is 2020-03-09, then value will be “2020-03”.
      • year_month_day — a string in the format of “yyyy-mm-dd” which represents a specific year, month, and day. Ex. 2020-05-04. Value can also be “now”. If today is 2020-03-09, then value will be “2020-03-09”.
      • or value can be “now” which is the current date-time.

    Possible values: is_empty, before, after, range, equals

  • precision string

    The precision, expressed as a timing interval unit, that Airship uses to evaluate a date attribute expression.

    Possible values: years, months, days, hours, minutes, day, month, month_day, year_month, year_month_day

  • relative_to string

    Specifies whether the date is in the future or in the past. If missing, it defaults to past.

    Possible values: future, past

  • value object
    One of

Device Attributes

Native attribute properties that Airship gathers automatically assigns to a channel. Varies by channel type. See: Default Attributes.

For segmentation, when using ua_app_version, ua_sdk_version, or ua_device_os, only semantic versioning formatting is accepted, and anything after the third decimal place is excluded, e.g., 12.2.3-alpha is compared as 12.2.3. You can use operators equals, contains, less, greater, is_empty with values in the formats 1, 1.2, 1.2.3.

OBJECT PROPERTIES
  • ua_app_version string

    The app version that the channel uses.

  • ua_browser_name string

    The browser associated with a web channel.

  • ua_browser_type string

    The browser type associated with a web channel.

    Possible values: mobile, desktop

  • ua_browser_version string

    The browser version associated with a web channel.

  • ua_carrier string

    The cellular carrier of the device associated with an app channel.

  • ua_country string

    The 2-letter country code for an app or web channel.

  • ua_country_code string

    The country dialing code derived from the MSISDN associated with an SMS channel.

  • ua_device_model string

    The model of the device associated with an app channel.

  • ua_device_os string

    The operating system of the device associated with an app channel.

  • ua_language string

    The 2-letter language code for an app or web channel.

  • ua_local_tz string

    The time zone that the SDK registers for an app or web channel.

  • ua_location_settings string

    If true, location settings are enabled for an app channel.

    Possible values: true, false

  • ua_ndc string

    The National Destination Code aka area code derived from the MSISDN on an SMS channel.

  • ua_rcs_enabled string

    Rich Communication Services (RCS) capability for an SMS channel. Set to true when an RCS upgrade delivery receipt is received.

    Possible values: true

  • ua_sdk_version string

    The Airship SDK version associated with an app or web channel.

  • ua_subdivision string

    The ISO 3166-2 code derived from the MSISDN on an SMS channel.

JSON Attribute selector

JSON Attribute examples

{
  // Example 1
  "audience":
   {
      "attribute": "books_on_books",
      "where": {
         "property": "$.x.store.book[*].title",
         "operator": "equals",
         "value": "Dracula",
         "compare_as": "text"
      }
   }
}
{
  // Example 2
  "audience":
   {
      "attribute": "oh_look_a_book",
      "where": {
         "property": "$.x['store']['book'][0]['title']",
         "operator": "equals",
         "value": "Dracula",
         "compare_as": "text"
      }
   }
}
{
  // Example 3
  "audience":
   {
      "attribute": "another_one",
      "where": {
         "property": "$.x.store.codes[*].sneakers",
         "operator": "equals",
         "value": 178394549,
         "compare_as": "number"
      }
   }
}
{
  // Example 4
  "audience":
   {
      "attribute": "and_one_more",
      "where": {
         "property": "$.x['store']['codes'][0]['available']",
         "operator": "equals",
         "value": "true",
         "compare_as": "boolean"
      }
   }
}

An attribute object with a JSON schema type. Performs value comparisons based on the JSON value for an attribute on a channel or Named User.

OBJECT PROPERTIES
  • attribute stringREQUIRED

    The name of the attribute.

  • where objectREQUIRED

    An object that filters on the JsonPath expression that you provide.

    OBJECT PROPERTIES
    • compare_as string

      Selects the property type for comparison.

      Possible values: text, number, date, boolean

    • operator stringREQUIRED

      The operator used to evaluate the attribute expression. If the JsonPath expression maps to an array, the only available operators are is_empty, not_empty, contains, or not_contains.

      Possible values: equals, contains, not_contains, less, less_eq, greater, greater_eq, range, before, after, is_empty, not_empty

    • precision string

      Used only for date values.

      Possible values: minutes, days, months, years

    • property stringREQUIRED

      The JsonPath expression that will be used to look up the value in a predefined attribute, for example "$.x['store']['book'][0]['title']". This is different from selecting based on primitive string attributes, because the JsonPath expression can map to a single attribute or an array of attributes. See JsonPath  for more information about JsonPath expressions and usage.

    • relative_to string

      Used only for date values.

      Possible values: future, past

    • value object

      The value of the property you are filtering for in the where object. Use compare_as to select the type for comparison. This is required for all operators except is_empty and not_empty.

      One of
      • string

NPS survey Attributes

Attributes automatically generated by Airship based on data from your NPS surveys.

OBJECT PROPERTIES
  • ua_nps_category string

    A category based on the score a user submits in an NPS survey. Scores of 9 and 10 are categorized as promoter, 7 and 8 are categorized as passive, and 0-6 are detractor.

  • ua_nps_score number

    The score (0-10) a user submits in an NPS (Net Promoter Score) survey.

Number Attribute selector

Number Attribute example

{ "audience":
   {
      "attribute": "lifetime_value",
      "operator": "greater",
      "value": 15000
   }
}

An attribute object with a NUMBER schema type. Performs value comparisons based on the number value for an attribute on a channel or Named User.

OBJECT PROPERTIES
  • attribute stringREQUIRED

    The key for the number attribute that you previously defined in the Airship UI, e.g., "lifetime_value".

  • operator stringREQUIRED

    The operator used to evaluate the attribute expression.

    Possible values: equals, contains, less, greater, is_empty

  • value numberREQUIRED

    The value of the number attribute that you are targeting. For example, 15000.

Remove Attribute

Remove Attribute

{
  "action": "remove",
  "key": "minor_league"
}

Remove an existing attribute from the audience.

OBJECT PROPERTIES
  • action stringREQUIRED

    Indicate that you want to remove an attribute from the audience.

    Possible values: remove

  • key stringREQUIRED

    The attribute ID for the attribute you want to set. JSON attribute key values must be in format <attribute_ID>#<instance_ID>. See JSON Attributes in About Attributes.

  • timestamp string

    The date-time when the attribute changed. If you don’t enter a timestamp, Airship uses the current time.

Set Attribute

Set Attribute with string value

{
  "action": "set",
  "key": "position",
  "value": "LF"
}

Set JSON Attribute with its required object value

{
  "action": "set",
  "key": "position",
  "value": "LF"
}

{
  "action": "set",
  "key": "position#instance_42",
  "value": {
    "exp": 1731531110,
    "name": "LeftField",
    "rank": 2,
    "active" true,
    "extras": [
      "rookie",
      "mvp"
    ]
  }
}

Add a new attribute, or edit the value of an existing attribute, for the audience.

OBJECT PROPERTIES
  • action stringREQUIRED

    Indicate that you want to set an attribute on the audience.

    Possible values: set

  • key stringREQUIRED

    The attribute ID for the attribute you want to set. JSON attribute key values must be in format <attribute_ID>#<instance_ID>. See JSON Attributes in About Attributes.

  • timestamp string

    The date-time when the attribute changed. If you don’t enter a timestamp, Airship uses the current time.

  • value objectREQUIRED

    The value that you want to set for an attribute. Accepts numbers and strings for integer/number type attributes, but your string must be convertible to a number or the request will fail. You can also set an object, which must be valid JSON or the request will fail.

    One of
    • string
    • OBJECT PROPERTIES
      • exp number

        The JSON attribute expiration date, set as the number of seconds since the epoch (January 1st, 1970). After expiration, Airship ignores the Attribute where used in segmentation and personalization. If omitted, Airship automatically sets a value of 90 days from the current date and time. The maximum expiry delay for a JSON Attribute is 731 days.

Text Attribute selector

Text Attribute example

{ "audience":
   {
      "attribute": "item_purchased",
      "operator": "contains",
      "value": "jeans"
   }
}

An attribute object with a TEXT schema type. Evaluates for the inclusion or exclusion of a text (string) attribute on a channel or Named User.

OBJECT PROPERTIES
  • attribute stringREQUIRED

    The key for the text attribute that you previously defined in the Airship UI, e.g., "item_purchased".

  • operator stringREQUIRED

    The operator used to evaluate the attribute expression.

    Possible values: equals, contains, less, greater, is_empty

  • value stringREQUIRED

    The string you want to match when evaluating the attribute expression, e.g., "jeans".

Pipeline objects

Objects and samples for /pipelines (Automation) endpoints.

Event selector

Compound event selector using 'and'

{
   "and": [
      {
         "key": "name",
         "value": {
            "equals": "POWER_LEVEL"
         }
      },
      {
         "key": "value",
         "value": {
            "greater_than": 9000,
            "at_most": 10000
         }
      }
   ]
}

An event selector is a JSON dictionary consisting of a set of (possibly negated) event-specific selectors joined together by a doubly-nested set of operators, in disjunctive or conjunctive normal form. That is, only queries of the pattern “single AND of ORs” or “single OR of ANDs” are allowed (no further nesting is allowed), and only leaf nodes of such queries may be negated. Elision of single-value operators is allowed for the sake of brevity/usability on writes, but responses from our servers will always be fully qualified.

Event-specific selectors are allowed to reference any field in a potentially matching event, at any nesting depth therein, with the goal of matching their structure to existing API formats, both inbound and outbound.

Top-level operator dictionaries are of the form {"and": []} or {"or": []}, where the members of the array will be operator dictionaries of the other type (“AND of ORs” or “OR of ANDs”), or if eliding on ingress, negation operator dictionaries or event-specific selectors.

Negation operator dictionaries are of the form {"not": {}} where the inner object is strictly an event-specific selector. I.e., only leaf nodes may be negated, in keeping with the tenets of conjunctive/disjunctive normal form.

One of
  • Event value selector object

    Defines an event value to match.

    OBJECT PROPERTIES
    • key stringREQUIRED

      The field you want to match a value against.

    • scope string

      Specifies an inner-dictionary on a potentially-matching event.

    • value objectREQUIRED

      Specifies the criteria qualifying a value as a match. Integer values support up to 6 digits of decimal precision. You can specify a range of values using at_least/greater_than and at_most/less_than, but the value for at_least/greater_than must be less than the value of at_most/less_than or your request will return an error.

      OBJECT PROPERTIES
      • array_contains string

        Matches if an array contains the specified string value.

      • at_least integer

        Matches values greater than the specified value.

      • at_most integer

        Matches values less than the specified value.

      • equals object

        Specifies an exact match. String values are case sensitive and must match exactly.

        Any of
        • string
      • greater_than integer

        Matches values greater than the specified value.

      • less_than integer

        Matches values less than the specified value.

  • AND selector object

    AND selector

    OBJECT PROPERTIES
    • and array
  • OR selector object

    OR selector

    OBJECT PROPERTIES
    • or array
  • NOT selector object

    NOT selector

    OBJECT PROPERTIES
    • not object

      Defines an event value to match.

      OBJECT PROPERTIES
      • key stringREQUIRED

        The field you want to match a value against.

      • scope string

        Specifies an inner-dictionary on a potentially-matching event.

      • value objectREQUIRED

        Specifies the criteria qualifying a value as a match. Integer values support up to 6 digits of decimal precision. You can specify a range of values using at_least/greater_than and at_most/less_than, but the value for at_least/greater_than must be less than the value of at_most/less_than or your request will return an error.

        OBJECT PROPERTIES
        • array_contains string

          Matches if an array contains the specified string value.

        • at_least integer

          Matches values greater than the specified value.

        • at_most integer

          Matches values less than the specified value.

        • equals object

          Specifies an exact match. String values are case sensitive and must match exactly.

          Any of
          • string
        • greater_than integer

          Matches values greater than the specified value.

        • less_than integer

          Matches values less than the specified value.

Event identifier

Simple `open` event identifier

{
  "event": "open"
}

Tag added example

{
  "event": "open"
}

{
  "tag_added": "cool_user"
}

Custom Event example

{
  "event": "open"
}

{
  "tag_added": "cool_user"
}

{
  "custom_event": {
    "key": "name",
    "value": {
      "equals": "christmas"
    }
  }
}

Event identifiers describe events that Automation can detect and act on. They may be described by a simple string, e.g., open, or by an object for parameterized events, e.g., { "tag_added" : "<t>" }.

One of
  • string

    Triggers the pipeline whenever an event of the following types occurs. first_open and first_opt_in are only available in immediate triggers.

    • open events occur whenever your audience opens your app.
    • first_open events occur when your audience opens your app for the first time.
    • first_opt_in events represent the first time your audience opts into email (commercial only), sms, or open notifications.
    • double_opt_in events occur when a new email channel registration occurs with the "opt_in_mode": "double" parameter.
    • When used without a value, region_entered and region_exited types cause the trigger to fire whenever an audience member enters or exits any region.

  • Compound event identifier object

    A compound event identifier is a JSON dictionary with a single key indicating the event type, and a value specifying the specific parameter to match on.

    OBJECT PROPERTIES
    • activation_time string

      The date-time indicating a time at which the trigger will automatically become active.

    • condition array[object]

      A single condition set or array of condition sets. It is a collection of one or more conditions and an operator for combining them, in the case that there are multiple conditions. A condition set follows the same general syntax as a compound selector. It is a JSON dictionary with a single key indicating the operator. The key’s value is an array of one or more condition objects. Taken together, the operator and set of conditions form a boolean expression which must evaluate to true for a pipeline to be activated and its outcomes executed. Valid operators for a condition set are and and or. This field is evaluated before the pipeline is entered and only evaluated against events for the triggers on which they are set, which is noticeable when using multiple triggers.

    • custom_event object<Event selector>

      A Custom Event selector is an event selector that describes the specific criteria a Custom Event must fulfill in order to trigger an automation. Supported Custom Event fields in the default scope are "name" (string) and ["value"]. Custom Events also have a map of properties that may also be selected under the "properties" scope. Values for the "properties" key may be string, boolean, number, or an array of strings.

      An event selector is a JSON dictionary consisting of a set of (possibly negated) event-specific selectors joined together by a doubly-nested set of operators, in disjunctive or conjunctive normal form. That is, only queries of the pattern “single AND of ORs” or “single OR of ANDs” are allowed (no further nesting is allowed), and only leaf nodes of such queries may be negated. Elision of single-value operators is allowed for the sake of brevity/usability on writes, but responses from our servers will always be fully qualified.

      Event-specific selectors are allowed to reference any field in a potentially matching event, at any nesting depth therein, with the goal of matching their structure to existing API formats, both inbound and outbound.

      Top-level operator dictionaries are of the form {"and": []} or {"or": []}, where the members of the array will be operator dictionaries of the other type (“AND of ORs” or “OR of ANDs”), or if eliding on ingress, negation operator dictionaries or event-specific selectors.

      Negation operator dictionaries are of the form {"not": {}} where the inner object is strictly an event-specific selector. I.e., only leaf nodes may be negated, in keeping with the tenets of conjunctive/disjunctive normal form.

    • deactivation_time string

      The date-time indicating a time at which the trigger will automatically become inactive.

    • double_opt_in object

      Matches when a double opt-in registration matching the specified criteria was made for a channel. A double opt-in selector is a complex selector that describes the specific criteria a double opt-in registration must fulfill in order for it to qualify as a match for triggering pipelines. The only supported value for scope is properties. All value selectors, except for date, are supported. The key object supports a simple string to select the value of a top-level key or any JsonPath query for maximum flexibility. For situations where a compound event identifier is necessary (e.g., when including trigger_id), but no selector is present or desired, an empty object {} is allowed. "immediate_trigger": "double_opt_in" and "immediate_trigger": { "id": "8e1a61d7-7e9d-4870-a548-2d4d6eb6405f", "double_opt_in": {} } are equivalent (assuming the ID is correct).

      One of
      • Complex Event Selector

        An event selector is a JSON dictionary consisting of a set of (possibly negated) event-specific selectors joined together by a doubly-nested set of operators, in disjunctive or conjunctive normal form. That is, only queries of the pattern “single AND of ORs” or “single OR of ANDs” are allowed (no further nesting is allowed), and only leaf nodes of such queries may be negated. Elision of single-value operators is allowed for the sake of brevity/usability on writes, but responses from our servers will always be fully qualified.

        Event-specific selectors are allowed to reference any field in a potentially matching event, at any nesting depth therein, with the goal of matching their structure to existing API formats, both inbound and outbound.

        Top-level operator dictionaries are of the form {"and": []} or {"or": []}, where the members of the array will be operator dictionaries of the other type (“AND of ORs” or “OR of ANDs”), or if eliding on ingress, negation operator dictionaries or event-specific selectors.

        Negation operator dictionaries are of the form {"not": {}} where the inner object is strictly an event-specific selector. I.e., only leaf nodes may be negated, in keeping with the tenets of conjunctive/disjunctive normal form.

    • pipeline_event object

      A JSON dictionary describing which pipeline events for a specified pipeline should be considered a match and should therefore trigger the pipeline.

      OBJECT PROPERTIES
      • cancellation_reason string

        For cancelled type selectors, the specific cancellation reason to consider for triggering. All others will be ignored.

        Possible values: cancellation_trigger, timing, condition, rewritten, rate_limit

      • message_id string

        Unique identifier for an In-App Automation. This is required when type is in_app_fallback.

      • pipeline_id string

        The UUID of a pipeline whose events should be considered. If this is not provided, then trigger_ids must be provided. This is not required if message_id is provided.

      • trigger_ids array[string]

        The list of trigger IDs that should be considered. If this is not provided, then pipeline_id must be provided. This is not required if message_id is provided.

      • type stringREQUIRED

        The type of event for the specified pipeline which should be considered.

        Possible values: entered, cancelled, fulfilled, in_app_fallback

    • region_entered object

      A region selector is an event selector that describes the specific criteria a region must fulfill in order to qualify as a match (for triggering pipelines).

      Supported default scope region keys are currently: name (string) and region_id (string).

      Under the source_info scope, we support the following key: region_id (string).

      We also have support for the arbitrary scope attributes, which has no key restrictions because it is user-supplied in its entirety.

    • region_exited object

      A region selector is an event selector that describes the specific criteria a region must fulfill in order to qualify as a match (for triggering pipelines).

      Supported default scope region keys are currently: name (string) and region_id (string).

      Under the source_info scope, we support the following key: region_id (string).

      We also have support for the arbitrary scope attributes, which has no key restrictions because it is user-supplied in its entirety.

    • subscription_added string

      Matches when the specified subscription list is added. The value of the identifier is a simple string identifying the subscription list.

    • subscription_removed string

      Matches when the specified subscription list is removed. The value of the identifier is a simple string identifying the subscription list.

    • tag_added object

      Defines a tag selector.

      One of
      • OBJECT PROPERTIES
        • group string

          The tag group. If you do not specify a group, Airship uses the default device tag group; this group is represented by a channel’s tags array rather than the tag_groups object.

        • tag stringREQUIRED

          The tag.

      • string

        The device tag.

    • tag_removed object

      Defines a tag selector.

      One of
      • OBJECT PROPERTIES
        • group string

          The tag group. If you do not specify a group, Airship uses the default device tag group; this group is represented by a channel’s tags array rather than the tag_groups object.

        • tag stringREQUIRED

          The tag.

      • string

        The device tag.

Pipeline object

Example

{
   "name":"The Darkest Pipeline",
   "enabled":true,
   "immediate_trigger":"first_open",
   "outcome":{
      "push":{
         "audience":"triggered",
         "device_types":[
            "ios",
            "android"
         ],
         "notification":{
            "alert":"Cool goatee, Abed"
         }
      }
   },
   "timing":{
      "delay":{
         "seconds":7200
      },
      "schedule":{
         "type":"local",
         "miss_behavior":"wait",
         "dayparts":[
            {
               "days_of_week":[
                  "thursday"
               ],
               "allowed_times":[
                  {
                     "preferred":"21:30:00"
                  }
               ]
            }
         ]
      }
   }
}

Example email pipeline

{
   "name":"The Darkest Pipeline",
   "enabled":true,
   "immediate_trigger":"first_open",
   "outcome":{
      "push":{
         "audience":"triggered",
         "device_types":[
            "ios",
            "android"
         ],
         "notification":{
            "alert":"Cool goatee, Abed"
         }
      }
   },
   "timing":{
      "delay":{
         "seconds":7200
      },
      "schedule":{
         "type":"local",
         "miss_behavior":"wait",
         "dayparts":[
            {
               "days_of_week":[
                  "thursday"
               ],
               "allowed_times":[
                  {
                     "preferred":"21:30:00"
                  }
               ]
            }
         ]
      }
   }
}

{
 "name":"Read Receipt",
 "enabled":true,
 "immediate_trigger": {
    "tag_added": "newSubscription"
 },
 "outcome":{
    "push":{
       "audience":"triggered"
       },
       "device_types": [
          "email"
       ],
       "notification": {
          "email": {
             "subject": "Did you get that thing I sent you?",
             "html_body": "<h2>Richtext body goes here</h2><p>Wow!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
             "plaintext_body": "Plaintext version goes here [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
             "message_type": "commercial",
             "sender_name": "Airship",
             "sender_address": "team@urbanairship.com",
             "reply_to": "no-reply@urbanairship.com"
          }
       }
    },
   "timing":{
      "delay":{
         "seconds":7200
      }
   }
}

A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

OBJECT PROPERTIES
  • activation_time string

    The date-time when the pipeline becomes active and begins processing triggers and issuing push notifications.

    If this value is in the future, the pipeline’s status is pending.

  • cancellation_trigger object
    One of
    • Event Identifier

      Event identifiers describe events that Automation can detect and act on. They may be described by a simple string, e.g., open, or by an object for parameterized events, e.g., { "tag_added" : "<t>" }.

    • array<ref>

      Defines event conditions that will cancel the fulfillment of a pipeline. If a pipeline has multiple cancellation triggers, they’re combined via an implicit OR operation. Any one of the triggers will cancel the fulfillment of the pipeline. Cancellation triggers are only allowed when a pipeline has no historical triggers and it is possible for a pipeline’s fulfillment to be delayed using the Timing Object. The first_open event identifier is not valid as a cancellation trigger.

  • condition array[object]

    One or more conditions, combined by operators. A condition set may contain a maximum of 20 conditions. Taken together, the operator and set of conditions form a boolean expression which must evaluate to true for a pipeline to be activated and its outcomes executed. Valid operators for a condition set are and and or. Nesting of operators is not supported within a condition set, i.e., you may not combine and logic with or logic.

  • constraint array[object]

    An array of rate objects determining the maximum number of messages each audience member can receive over a period of time. You can set a lifetimes constraint as well, limiting a pipeline to an absolute maximum number of messages ever.

  • creation_time string

    Read-only timestamp. The date-time indicating the time that the pipeline was initially created. This is a read-only field that is present on GET responses. If it is included in a POST or PUT request it will be ignored.

  • deactivation_time string

    The date-time when the pipeline becomes inactive and quits processing triggers and issuing push notifications.

    If this value is in the past, the pipeline’s status is completed.

  • enabled booleanREQUIRED

    A boolean value indicating whether or not the pipeline is active.

  • historical_trigger object
    One of
    • Historical trigger object object

      Defines a condition that matches against event data trended over time. It consists of an event identifier, a time period, and a matching operator with a value indicating the number of occurrences of the event. The operator indicates whether to match greater than, less than, or exactly the number of occurrences specified. Valid matching operators are equals, greater_than, or less_than. The matching window is specified in days, with an upper limit of 90 days. A historical trigger will be periodically evaluated against the event history for every active device belonging to the application. Pipelines with historical triggers cannot also have a timing object.

      OBJECT PROPERTIES
      • creation_time string

        A date-time returned when getting a pipeline with a historical_trigger. Include this field in a PUT request to ensure that the historical_trigger is not reset.

      • days integer

        A time period key. An integer indicating the length of the matching window, in days. Maximum 90 days.

      • equals integer

        A matching operator. Since we are measuring inactivity with the historical trigger object, 0 is the only value supported with the equals operator, i.e., we are measuring number of events in a defined time window. Any number higher than zero would therefore represent activity.

      • event object<Event identifier>

        Event identifiers describe events that Automation can detect and act on. They may be described by a simple string, e.g., open, or by an object for parameterized events, e.g., { "tag_added" : "<t>" }.

      • greater_than integer

        A matching operator. Specifies the number of events that must be targeted before the historical trigger will fire.

      • less_than integer

        A matching operator. Specifies the number of events that must be targeted before the historical trigger will fire.

    • array<object>

      Historical trigger objects are limited to inactivity triggers, which trigger when a user fails to open the app within a defined number of days.

  • immediate_trigger object
    One of
    • Event Identifier

      Event identifiers describe events that Automation can detect and act on. They may be described by a simple string, e.g., open, or by an object for parameterized events, e.g., { "tag_added" : "<t>" }.

    • array<ref>

      Defines a condition that activates a trigger immediately when an event matching it occurs. If a pipeline has multiple immediate triggers, they’re combined via an implicit OR operation. Any one of the triggers firing will activate the pipeline. Immediate triggers are all event identifiers. first_open is a valid event identifier for immediate triggers. However, events within the trigger support AND and OR compound selection.

  • last_modified_time string

    Read-only timestamp. The date-timeindicating the time that the pipeline was last modified. This is a read-only field that is present on GET responses. If it is included in a POST or PUT request it will be ignored.

  • name string

    A descriptive name for the pipeline.

  • outcome objectREQUIRED
    One of
    • Outcome object object

      An outcome object contains a single push object where the audience field must be set to triggered.

      OBJECT PROPERTIES
      • push objectREQUIRED

        A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

        OBJECT PROPERTIES
        • audience stringREQUIRED

          A special selector used in Pipelines to indicate that the audience of the push is composed of the device or devices that activated the trigger. See Pipeline objects for more information.

          Possible values: triggered

        • campaigns object<Campaigns object>

          An object specifying custom campaign categories related to the notification.

        • device_types array[string]REQUIRED

          An array containing one or more strings identifying targeted platforms.

        • in_app object<In-app message>

          A JSON object describing an in-app message payload.

        • message object
          One of
        • notification object<Notification object>

          The notification payload that is required unless either message or in_app is present. You can provide an alert and any platform overrides that apply to the device_type platforms you specify.

        • options object<Push options>

          A JSON dictionary for specifying non-payload options related to the delivery of the push.

        • orchestration object

          An object used to indicate the strategy to employ when deciding which channels to target for a contact. An orchestration object can be stored in Airship as the default strategy. If the orchestration section is included in a push payload, it will override the configured default value. The overall default strategy is fan_out.

          OBJECT PROPERTIES
          • channel_priority array[string]

            An array of channel types in priority order. Required if type is set to channel_priority.

          • type stringREQUIRED

            The name of the orchestration strategy to employ.

            Possible values: channel_priority, fan_out, triggering_channel, last_active

    • array<object>
  • status string

    Read-only field indicating whether or not the pipeline is currently issuing push notifications.

    • pending: The pipeline is not yet active. Occurs when the current time is less than or equal to the activation_time.
    • live: The pipeline is active.
    • completed: The pipeline has finished running. Occurs when the current time is greater than or equal to the deactivation_time.
    • disabled: The pipeline is not active.

    Possible values: pending, live, completed, disabled

  • timing object

    Determines when pipelines will be sent in accordance with triggers.

    OBJECT PROPERTIES
    • delay object

      Determines the time that Airship should wait after a triggering event before processing the pipeline outcome.

      OBJECT PROPERTIES
      • seconds integerREQUIRED

        An integer value greater than 0 seconds representing the number of seconds to delay.

    • schedule object

      The time(s) when the pipeline can issue pushes and behavior for events occurring outside scheduled time(s).

      OBJECT PROPERTIES
      • dayparts array[object]REQUIRED

        A list of daypart objects that, when combined, are non-intersecting and form a nonempty group of time ranges on a nonzero number of days of the week. Daypart is a term borrowed from television/radio marketing .

      • miss_behavior string

        Behavior of the pipeline when a triggering event occurs outside the range of daypart objects and allowed_times. You can specify cancel (do not process the outcome) or wait (delay the outcome until the preferred time of the next allowed_times window or the beginning of that window). Defaults to wait if unspecified.

        Possible values: wait, cancel

      • type string

        The mode in which to interpret the times in this schedule. Default is local.

        Possible values: local, utc

  • uid string

    The canonical identifier of the pipeline. This is a read-only field present on responses from the API, but it will be ignored if it is present on requests.

  • url string

    Read-only string. The canonical resource URL of the pipeline. This is a read-only field present on responses from the API, but it will be ignored if present on requests.

Subscription conditions

Example

{ "name" : "Pipeline with Subscription Conditions",
  "enabled" : true,
  "immediate_trigger" : "/* ... */",
  "outcome" : "/* ... */",
  "condition": [
  { "or" : [
      {"subscription" : {"list_name": "sports_updates"}},
      {"subscription" : {"list_name": "silence", "negated": true}}]
  }]
}

Subscription conditions have two possible attributes: list_name and negated.

OBJECT PROPERTIES
  • list_name stringREQUIRED

    The name of the subscription list to be matched.

  • negated boolean

    A boolean indicating the condition should match on the absence from the list.

Tag conditions

Example

{
    "name" : "Pipeline with Tag Conditions",
    "enabled" : true,
    "immediate_trigger" : "/* ... */",
    "outcome" : "/* ... */",
    "condition": [
        {
            "or" : [
                {
                    "tag" : {
                        "tag_name" : "VIP"
                    }

                },
                {
                    "tag" : {
                        "tag_name": "dont_push",
                        "group": "my_special_sandbox",
                        "negated": true
                    }
                }
            ]
        }
    ]
}

Tag conditions have three possible attributes: tag_name, group, and negated. Tag conditions can be replaced by segmentation conditions, which offer more features. But note that the behavior of tag conditions is slightly different than a segmentation condition using tag selectors when it comes to contacts. Tag conditions evaluate against a combined set of all tags of all channels. Segmentation conditions evaluate against all the channels of a contact individually to see if at least one channel satisfies the condition.

OBJECT PROPERTIES
  • group string

    A tag group. Defaults to device.

  • negated boolean

    If true, the condition will match on the absence of a tag. If absent or false, the condition will match on the presence of a tag.

  • tag_name stringREQUIRED

    The name of the tag the condition will match against.

Create and Send

Objects and samples for /create-and-send endpoints. A full object can contain parts of schedule, template, audience, and platform override objects (for email, sms, or open:: platforms).

The notification payload for Create and Send objects supports both stored and inline templates. Using inline templates, you can define and populate variables to personalize notifications to your new channels.

Create and Send to email channels

Example object

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22"
      },
      {
        "ua_address" : "ben@example.com",
        "ua_commercial_opted_out": "2020-11-29T12:45:10"
      },
      {
        "ua_address" : "mary@example.com",
        "ua_email_suppression_state": "BOUNCE"
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "subject": "Welcome to the 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": "transactional",
      "sender_name": "Airship",
      "sender_address": "team@airship.com",
      "reply_to": "no-reply@airship.com",
      "click_tracking": false,
      "open_tracking": false,
      "attachments": [
        {
          "id": "0e10a6b9-725c-4f6b-9af2-9ef5b31328c0",
        },
        {
          "id": "5503b5fe-ed69-4609-bef6-6fef0e6e428f"
        }
      ]
    }
  },
  "campaigns": {
      "categories": ["winter sale", "west coast"]
  }
}

The payload for a Create and Send operation to email channels. When sending to email channels, device_types must be set to email.

OBJECT PROPERTIES
  • audience objectREQUIRED
    One of
    • Email audience for Create and Send payloads object

      The email addresses and opt-in agreements for the audience you want to send to. Unknown addresses are registered as new channels.

      OBJECT PROPERTIES
      • create_and_send array[object]REQUIRED

        Each object in the array represents an email address you want to send to. Unknown addresses are registered as new channels. Channel registration fields are prefixed with ua_ and have the same requirements as the email registration endpoint.

        You cannot provide optional channel registration fields using this endpoint (like locale_language for email channels). All other fields represent variables if notification specifies a template.

    • OBJECT PROPERTIES
  • campaigns object<Campaigns object>

    An object specifying custom campaign categories related to the notification.

  • device_types array[string]REQUIRED

    The platform you want to send notifications to.

  • notification objectREQUIRED

    An alert notification or a platform override matching the value in device types. A notification with a platform override that does not match your device_types will result in a 400 error.

    OBJECT PROPERTIES
    • email object

      You can either provide the standard object that you would provide when performing a /api/push to an email platform, or you can provide some of the email platform override fields along with an inline template.

      One of
      • Email Override Object

        Notification fields specific to email messages. This object is required when email is specified in the payload’s device_types field.

      • Email Override With Template

        Notification fields specific to email messages with an inline template for use in a Create and Send payload. Using a template enables you to provide and populate variables in your notification. You can also add conditional statements based on those variables, determining message text that to send to each member of your audience. Conditionals begin with {{#operator}} and end with {{/operator}}. For more information, see Handlebars.

Create and Send MMS notification

Example Create and Send for MMS without template

{
  "audience": {
    "create_and_send": [
        {
            "ua_msisdn": "15558675309",
            "ua_sender": "15551234567",
            "ua_opted_in": "2020-11-11T18:45:30",
        }
    ]
  },
  "device_types": [
    "mms"
  ],
  "notification": {
    "mms": {
      "fallback_text": "Delivery failed, but you should still check this out.",
      "subject" : "Hey, thanks for subscribing!",
      "slides": [
        {
          "text": "Check this out!",
          "media": {
              "url": "https://i.example.com/1t466Om.jpg",
              "content_type": "image/jpeg",
              "content_length": 52918
            }
          }
        ]
      }
    }
  }

The payload for a Create and Send operation that sends a multimedia payload (MMS) to SMS channels. When sending an MMS payload, device_types must be set to mms.

OBJECT PROPERTIES
  • audience objectREQUIRED
    One of
    • SMS audience for Create and Send payloads object

      The SMS information and opt-in parameters for the audience you want to send to. Unknown MSISDNs are registered as new channels.

      OBJECT PROPERTIES
      • create_and_send array[object]REQUIRED

        Each object in the array represents an MSISDN you want to send to. Unknown MSISDNs are registered as new channels. Channel registration fields are prefixed with ua_ and have the same requirements as the SMS channel registration endpoint.

        All other fields represent variables if notification specifies a template.

    • OBJECT PROPERTIES
  • device_types array[string]REQUIRED

    The platform you want to send notifications to.

  • notification objectREQUIRED
    OBJECT PROPERTIES
    • mms objectREQUIRED

      A platform override for MMS messages; device_types must be set to mms. A notification with a platform override that does not match your device_types will result in a 400 error.

      One of
      • Mms Override Object

        Provides the content for a push to MMS channels. If sms is in the device_type array, your request may include this object. It cannot be combined with an SMS Platform Override as a single push can only include either an SMS or MMS payload.

      • Mms Override With Template

        Template and notification overrides for a Create and Send payload with device_types set to mms. With a template, you can provide and populate variables and conditional statements based on those variables. Conditionals begin with {{#operator}} and end with {{/operator}}. For more information, see Handlebars.

Create and Send to open channels

Example object

{
  "audience" : {
    "create_and_send": [
      {
        "ua_address" : "36d5a261-0454-40f5-b952-942c4b2b0f22",
        "name": "Perry"
      }
    ]
  },
  "device_types" : [ "open::smart_fridge" ],
  "notification" : {
      "open::smart_fridge": {
          "alert" : "Hey {{name}}, you're out of ice cream!"
      }
  },
  "campaigns": {
      "categories": ["needs_ice_cream", "cookies_and_cream"]
  }
}

The payload for a Create and Send operation to open channels. When sending to open channels, the device_type must be set to open::<open_channel_name>.

OBJECT PROPERTIES
  • audience objectREQUIRED
    One of
    • Open audience for Create and Send payloads object

      The Open channel addresses and opt-in information for the audience you want to send to. Unknown addresses are registered as new channels.

      OBJECT PROPERTIES
      • create_and_send array[object]REQUIRED

        Each object in the array represents an Open channel address you want to send to. Unknown addresses are registered as new channels. Channel registration fields are prefixed with ua_ and have the same requirements as open channel registration.

    • OBJECT PROPERTIES
  • campaigns object<Campaigns object>

    An object specifying custom campaign categories related to the notification.

  • device_types array[string]REQUIRED

    The platform you want to send notifications to.

  • notification objectREQUIRED

    An alert notification or a platform override matching the value in device types. A notification with a platform override that does not match your device_types will result in a 400 error.

    OBJECT PROPERTIES
    • open::open_platform_name object<Open channel override with template>

      Use a template with an open channel-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

Create and Send to SMS channels

Example object

{
 "audience": {
    "create_and_send" : [
      {
        "ua_msisdn": "15558675309",
        "ua_sender": "12345",
        "ua_opted_in": "2020-11-11T18:45:30"
      }
    ]
  },
  "device_types" : [ "sms" ],
  "notification" : {
    "sms": {
      "alert": "Check out our winter sale! https://www.example.com/amazingly/long/url-that-I-want-to-shorten",
      "expiry": 172800,
      "shorten_links": true
    }
  },
  "campaigns": {
      "categories": ["winter sale", "west coast"]
  }
}

The payload for a Create and Send operation to SMS channels. When sending to SMS channels, device_types must be set to sms.

OBJECT PROPERTIES
  • audience objectREQUIRED
    One of
    • SMS audience for Create and Send payloads object

      The SMS information and opt-in parameters for the audience you want to send to. Unknown MSISDNs are registered as new channels.

      OBJECT PROPERTIES
      • create_and_send array[object]REQUIRED

        Each object in the array represents an MSISDN you want to send to. Unknown MSISDNs are registered as new channels. Channel registration fields are prefixed with ua_ and have the same requirements as the SMS channel registration endpoint.

        All other fields represent variables if notification specifies a template.

    • OBJECT PROPERTIES
  • campaigns object<Campaigns object>

    An object specifying custom campaign categories related to the notification.

  • device_types array[string]REQUIRED

    The platform you want to send notifications to.

  • notification objectREQUIRED

    An alert notification or a platform override matching the value in device types. A notification with a platform override that does not match your device_types will result in a 400 error.

    OBJECT PROPERTIES
    • sms object
      One of
      • Sms Override Object

        Provides override options when sms is one of the device_types specified in the payload.

      • Sms Override With Template

        Notification fields specific to SMS messages with an inline template for use in a Create and Send payload. Using a template enables you to provide and populate variables in your notification. You can also add conditional statements based on those variables, determining message text that to send to each member of your audience. Conditionals begin with {{#operator}} and end with {{/operator}}. For more information, see Handlebars.

Response format

Success and error responses typically conform to the following formats.

Error response

400 response

{
  "ok" : false,
  "error" : "Could not parse request body.",
  "error_code" : 40000,
  "details" : {
      "error" : "The key 'alert1' is not allowed in this context",
      "path" : "notification.alert1",
      "location" : {
          "line" : 5,
          "column" : 18
      }
  }

400 response without location

{
  "ok" : false,
  "error" : "Could not parse request body.",
  "error_code" : 40000,
  "details" : {
      "error" : "The key 'alert1' is not allowed in this context",
      "path" : "notification.alert1",
      "location" : {
          "line" : 5,
          "column" : 18
      }
  }

{
    "ok": false,
    "error": "Could not parse request body.",
    "error_code": 40902,
    "details": {
        "error": "malformed sender"
    }
}

404 response

{
  "ok" : false,
  "error" : "Could not parse request body.",
  "error_code" : 40000,
  "details" : {
      "error" : "The key 'alert1' is not allowed in this context",
      "path" : "notification.alert1",
      "location" : {
          "line" : 5,
          "column" : 18
      }
  }

{
    "ok": false,
    "error": "Could not parse request body.",
    "error_code": 40902,
    "details": {
        "error": "malformed sender"
    }
}

{
    "ok": false,
    "error": "Entity not found",
    "error_code": 40401
}

Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

OBJECT PROPERTIES
  • details object

    Provides information relating to the specific error_code when possible. For 400 errors, this object may include the path and location of validation failures.

    OBJECT PROPERTIES
    • error string

      Specific information about the semantic error, helping you better understand why the request failed.

    • location object

      The specific line and column where the validation error occurred, if known.

      OBJECT PROPERTIES
      • column integer

        The column containing the semantic error.

      • line integer

        The line containing the semantic error.

    • path string

      The path to the key containing the validation error.

  • error stringREQUIRED

    A plain-text explanation of the error.

  • error_code integer

    The Airship error code. This is normally the HTTP error code appended with a 2-digit identifier, helping provide more specific details about the error.

  • ok booleanREQUIRED

    2xx responses return true; 4xx responses return false.

OK response

OK response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
}

OK with identifiers

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
}

HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078"
    ]
}

Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

OBJECT PROPERTIES
  • ok booleanREQUIRED

    Success.

  • operation_id string

    A unique string identifying the operations that modify resources. Use the operation ID to locate and track grouped operations (i.e., a batch push operation may generate multiple push_id strings, but a single operation_id) or operations that change an existing resource.

External Data Feeds references

A push request property specifying which External Data Feeds should be invoked and with what parameters in order to support personalization from feed content.

Feed references object

Example push external data feeds request

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

 {
    "device_types": ["ios"],
    "audience": { "tag": "earlyBirds" },
    "notification": {
       "alert": "{{#feed \"featured_product\"}}Hello, {{user}}, could I interest you in {{product_name}} today?{{/feed}}"
    },
    "options": {
       "personalization": true
    },
    "feed_references": {
       "feeds": [
          {
             "name": "featured_product"
          }
       ],
       "defaults": {
          "featured_product": {
             "category": "featured"
          }
       }
    }
 }

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3
Content-Length: 123
Data-Attribute: push_ids

{
    "ok": true,
    "operation_id": "5e7852b0-6909-4e60-a73f-4d6b92d94c80",
    "push_ids": [
       "bf28d158-fefe-475a-9c2a-ed4f69cc891e"
    ]
}

Example feed references object

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

 {
    "device_types": ["ios"],
    "audience": { "tag": "earlyBirds" },
    "notification": {
       "alert": "{{#feed \"featured_product\"}}Hello, {{user}}, could I interest you in {{product_name}} today?{{/feed}}"
    },
    "options": {
       "personalization": true
    },
    "feed_references": {
       "feeds": [
          {
             "name": "featured_product"
          }
       ],
       "defaults": {
          "featured_product": {
             "category": "featured"
          }
       }
    }
 }

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3
Content-Length: 123
Data-Attribute: push_ids

{
    "ok": true,
    "operation_id": "5e7852b0-6909-4e60-a73f-4d6b92d94c80",
    "push_ids": [
       "bf28d158-fefe-475a-9c2a-ed4f69cc891e"
    ]
}   

{
   "feed_references": {
      "feeds": [
         {
            "name": "featured_product",
            "params": {
               "sub_category": "shoes"
            },
            "on_error": "continue"
         }
      ],
      "defaults": {
         "featured_product": {
            "category": "featured"
         }
      }
   }
}

An object used to indicate that an external data feed should be invoked, the name of the feed to invoke, and the way in which to invoke it. You can only include a feed if you include a templates object in the payload or set the personalization option to true.

OBJECT PROPERTIES
  • defaults object

    Default parameter values for your feed. These values override any defaults you set for your feed in the Airship Dashboard.

  • feeds array[object]REQUIRED

    An array of feeds that you want to use to personalize your message.

Region data formats

The following schemas represent ways to target by location, region, or geofence.

Geofence object

Polygon Geofence

{
    "type": "POLYGON",
    "points": [
        {
            "latitude": 1.000,
            "longitude": 90
        },
        {
            "latitude": 2.000,
            "longitude": 90
        },
        {
            "latitude": 3.000,
            "longitude": 0
        }
    ]
}

Circle Geofence

{
    "type": "POLYGON",
    "points": [
        {
            "latitude": 1.000,
            "longitude": 90
        },
        {
            "latitude": 2.000,
            "longitude": 90
        },
        {
            "latitude": 3.000,
            "longitude": 0
        }
    ]
}

{
    "type": "CIRCLE",
    "center": {
        "latitude": 0,
        "longitude": 0
    },
    "radius": 1000
}

Confidential Geofence

{
    "type": "POLYGON",
    "points": [
        {
            "latitude": 1.000,
            "longitude": 90
        },
        {
            "latitude": 2.000,
            "longitude": 90
        },
        {
            "latitude": 3.000,
            "longitude": 0
        }
    ]
}

{
    "type": "CIRCLE",
    "center": {
        "latitude": 0,
        "longitude": 0
    },
    "radius": 1000
}

{
    "type": "CONFIDENTIAL",
    "source": "Maponics",
    "version": "1.0.17-BETA",
    "id": "TheLouvreMuseumFloodZoneParis"
}

A Geofence object describes a geographical boundary corresponding to a physical location of relevance to the application or application owner. The geofence type can be a polygon, a circle, or provided by a confidential source.

One of
  • Polygon Geofence object object

    A Geofence subtype describing a polygon.

    OBJECT PROPERTIES
    • points arrayREQUIRED

      An ordered array of Points that correspond to the vertices of the polygon on the globe.

    • type stringREQUIRED

      The key type indicating a polygon geofence subtype.

      Possible values: POLYGON

  • Circle Geofence object object

    A Geofence subtype describing a circle.

    OBJECT PROPERTIES
    • center object<Point object>REQUIRED

      A single Point indicating the center fo the circle.

      A Point object is a simple JSON object corresponding to a point on the globe, consisting of only two keys: latitude and longitude.

    • radius integerREQUIRED

      An integer indicating the size (in meters) of the radius of the circle whose edge is the geofence boundary.

    • type stringREQUIRED

      The key type indicating a circle geofence subtype.

      Possible values: CIRCLE

  • Confidential Geofence object object

    A confidential Geofence subtype.

    OBJECT PROPERTIES
    • id stringREQUIRED

      The source-specific identifier for this geofence.

    • source stringREQUIRED

      The name of the company providing the geofence.

    • type stringREQUIRED

      The key type indicating a confidential geofence subtype.

      Possible values: CONFIDENTIAL

    • version stringREQUIRED

      The version number for the source of this geofence.

Point object

Coordinate point example

{
    "latitude": 45,
    "longitude": 179.999999
}

A Point object is a simple JSON object corresponding to a point on the globe, consisting of only two keys: latitude and longitude.

OBJECT PROPERTIES
  • latitude numberREQUIRED

    Decimal with maximum 6 digits of decimal precision in the range [-90,90].

  • longitude numberREQUIRED

    Decimal with maximum 6 digits of decimal precision in the range of [0, 180)

Region object

Example polygon-type Geofence imported from Gimbal

{
    "region_id": "abe5deb3-00d0-446e-8c5d-94b6421a01e0",
    "name": "My Favorite Place",
    "created_at": "2020-06-09T12:34:56",
    "updated_at": "2020-06-09T12:34:56",
    "geofence": {
        "type": "POLYGON",
        "points": [
            {
                "latitude": 90.0,
                "longitude": 180.0
            },
            {
                "latitude": 90.0,
                "longitude": 180.0
            },
            {
                "latitude": 0.0,
                "longitude": 0.0
            }
        ]
    },
    "beacons": [
        {
            "name": "entryway",
            "id": "VLSHLAOEXOFCMLDVTKFQ"
        },
        {
            "name": "Exhibit A",
            "id": "ZAQQMNOZKRFCRPYEUCZI"
        }
    ],
    "attributes": {
        "store_name": "REI"
    },
    "source_info": {
        "source": "GIMBAL",
        "region_id": "4BPSFLKJSDFLKJSDFLKJ",
        "vendor_href": "http://api.gimbal.com/2/places/4BPSFLKJSDFLKJSDFLKJ"
    }
}

A Region object describes a geographical boundary or set of hardware identifiers and associated attributes that correspond to a physical location of relevance to the application or application owner.

OBJECT PROPERTIES
  • attributes object

    An attribute object is an object containing the customer-provided region attributes associated with a particular region.

  • beacons array[object]

    An array of beacon objects.

  • created_at stringREQUIRED

    The creation date-time for the region.

  • geofence object<Geofence object>

    A Geofence object describes a geographical boundary corresponding to a physical location of relevance to the application or application owner. The geofence type can be a polygon, a circle, or provided by a confidential source.

  • name string

    A human-readable name for the region.

  • region_id stringREQUIRED

    A string containing a UUID that is the canonical identifier for this object, elsewhere referred to as region_id.

  • source_info object

    A Source Info object is a simple JSON object providing the details about the origin of the region data.

    OBJECT PROPERTIES
    • region_id stringREQUIRED

      Internal identifier used by source for this region.

    • source stringREQUIRED

      Name of the company who originated the region data.

    • vendor_href string

      URI indicating the location of the original source of this region data.

  • updated_at stringREQUIRED

    The last updated date-time for the region.

Permissions

OAuth Scope

The value of the scope parameter is a list of space-delimited, case-sensitive strings. If multiple scopes are specified, their order does not matter. Each string adds an additional access range to the requested scope.

  • att: Attachments
  • chn: Channels
  • evt: Events
  • lst: Lists
  • nu: Named Users
  • pln: Pipelines
  • psh: Push
  • sch: Schedules

Subject

A space-delimited set of identifiers for which subjects a token is allowed. Example: app:JQIMcndxIHWy2QISpt1SpZ

  • app: May operate on the given app

Personalization template objects

Personalization templates objects, including pushes to templates and template listing.

Push template payload

Push template payload example

{
   "audience": {
      "tag": [
         "yanny",
         "laurel"
      ]
   },
   "device_types": [
      "email",
      "ios",
      "android",
      "web"
   ],
   "merge_data": {
      "template_id": "8cce6cc8-7d78-43c7-80b5-81ac24c07672",
      "substitutions": {
         "FIRST_NAME": "Bob",
         "LAST_NAME": "Takahashi",
         "TITLE": null
      }
   },
   "campaigns": {
      "categories": [
         "winter sale",
         "west coast"
      ]
   }
}

A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

OBJECT PROPERTIES
  • audience object<Audience selector (max 1000)>REQUIRED

    The audience for the template.

    An audience selector forms the expression that determines the set of channels to target.

  • campaigns object<Campaigns object>

    An object specifying custom campaign categories related to the notification.

  • device_types array[string]REQUIRED

    An array containing one or more strings identifying targeted platforms.

  • merge_data objectREQUIRED

    A template selector describing the template ID and variable substitutions to use with it.

    OBJECT PROPERTIES
    • substitutions object

      An object containing overrides for your template’s variables. The key-value pairs in this object are the value of the key items defined in your template, and the values you want to substitute for the default_value of those keys.

    • template_id stringREQUIRED

      Specifies the template to override; corresponds to the id in /templates responses.

Template object

Basic template object

{
   "name": "<template name>",
   "description": "<template description>",
   "variables": ["<variable specifications>"],
   "push": "<push-object>",
   "id": "<template-id>",
   "created_at" : "timestamp",
   "modified_at" : "timestamp",
   "last_used" : "timestamp"
}

A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints.

OBJECT PROPERTIES
  • created_at string

    The date-time when this template was created.

  • description string

    The description for the template.

  • id string

    The unique ID assigned to this template. Used to retrieve or use the template in other endpoints.

  • last_used string

    The date-time when this template’s definition was last used. This attribute cannot template-based specified when the template is created and will only be present when template objects are provided by the template retrieval and template listing endpoints.

  • modified_at string

    The date-time when this template was last modified.

  • name stringREQUIRED

    The name of the template.

  • push object<Template push object>

    A partial push object describing everything about a push notification, except for the audience and device_types keys (which are defined in the Push template payload) and the message key (which is incompatible with templates).

  • variables arrayREQUIRED

    An array of variable specifications. Variables can be customized when pushing based on the template.

Template push object

Example

{
    "audience" : {
        "OR" : [
            { "tag" : ["sports", "entertainment"]},
            { "device_token" : "871922F4F7C6DF9D51AC7ABAE9AA5FCD7188D7BFA19A2FA99E1D2EC5F2D76506" },
            { "apid" : "5673fb25-0e18-f665-6ed3-f32de4f9ddc6" }
        ]
    },
    "device_types" : [ "ios" ],
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "FIRST_NAME": "Bob"
        }
    }
}

A partial push object describing everything about a push notification, except for the audience and device_types keys (which are defined in the Push template payload) and the message key (which is incompatible with templates).

OBJECT PROPERTIES
  • campaigns object<Campaigns object>

    An object specifying custom campaign categories related to the notification.

  • in_app object<In-app message>

    A JSON object describing an in-app message payload.

  • no_throttle boolean

    If true, the push will ignore global throttling rates that have been configured for the application, resulting in delivery as quickly as possible.

  • notification object<Notification object>

    The notification payload that is required unless either message or in_app is present. You can provide an alert and any platform overrides that apply to the device_type platforms you specify.

  • options object

    A JSON dictionary for specifying non-payload options related to the delivery of the push.

    OBJECT PROPERTIES
    • expiry object

      Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

      One of

Template variables

Template variable example

{
   "key" : "<key>",
   "name" : "<variable name>",
   "description" : "<variable description>",
   "default_value" : "<fallback value>"
}

A template variable object describes the pieces of your template to override when creating template-based pushes. These are the fields you want to customize when you send a push based on the template.

OBJECT PROPERTIES
  • default_value string

    A default value for the variable. If the key for this variable is not specified in a Template Selector (substitutions) when issuing push notifications based on this template, the push will use this value.

  • description string

    A description of the variable.

  • key stringREQUIRED

    The key used to reference the variable inside the template push. (32 chars, starting and ending with alphanumeric characters, and consisting of alphanumeric characters and underscores).

  • name string

    A friendly name for the variable.

Actions

Example add custom event action

{
   "actions": {
       "add_custom_event": {
          "name": "myCustomEvent",
          "value": 12.5,
          "properties": {
             "property_key1": "value_property1",
             "property_key2": 6789
          }
       }
   }
}

Example tag actions

{
   "actions": {
       "add_custom_event": {
          "name": "myCustomEvent",
          "value": 12.5,
          "properties": {
             "property_key1": "value_property1",
             "property_key2": 6789
          }
       }
   }
}

{
   "actions": {
      "add_tag": [
         "airship",
         "blimp"
      ],
      "remove_tag": [
         "boat",
         "car"
      ],
      "share": "Check out Airship!",
      "open": {
         "type": "url",
         "content": "http://www.urbanairship.com"
      },
      "app_defined": {
         "some_app_defined_action": "some_value"
      }
   }
}

Example landing page action

{
   "actions": {
       "add_custom_event": {
          "name": "myCustomEvent",
          "value": 12.5,
          "properties": {
             "property_key1": "value_property1",
             "property_key2": 6789
          }
       }
   }
}

{
   "actions": {
      "add_tag": [
         "airship",
         "blimp"
      ],
      "remove_tag": [
         "boat",
         "car"
      ],
      "share": "Check out Airship!",
      "open": {
         "type": "url",
         "content": "http://www.urbanairship.com"
      },
      "app_defined": {
         "some_app_defined_action": "some_value"
      }
   }
}

{
   "actions": {
      "open": {
         "type": "landing_page",
         "content": {
            "body": "<html>content</html>",
            "content_type": "text/html",
            "content_encoding": "utf-8"
         },
         "fallback_url" : "https://www.urbanairship.com/settings"
      }
   }
}

Example open phone app

{
   "actions": {
       "add_custom_event": {
          "name": "myCustomEvent",
          "value": 12.5,
          "properties": {
             "property_key1": "value_property1",
             "property_key2": 6789
          }
       }
   }
}

{
   "actions": {
      "add_tag": [
         "airship",
         "blimp"
      ],
      "remove_tag": [
         "boat",
         "car"
      ],
      "share": "Check out Airship!",
      "open": {
         "type": "url",
         "content": "http://www.urbanairship.com"
      },
      "app_defined": {
         "some_app_defined_action": "some_value"
      }
   }
}

{
   "actions": {
      "open": {
         "type": "landing_page",
         "content": {
            "body": "<html>content</html>",
            "content_type": "text/html",
            "content_encoding": "utf-8"
         },
         "fallback_url" : "https://www.urbanairship.com/settings"
      }
   }
}

{
   "actions": {
      "open": {
         "type": "url",
         "content": "tel:15035551234"
      }
   }
}

Example deep link action

{
   "actions": {
       "add_custom_event": {
          "name": "myCustomEvent",
          "value": 12.5,
          "properties": {
             "property_key1": "value_property1",
             "property_key2": 6789
          }
       }
   }
}

{
   "actions": {
      "add_tag": [
         "airship",
         "blimp"
      ],
      "remove_tag": [
         "boat",
         "car"
      ],
      "share": "Check out Airship!",
      "open": {
         "type": "url",
         "content": "http://www.urbanairship.com"
      },
      "app_defined": {
         "some_app_defined_action": "some_value"
      }
   }
}

{
   "actions": {
      "open": {
         "type": "landing_page",
         "content": {
            "body": "<html>content</html>",
            "content_type": "text/html",
            "content_encoding": "utf-8"
         },
         "fallback_url" : "https://www.urbanairship.com/settings"
      }
   }
}

{
   "actions": {
      "open": {
         "type": "url",
         "content": "tel:15035551234"
      }
   }
}

{
   "actions": {
      "open": {
         "type": "deep_link",
         "content": "prefs",
         "fallback_url": "https://www.urbanairship.com/settings"
      }
   }
}

Example Subscription List action

{
   "actions": {
       "add_custom_event": {
          "name": "myCustomEvent",
          "value": 12.5,
          "properties": {
             "property_key1": "value_property1",
             "property_key2": 6789
          }
       }
   }
}

{
   "actions": {
      "add_tag": [
         "airship",
         "blimp"
      ],
      "remove_tag": [
         "boat",
         "car"
      ],
      "share": "Check out Airship!",
      "open": {
         "type": "url",
         "content": "http://www.urbanairship.com"
      },
      "app_defined": {
         "some_app_defined_action": "some_value"
      }
   }
}

{
   "actions": {
      "open": {
         "type": "landing_page",
         "content": {
            "body": "<html>content</html>",
            "content_type": "text/html",
            "content_encoding": "utf-8"
         },
         "fallback_url" : "https://www.urbanairship.com/settings"
      }
   }
}

{
   "actions": {
      "open": {
         "type": "url",
         "content": "tel:15035551234"
      }
   }
}

{
   "actions": {
      "open": {
         "type": "deep_link",
         "content": "prefs",
         "fallback_url": "https://www.urbanairship.com/settings"
      }
   }
}

{
   "actions": {
      "subscription_list": [
         {
            "action": "subscribe",
            "type": "contact",
            "list_id": "cool_deals",
            "scope": "app"
         }
      ]
   }
}

Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

OBJECT PROPERTIES
  • add_custom_event object

    Emit a custom event when a user interacts with the push notification.

    OBJECT PROPERTIES
    • name stringREQUIRED

      The name of the custom event.

    • properties object

      A JSON object with the properties associated with the event.

    • value number

      An integer or decimal value of the event.

  • add_tag array[string]

    An array of tags.

  • app_defined object

    A map of registered action names to payloads as defined by the app or SDK. Some of these actions are supported as their own property on the Actions object, but be aware that their registered names in the SDK may be different. For a summary of the actions registered by the SDK, including usage information, see the Mobile docs.

  • open object

    Open action. When a user interacts with the notification, opens one of: URL, deep link, or landing page as described in the associated content property.

    One of
    • Open URL Action object

      Opens a URL or passes a string for use as a custom action.

      OBJECT PROPERTIES
      • content stringREQUIRED

        Any string. A URL string that starts with either http or https will open a URL or a string that starts with tel: followed by a sequence of numbers will open the phone app.

      • type stringREQUIRED

        Possible values: url

    • Open Deep Link Action object

      Opens a deep link.

      OBJECT PROPERTIES
      • content stringREQUIRED

        A non-blank string.

      • fallback_url string

        A URL that can be used on platforms that don’t have full support for the otherwise defined action.

      • type stringREQUIRED

        Possible values: deep_link

    • Open Landing Page object

      Opens a landing page.

      OBJECT PROPERTIES
  • remove_tag array[string]

    An array of tags.

  • share string

    String indicating the text that will populate the share action.

  • subscription_list array[object]

    Alter subscription list membership for a channel or contact.

Assertion JWT

A JSON Web Token (JWT) used for authorization in OAuth token requests. The JWT must be signed with the private key corresponding to the client_id in the kid header using the ES384 algorithm.

All of
  • Headers object

    Assertion JWT headers

    OBJECT PROPERTIES
    • alg stringREQUIRED

      The signing algorithm.

      Possible values: ES384

    • kid stringREQUIRED

      The key used to sign the JWT, the client_id.

  • Claims object

    Assertion JWT claims

    OBJECT PROPERTIES
    • aud stringREQUIRED

      The valid request endpoint. Example: https://oauth2.asnapius.com/token

    • exp integerREQUIRED

      The assertion’s expiration timestamp in seconds since epoch, after which it is not valid. The expiry must not be more than 10 minutes in the future. This is for the assertion, not for the token that will be returned. Example: 1681862754

    • iat integerREQUIRED

      The issue timestamp in seconds since epoch. Example: 168186250

    • ipaddr string

      A space-delimited list of CIDR representations of valid IP addresses to which the issued token is restricted.

    • iss stringREQUIRED

      The issuer, the client_id.

    • nonce stringREQUIRED

      A unique string that must not have been used recently with this client_id. We will store this for a minimum of 2 hours. If you are relying on the nonce to defend against replay attacks, it is recommended to also enforce a narrow ipaddr range in order to prevent requests that utilize the returned access token from being replayed by an outside client.

    • scope object<OAuth Scope>

      A space-delimited list of scopes to which the returned claim should be restricted. If not provided, the full list of scopes the client_id is granted will be in the returned claim.

      The value of the scope parameter is a list of space-delimited, case-sensitive strings. If multiple scopes are specified, their order does not matter. Each string adds an additional access range to the requested scope.

      • att: Attachments
      • chn: Channels
      • evt: Events
      • lst: Lists
      • nu: Named Users
      • pln: Pipelines
      • psh: Push
      • sch: Schedules

    • sub object<Subject>REQUIRED

      A space-delimited set of identifiers for which subjects a token is allowed. An app subject is required. Example: app:JQIMcndxIHWy2QISpt1SpZ.

      A space-delimited set of identifiers for which subjects a token is allowed. Example: app:JQIMcndxIHWy2QISpt1SpZ

      • app: May operate on the given app

Array

The array can hold string, number, boolean, objects, and array. Accepts numbers and strings for integer/number type attributes, but your string must be convertible to a number or the request will fail. Objects must be valid JSON or the request will fail.

Audience limits object

Audience limits

{
  "options": {
    "audience_limits": {
      "max_recipients": 1000
    }
  }
}

Defines limits to be applied to Push Notifications and standard in-app messages (not In-App Automations or Scenes) only. See Audience Limit in the Message delivery user guide for additional information and limitations.

OBJECT PROPERTIES
  • max_recipients integer

    The maximum number of recipients a push can be delivered to.

Ban List parameters

Ban List parameters

{
  "ban_list_parameters": {
    "category": "api-cat"
  }
}

A list of parameters, where the key and value are both strings, that will be used to override the default values set for variables in a Ban List request URL.

OBJECT PROPERTIES
  • * string

Bulk send object

Bulk send object

{
    "audience" : {
        "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
    },
    "device_types" : [ "open::rcs" ],
    "notification" : {
        "alert" : "Welcome to the winter sale!!"
    },
    "campaigns": {
        "categories": ["winter sale", "west coast"]
    }
}

A bulk send object describes everything about a Send message with bulk ID or Schedule message with bulk ID notification. The acceptable fields are identical to a standard push with two exceptions. The audience field can only be a single bulk_id and there can only be one device_type.

OBJECT PROPERTIES
  • audience objectREQUIRED
    OBJECT PROPERTIES
  • campaigns object<Campaigns object>

    An object specifying custom campaign categories related to the notification.

  • device_types array[string]REQUIRED

    An array containing exactly one targeted platform.

  • feed_references object<Feed references object>

    An object used to indicate that an external data feed should be invoked, the name of the feed to invoke, and the way in which to invoke it. You can only include a feed if you include a templates object in the payload or set the personalization option to true.

  • global_attributes object

    The global attributes object may contain an arbitrary set of keys and values, including arrays and nested objects, which will be added to the global attributes rendering namespace for this push. Top-level keys must start with a letter and cannot start with the reserved sequence ua_. If the global attributes object is nonempty, it implies the personalization: true option.

  • in_app object<In-app message>

    A JSON object describing an in-app message payload.

  • localizations array

    An array of localizations. Channels bearing the specified language/country combination will receive the corresponding message.

  • message object
    One of
  • message_type object<Message type>

    Indicates the purpose of a message.

  • notification object<Notification object>

    The notification payload that is required unless either message or in_app is present. You can provide an alert and any platform overrides that apply to the device_type platforms you specify.

  • options object<Push options>

    A JSON dictionary for specifying non-payload options related to the delivery of the push.

  • orchestration object

    An object used to indicate the strategy to employ when deciding which channels to target for a contact. An orchestration object can be stored in Airship as the default strategy. If the orchestration section is included in a push payload, it will override the configured default value. The overall default strategy is fan_out.

    OBJECT PROPERTIES
    • channel_priority array[string]

      An array of channel types in priority order. Required if type is set to channel_priority.

    • type stringREQUIRED

      The name of the orchestration strategy to employ.

      Possible values: channel_priority, fan_out, triggering_channel, last_active

  • snippet_references object<Snippet references object>

    An object used to indicate that a set of snippets should be loaded for use in message content. Use the following syntax in your payload: {{> your_snippet_name }} to reference the snippet content within a notification or rich message.

    See Snippets to see how to create a snippet in the Airship dashboard.

Campaigns object

Example campaigns in a push payload

{
   "audience": "all",
   "notification": {
      "alert": "Taco Kitten wins Kentucky Derby by a whisker"
   },
   "campaigns": {
      "categories": [
         "kittens",
         "tacos",
         "horse_racing"
      ]
   },
   "device_types": [ "ios", "android" ]
}

An object specifying custom campaign categories related to the notification.

OBJECT PROPERTIES
  • categories array[string]REQUIRED

    Array of strings representing the campaigns you wish to associate with the notification. Must have between 1 to 10 items in the array with a 64 character/byte maximum per item.

Channel Contact operation device info object

Additional device information that is not included in the headers.

OBJECT PROPERTIES
  • device_type stringREQUIRED

    The device type of the channel.

    Possible values: ios, android, amazon, web, email, sms, open

Identify action object

Example identify contact operation

{
  "device_info": {
    "device_type": "android"
  },
  "action": {
    "type": "identify",
    "named_user_id": "my-named-user",
    "contact_id": "a29ce8c7-4a63-37cb-9716-dffd3d419c4a"
  }
}

A Channel Contact operation using this object associates a channel to a Named User and attempts to identify the Named User with a specific Contact ID. If the Named User does not yet exist, it will be created with the Anonymous Contact ID that the channel is already associated to. If the channel is not associated to an Anonymous Contact, the Named User will be created using the optionally provided Contact ID or a randomly generated Contact ID if there is no Contact ID provided or the provided Contact ID is already bound to a Named User.

OBJECT PROPERTIES
  • contact_id string

    Contact ID to associate to the Named User if it is not already associated to a Contact. Otherwise it will be ignored.

  • named_user_id stringREQUIRED

    Identifies the Named User, with no leading or trailing whitespace.

  • type stringREQUIRED

    The action to be carried out.

    Possible values: identify

Channel Contact operation object

Contains device_info and action.

OBJECT PROPERTIES
  • action objectREQUIRED
    One of
    • Channel Contact Operation Resolve Action Object

      A Channel Contact operation using this object results in either resolving the current associated Contact (named or anonymous) for that channel or it will associate that channel to an Anonymous Contact, always returning a Contact ID for the SDK to store. A Contact ID can optionally be provided, which the channel will be associated to in the event the channel is not already associated to a Contact and the provided Contact ID is not already bound to a Named User.

    • Channel Contact Operation Identify Action Object

      A Channel Contact operation using this object associates a channel to a Named User and attempts to identify the Named User with a specific Contact ID. If the Named User does not yet exist, it will be created with the Anonymous Contact ID that the channel is already associated to. If the channel is not associated to an Anonymous Contact, the Named User will be created using the optionally provided Contact ID or a randomly generated Contact ID if there is no Contact ID provided or the provided Contact ID is already bound to a Named User.

    • Channel Contact Operation Reset Action Object

      A Channel Contact operation using this object is mostly equivalent to Named Users disassociation, but instead of leaving the channel disassociated, it associates the channel to a new Anonymous Contact after disassociation from the current Contact.

  • device_info object<Channel Contact operation device info object>REQUIRED

    Additional device information that is not included in the headers.

Reset action object

Example reset contact operation

{
  "device_info": {
    "device_type": "android"
  },
  "action": {
    "type": "reset"
  }
}

A Channel Contact operation using this object is mostly equivalent to Named Users disassociation, but instead of leaving the channel disassociated, it associates the channel to a new Anonymous Contact after disassociation from the current Contact.

OBJECT PROPERTIES
  • type stringREQUIRED

    The action to be carried out.

    Possible values: reset

Resolve action object

Example resolve contact operation

{
  "device_info": {
    "device_type": "ios"
  },
  "action": {
    "type": "resolve"
  }
}

A Channel Contact operation using this object results in either resolving the current associated Contact (named or anonymous) for that channel or it will associate that channel to an Anonymous Contact, always returning a Contact ID for the SDK to store. A Contact ID can optionally be provided, which the channel will be associated to in the event the channel is not already associated to a Contact and the provided Contact ID is not already bound to a Named User.

OBJECT PROPERTIES
  • contact_id string

    Contact ID to associate to the channel if it is not already associated to a Contact.

  • type stringREQUIRED

    The action to be carried out.

    Possible values: resolve

Identify Contact response object

Information about the Contact.

OBJECT PROPERTIES
  • channel_association_timestamp string

    The date-time when the channel association occurred.

  • contact_id string

    Internal Contact ID.

  • is_anonymous boolean

    Specifies whether the Contact is anonymous or not.

Channel listing object

Example iOS channel

{
   "channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881",
   "device_type": "ios",
   "installed": true,
   "background": true,
   "opt_in": false,
   "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
   "created": "2020-08-08T20:41:06",
   "last_registration": "2020-05-01T18:00:27",
   "named_user_id": "some_id_that_maps_to_your_systems",
   "alias": null,
   "tags": [
      "tag1",
      "tag2"
   ],

   "tag_groups": {
      "sports fan": ["Federer fan", "Messi fan"],
      "music fan": [ "Beyonce", "Muse" ],
      "ua_locale_country": [ "US" ],
      "ua_locale_language": [ "en" ]
   },

   "ios": {
      "badge": 0,
      "quiettime": {
         "start": null,
         "end": null
      },
      "tz": "America/Los_Angeles"
   }
}

Describes a channel listing object.

OBJECT PROPERTIES
  • address string

    The address to send push notifications to when device_type is email or open. For all other device_type values, this key is replaced with push_address.

  • alias stringDEPRECATED

    Displays the alias associated with the channel, if one exists. Aliases are the precursor to Named Users, our user mapping system. If you are using aliases, please upgrade to Named Users. Listed as null when not set.

  • attributes object<Custom and predefined Attributes>

    A dictionary of attributes that you’ve associated with the channel. See the Attributes guide for more information about creating and assigning attributes.

    The attributes listed here are “predefined” by Airship, but you can create new attributes in the Airship dashboard.

    Attributes associated with a channel or Named User. This object contains predefined attributes that you enable and assign to the channel, or custom attributes that you create and assign.

    This object enumerates predefined attributes, but you can create your own in the Airship dashboard.

  • background boolean

    If true, the device can receive background push notifications. If false, it cannot. This field only appears for iOS devices.

  • channel_id string

    The unique channel identifier for a device.

  • commercial_opted_in string

    The date-time when a user gave explicit permission to receive commercial emails.

  • commercial_opted_out string

    The date-time when a user explicitly denied permission to receive commercial emails.

  • created string

    The creation date-time of this channel.

  • device_attributes object<Device Attributes>

    Native attribute properties that Airship gathers automatically assigns to a channel. Varies by channel type. See: Default Attributes.

    For segmentation, when using ua_app_version, ua_sdk_version, or ua_device_os, only semantic versioning formatting is accepted, and anything after the third decimal place is excluded, e.g., 12.2.3-alpha is compared as 12.2.3. You can use operators equals, contains, less, greater, is_empty with values in the formats 1, 1.2, 1.2.3.

  • device_type string

    Specifies the device platform for a channel.

    Possible values: ios, android, amazon, web, open, email, sms

  • email_address string

    The email address associated with the email channel when device_type is email.

  • installed boolean

    If true, the channel is installed. If false, it is uninstalled.

  • ios object<iOS channel object>

    Contains parameters that apply when the device_type is set to ios.

  • last_registration string

    The last registration date-time of this channel, if known.

  • msisdn string

    The phone number associated with the SMS channel. Must be numeric characters only, without leading zeros.

  • named_user_id string

    A customer-chosen ID that represents the device user, e.g., CRM ID. This ID cannot have leading or trailing whitespace. Listed as null when not set.

  • open object<Open channel options>

    Contains options that apply when the device_type is set to open.

  • opt_in boolean

    If true, the channel is opted in to push notifications. If false, it is not. Required for all types except email.

  • opt_in_date string

    (SMS only) The date-time when the SMS channel gave permission to receive messages.

  • opt_out_date string

    (SMS only) The date-time when the SMS channel opted out of receiving messages.

  • push_address string

    Required if opt_in is true. The address to send push notifications to for all device_type values other than email and open. When device_type is email or open, this key is replaced with address.

  • subscription_lists array

    Lists all the subscription lists that this channel is subscribed to.

  • suppression_state string

    If an email channel is suppressed, the reason for its suppression. Email channels with any suppression state set will not have any delivery to them fulfilled. If a more specific reason is not known, use imported.

    Possible values: spam_complaint, commercial_spam_complaint, bounce, imported

  • tag_groups object<Tag Group object>

    One or more tag group objects (including Device Property Tags) associated with this channel.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • tags array[string]

    An array of tags associated with this channel.

  • transactional_opted_in string

    The date-time when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out.

  • transactional_opted_out string

    The date-time when a user explicitly denied permission to receive transactional emails.

  • web object

    Contains parameters that apply when the device_type is set to web.

    OBJECT PROPERTIES
    • subscription object

      The web subscription. This optional field is not present for cases where a browser is registered (for purposes of Feature Flags) but isn’t opted-in to push notifications.

      OBJECT PROPERTIES
      • keys object

        Encryption keys required for signing the push package.

        OBJECT PROPERTIES
        • auth string

          The authentication secret.

        • p256dh string

          The public key.

    • user_agent_string string

      The full user agent string.

Contact subscription lists object

Example contact Subscription Lists object

{
   "list_ids": ["example_listId-2", "example_listId-4"],
   "scope": "app"
}

A list of subscription list items associated with the specified contact. Each item consists of a list of list IDs and an optional scope.

OBJECT PROPERTIES
  • list_ids arrayREQUIRED

    A list of subscription lists associated to the specified scope. If no scope is specified these subscription lists are not scoped.

  • scope object<Scopes>

    The channel types where membership applies. The app scope includes iOS, Android, and Amazon channels.

Custom Event object

Example Custom Event

{
   "occurred": "2020-05-02T02:31:22",
   "user": {
       "named_user_id": "cool.person"
   },
   "body": {
       "name": "purchased",
       "value": 239.85,
       "transaction": "686f53d4-7e0s-36d7-234e-c9792dac6e7b",
       "interaction_id": "your.store/us/en_us/pd/shoe/pid-123456/pgid-123456",
       "interaction_type": "email",
       "unique_id": "4c2c380a-0400-4d34-ab04-aaf31f0967c7",
       "properties": {
          "description": "sky high",
          "brand": "victory",
          "colors": [
          "red",
          "blue"
          ],
          "items": [
          {
             "text": "New Line Sneakers",
             "price": "$ 79.95"
          },
          {
             "text": "Old Line Sneakers",
             "price": "$ 79.95"
          },
          {
             "text": "Blue Line Sneakers",
             "price": "$ 79.95"
          }
          ],
          "name": "Cool Person",
          "userLocation": {
          "state": "CO",
          "zip": "80202"
          }
       },
      "session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
   }
}

Defines a Custom Event.

OBJECT PROPERTIES
  • body objectREQUIRED

    Contains information about your Custom Event. While only the event name is required, it is recommended that you provide as much information in this object as possible, so that your event is relevant and informative.

    OBJECT PROPERTIES
    • interaction_id string

      The identifier defining where the event occurred. In a traditional website, this would be the path and query string from the URL. In a single page app that uses hash routing, it would be the path, query string, and fragment identifier.

    • interaction_type string

      Describes the type of interaction that triggered the event, e.g., url, social, email. This should almost always be ‘url’ for web events. Airship can separate events with the same name by interaction_type, providing greater insight into Custom Events.

    • name stringREQUIRED

      A plain-text name for the event. Airship’s analytics systems will roll up events with the same name, providing counts and total value associated with the event. This value cannot contain upper-case characters. If the name contains upper-case characters, you will receive a 400 response.

    • properties object

      An object containing Custom Event properties. You can use handlebars to access Custom Event properties in templates or messages triggered by the Custom Event. Items in the properties object are limited to a 255 character maximum string length.

    • session_id string

      The user session during which the event occurred. You must supply and maintain session identifiers.

    • transaction string

      If the event is one in a series representing a single transaction, use the transaction field to tie events together.

    • unique_id string

      If properties for the Custom Event are being used for triggering and personalizing a Sequence, use a unique ID to introduce uniqueness in order to differentiate messages and prevent dropping sends as duplicates.

    • value number

      If the event is associated with a count or amount, the ‘value’ field carries that information. Airship will treats this field as a representation of money; mathematical operations will use fixed precision representations of this field. The value field respects six digits of precision to the right of the decimal point. This field is optional; if empty, its value will default to zero.

  • occurred string

    The date-time when the event occurred. Events must have occurred within the past 90 days. You cannot provide a future date-time. If omitted, the current date-time is used.

  • user objectREQUIRED

    Contains the Airship channel identifier for the user who triggered the event.

    One of
    • Named User object
      OBJECT PROPERTIES
      • named_user_id string

        The Named User associated with the event.

    • Fire OS Channel object
      OBJECT PROPERTIES
      • amazon_channel string

        The unique channel identifier for a Fire OS device.

    • Android Channel object
      OBJECT PROPERTIES
      • android_channel string

        The unique channel identifier for an Android device.

    • iOS Channel object
      OBJECT PROPERTIES
      • ios_channel string

        The unique channel identifier for an iOS device.

    • Web Channel object
      OBJECT PROPERTIES
      • web_channel string

        The unique channel identifier for a web device.

    • Generic Channel object
      OBJECT PROPERTIES
      • channel string

        Airship canonical identifier for a user. Airship will determine the device.

Email channel associated by contact

Example

{
  "type": "email",
  "channel_id": "463c4643-a16c-48da-9585-f2c5406f828b",
  "email_address": "d*******r@example.com",
  "commercial_opted_in": "2024-02-11T00:00:00"
}

An email channel associated with a contact.

OBJECT PROPERTIES
  • channel_id string

    The unique identifier.

  • commercial_opted_in string

    The date-time when a user gave explicit permission to receive commercial emails.

  • email_address string

    The email address corresponding to the channel.

  • type string

    The channel type.

    Possible values: email

Experiment object

Example

{
   "name": "<experiment name>",
   "description": "<experiment description>",
   "control": "<control group>",
   "audience": "<audience-selection>",
   "device_types": "<device-types>",
   "campaigns": "<campaigns>",
   "variants": "[<variant specifications>]",
   "id": "<id>",
   "created_at": "timestamp",
   "push_id": "<push_id>"
}

An experiment object describes an A/B test, including the audience and variant portions.

OBJECT PROPERTIES
  • audience object<Audience selector (max 1000)>REQUIRED

    The audience for the experiment.

    An audience selector forms the expression that determines the set of channels to target.

  • campaigns object<Campaigns object>

    Campaigns object that will be applied to resulting pushes.

    An object specifying custom campaign categories related to the notification.

  • control number

    The proportional subset of the audience that will not receive a push. The remaining audience will be split between the variants. It may help to think of this value as a percentage. See Audience groups in the API in Message A/B tests.

  • created_at string

    The date-time when the experiment was created. This value is created and assigned automatically by Airship and appears in responses only.

  • description string

    A description of the experiment.

  • device_types array[string]REQUIRED

    An array containing one or more strings identifying targeted platforms.

  • id string

    The unique ID assigned to this experiment. This value is created and assigned automatically by Airship and appears in responses only.

  • name string

    A name for the experiment.

  • push_id string

    The push ID associated with this experiment. This value is created and assigned automatically by Airship and appears in responses only.

  • variants array[object]REQUIRED

    The variants for the experiment. An experiment must have at least 1 variant and no more than 26.

iOS channel object

Contains parameters that apply when the device_type is set to ios.

OBJECT PROPERTIES
  • badge integer

    The iOS badge number. Must be greater than zero.

  • quiettime object

    Quiet time settings. Requires presence of tz.

    OBJECT PROPERTIES
    • end string

      Quiet time end in HH:MM format.

    • start string

      Quiet time start in HH:MM format.

  • scheduled_summary boolean

    If true, the scheduled summary notification status is enabled.

  • time_sensitive boolean

    If true, the time sensitive notification status is enabled.

  • tz string

    The channel’s time zone. A list of possible time zone values is maintained at the IANA Time Zone Database .

In-app message

Example

{
   "audience": "all",
   "device_types": [ "ios", "android" ],
   "notification": { "alert": "This part appears on the lockscreen" },
   "in_app": {
      "alert": "This part appears in-app!",
      "display_type": "banner",
      "expiry": "2020-04-01T12:00:00",
      "display": {
         "position": "top"
      },
      "actions": {
         "add_tag": "in-app"
      }
   }
}

A JSON object describing an in-app message payload.

OBJECT PROPERTIES
  • actions object<Actions>

    Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

  • alert stringREQUIRED

    The text displayed on the in-app message.

  • display object

    The allowed fields for this object depend on the value of of the display_type field. Currently, the only valid display_type is banner, so the following is an associated display object for the banner display type.

    OBJECT PROPERTIES
    • duration integer

      Specifies how long the notification should stay on the screen in seconds before automatically disappearing; set to 15 by default.

    • position string

      One of either top or bottom, specifies the screen position of the message. Defaults to bottom.

      Possible values: top, bottom

    • primary_color string

      Specifies the primary color of the in-app message (format #rrggbb).

    • secondary_color string

      Specifies the secondary color of the in-app message (format #rrggbb).

  • display_type stringREQUIRED

    Specifies the display type.

    Possible values: banner

  • expiry object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • extra object

    A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.

  • interactive object<Interactive notification object>

    An interactive notification.

    Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

Interactive notification object

Example with `type` actions

{
   "interactive": {
      "type": "ua_yes_no_foreground",
      "button_actions": {
         "yes": {
            "add_tag": "more_cake_please",
            "remove_tag": "lollipop",
            "open": {
               "type": "url",
               "content": "http://www.urbanairship.com"
            }
         },
         "no": {
            "add_tag": "nope"
         }
      }
   }
}

Example with `ua_share` actions

{
   "interactive": {
      "type": "ua_yes_no_foreground",
      "button_actions": {
         "yes": {
            "add_tag": "more_cake_please",
            "remove_tag": "lollipop",
            "open": {
               "type": "url",
               "content": "http://www.urbanairship.com"
            }
         },
         "no": {
            "add_tag": "nope"
         }
      }
   }
}

{
   "interactive": {
      "type": "ua_share",
      "button_actions": {
         "share": { "share": "Look at me! I'm on a boat." }
      }
   }
}

An interactive notification.

Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

OBJECT PROPERTIES
  • button_actions object

    An object containing keys that must be the button IDs for the specified interactive notification type. If the notification type begins with ua_, the keys must match exactly the button IDs for that type or a strict subset. The names of the button IDs cannot be validated for custom notifications.

    One of
    • Yes/No object

      Yes/No button action

      OBJECT PROPERTIES
      • no object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • yes object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Accept/Decline object

      Accept/decline button action

      OBJECT PROPERTIES
      • accept object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • decline object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Shop Now object

      Shop now button action

      OBJECT PROPERTIES
      • shop_now object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Buy Now object

      Buy now button action

      OBJECT PROPERTIES
      • buy_now object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Follow object

      Follow button action

      OBJECT PROPERTIES
      • follow object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Opt In object

      Opt in button action

      OBJECT PROPERTIES
      • opt_in object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Unfollow object

      Unfollow button action

      OBJECT PROPERTIES
      • unfollow object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Opt Out object

      Opt out button action

      OBJECT PROPERTIES
      • opt_out object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Opt In/Remind object

      Opt in/remind button action

      OBJECT PROPERTIES
      • opt_in object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • remind object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Remind object

      Remind button action

      OBJECT PROPERTIES
      • remind object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • More Info object

      More info button action

      OBJECT PROPERTIES
      • more_info object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Download object

      Download button action

      OBJECT PROPERTIES
      • download object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Share object

      Share button action

      OBJECT PROPERTIES
      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Download/Share object

      Download/share button action

      OBJECT PROPERTIES
      • download object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Remind/Share object

      Remind/share button action

      OBJECT PROPERTIES
      • remind object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Opt In/Share object

      Opt in/share button action

      OBJECT PROPERTIES
      • opt_in object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Opt Out/Share object

      Opt out/share button action

      OBJECT PROPERTIES
      • opt_out object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Follow/Share object

      Follow/share button action

      OBJECT PROPERTIES
      • follow object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Unfollow/Share object

      Unfollow/share button action

      OBJECT PROPERTIES
      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • unfollow object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Shop Now/Share object

      Shop now/share button action

      OBJECT PROPERTIES
      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • shop_now object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Buy Now/Share object

      Buy now/share button action

      OBJECT PROPERTIES
      • buy_now object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • More Like/Less Like object

      More like/less like button action

      OBJECT PROPERTIES
      • less_like object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • more_like object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Like/Dislike object

      Like/dislike button action

      OBJECT PROPERTIES
      • dislike object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • like object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Like object

      Like button action

      OBJECT PROPERTIES
      • like object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Like/Share object

      Like/share button action

      OBJECT PROPERTIES
      • like object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Add to Calendar/Remind object

      Add to calendar/remind button action

      OBJECT PROPERTIES
      • add_calendar object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • remind object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Add object

      Add button action

      OBJECT PROPERTIES
      • add object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Save object

      Save button action

      OBJECT PROPERTIES
      • save object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Follow/Save object

      Follow/Save button action

      OBJECT PROPERTIES
      • follow object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • save object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Rate object

      Rate button action

      OBJECT PROPERTIES
      • rate object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Rate/Remind object

      Rate/remind button action

      OBJECT PROPERTIES
      • rate object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • remind object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Search object

      Search button action

      OBJECT PROPERTIES
      • search object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Book object

      Book button action

      OBJECT PROPERTIES
      • book object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Happy/Sad object

      Happy/Sad button action

      OBJECT PROPERTIES
      • happy object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • sad object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Up/Down object

      Up/down button action

      OBJECT PROPERTIES
      • down object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • up object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

  • type stringREQUIRED

    A string that specifies the name of either a predefined or a custom-defined interactive notification type. Predefined types are prefixed with ua_.

    Possible values: ua_yes_no_foreground, ua_yes_no_background, ua_accept_decline_foreground, ua_accept_decline_background, ua_shop_now, ua_buy_now, ua_follow, ua_opt_in, ua_unfollow, ua_opt_out, ua_opt_in_remind, ua_remind_me_later, ua_more_info, ua_download, ua_share, ua_download_share, ua_remind_share, ua_opt_in_share, ua_opt_out_share, ua_follow_share, ua_unfollow_share, ua_shop_now_share, ua_buy_now_share, ua_more_like_less_like, ua_like_dislike, ua_like, ua_like_share, ua_add_calendar_remind, ua_add, ua_save, ua_follow_save, ua_rate, ua_rate_remind, ua_search, ua_book, ua_icons_happy_sad, ua_icons_up_down, <custom_defined_interactive_notification_type>

Landing page content

One of
  • OBJECT PROPERTIES
    • url stringREQUIRED

      The URL to be opened as a landing page. This value supports http or https schemes and can be personalized using handlebars expressions.

  • All of
    • OBJECT PROPERTIES
      • content_encoding string

        A string specifying the encoding of the text in the body attribute. Defaults to utf-8.

        Possible values: utf-8, base64

      • content_type stringREQUIRED

        A non-blank string, which must be a MIME type.

List response object

List response object

{
  "ok": true,
  "lists": [
      {
        "name": "ua_attributes_my_list",
        "description": "My first list",
        "extra": {
            "filename": "list.csv",
            "source": "crm"
        },
        "created": "2020-05-13T21:41:25",
        "last_updated": "2020-05-13T21:45:17",
        "channel_count": 0,
        "error_path": "https://go.urbanairship.com/api/attribute-lists/ua_attributes_my_list/errors",
        "status": "ready"
      },
      {
        "name": "ua_attributes_another_list",
        "description": "My second list",
        "extra": {
            "filename": "list2.csv",
            "source": "api"
        },
        "created": "2020-05-14T21:41:25",
        "last_updated": "2020-05-14T21:45:17",
        "channel_count": 0,
        "error_path": "https://go.urbanairship.com/api/attribute-lists/ua_attributes_another_list/errors",
        "status": "ready"
      }
  ]
}

Contains all user-specified data about a static list or attributes list (metadata), but does not contain CSV list contents. Use the /api/lists/{name}/csv endpoints to upload or download list contents.

OBJECT PROPERTIES
  • channel_count integer

    A count of resolved channel identifiers for the last uploaded and successfully processed identifier list. This will always be 0 for attribute lists.

  • created string

    The date-time when the list was initially created.

  • description string

    An optional description for the list.

  • error_path string

    If non-empty, indicates that there were errors in the processed CSV file. The value is either an empty string or a URL to download a file describing the errors.

  • extra object

    An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.

  • last_updated string

    The date-time when the identifiers of the list were last updated successfully.

  • name stringREQUIRED

    The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.

  • status string

    A string value representing the state of the list.

    • ready — The list was processed successfully and is ready for sending.
    • processing — The list is being processed.
    • failure — There was an error processing the last uploaded list.

    Possible values: ready, processing, failure

Localization object

Example array of localizations

{
  "localizations": [
      {
         "language": "de",
         "country": "AT",
         "notification": {
            "alert": "Grüss Gott"
         }
      },
      {
         "language": "de",
         "country": "DE",
         "notification": {
            "alert": "Guten Tag"
         }
      }
   ]
}

An object used to indicate that message content delivered to a device should be customized for a specific locale subset. Each localization object must have at least one of country and language. Which of those two fields are present does not need to be consistent across localizations.

In addition, each localization object must have one of notification, message, or in_app set. If the top level notification, message, or in_app fields are set, they will be delivered to any user in the audience not matching any of the localizations.

OBJECT PROPERTIES
  • country string

    The ISO 3166-2 two-letter country code for this localization.

  • in_app object<In-app message>

    A JSON object describing an in-app message payload.

  • language string

    The ISO 639-1 two-letter language code for this localization.

  • message object<Message Center object>

    A Message Center message.

  • notification object<Notification object>

    The notification payload that is required unless either message or in_app is present. You can provide an alert and any platform overrides that apply to the device_type platforms you specify.

Message Center object

Message object example

{
   "audience": "all",
   "notification": {
      "ios": {
         "badge": "+1"
      }
   },
   "message": {
      "title": "This week's offer",
      "body": "<html><body><h1>blah blah</h1> etc...</html>",
      "content_type": "text/html",
      "expiry": "2020-04-01T12:00:00",
      "extra": {
         "offer_id": "608f1f6c-8860-c617-a803-b187b491568e"
      },
      "icons": {
         "list_icon": "http://cdn.example.com/message.png"
      }
   }
}

A Message Center message.

OBJECT PROPERTIES
  • body stringREQUIRED

    The body of the message.

  • content_encoding string

    A string denoting encoding type of the data in body. Defaults to utf-8. base64 encoding can be used in cases which would be complex to escape properly, just as HTML containing embedded javascript code, which itself may contain embedded JSON data.

  • content_type string

    A string denoting the MIME type of the data in body. Defaults to text/html.

  • expiry object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • extra object

    A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.

  • icons object

    A JSON dictionary of string key and value pairs representing icons. At this time, only the list_icon key is supported. Values must be URI/URLs to icon resources. For resources hosted by UA, use the following URI format ua:<resource_id>.

    OBJECT PROPERTIES
    • list_icon string
  • title stringREQUIRED

    The title of the message.

Message type

Indicates the purpose of a message.

Named User object

Example Named User

{
  "named_user": {
      "named_user_id": "user-id-1234",
      "created" : "2020-04-08T20:41:06",
      "last_modified" : "2020-05-01T18:00:27",
      "tags": {
        "loyalty program": [
            "silver-member",
            "ten-plus-years",
            "valued-customer"
        ],
        "crm id": [
            "abc-123-def-456"
        ]
      },
      "subscription_lists": [
        {
          "list_ids": ["example_listId-1", "example_listId-5"],
          "scope": "web"
        },
        {
          "list_ids": ["example_listId-2", "example_listId-3"],
          "scope": "app"
        },
        {
          "list_ids": ["example_listId-2"],
          "scope": "web"
        },
        {
          "list_ids": ["example_listId-3"],
          "scope": "email"
        },
        {
          "list_ids": ["example_listId-4"],
          "scope": "sms"
        }
      ],
      "attributes": {
        "item_purchased": "Fur removal tool",
        "cats_name": "Sammy",
        "pets_age": 12
      },
      "user_attributes": {
        "ua_country": "US",
        "ua_language": "en",
        "ua_tz": "America/Los_Angeles"
      },
      "channels": [
        {
            "channel_id": "dceafd02-b852-4305-83df-98b65fa40dd4",
            "device_type": "ios",
            "installed": true,
            "opt_in": true,
            "push_address": "FFFF",
            "created": "2020-04-08T20:41:06",
            "last_registration": "2020-05-01T18:00:27",
            "tags": [
              "meow"
            ]
        }
      ]
  }
}

The response body for a Named User listing, including tags, channels and attributes associated with the Named User.

OBJECT PROPERTIES
  • attributes object<Custom and predefined Attributes>REQUIRED

    Attributes associated with a channel or Named User. This object contains predefined attributes that you enable and assign to the channel, or custom attributes that you create and assign.

    This object enumerates predefined attributes, but you can create your own in the Airship dashboard.

  • channels arrayREQUIRED

    Listing of channels associated with the Named User.

  • created stringREQUIRED

    The creation date-time.

  • last_modified stringREQUIRED

    The last modified date-time.

  • named_user_id stringREQUIRED

    A customer-chosen ID that represents a user, e.g., CRM ID. This ID cannot have leading or trailing whitespace.

  • subscription_lists arrayREQUIRED

    A list of subscription list items associated with the Named User.

  • tags object<Tag Group object>REQUIRED

    One or more tag group objects associated with the Named User. See Named User Tags.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • user_attributes objectREQUIRED

    User attributes consist of three values that are copied from the last channel associated with the Named User.

    OBJECT PROPERTIES
    • ua_country string

      An ISO 3166 two-character country code. Example: “US”.

    • ua_language string

      An ISO 639-1 two-character language code. Example: “en”.

    • ua_local_tz string

      Time zone as a string. Example: “America/Los_Angeles”

Subscription list item object

Example Subscription List item

{
  "list_ids": ["example_listId-2", "example_listId-3"],
  "scope": "app"
}

An item consisting of a list of list IDs and scope.

OBJECT PROPERTIES
  • list_ids arrayREQUIRED

    A list of subscription lists associated to the specified scope. If no scope is specified these subscription lists are not scoped.

  • scope string

    Scope as a string.

    Possible values: app, email, sms, web

Named User Subscription Lists object

Example Subscription Lists object

{
    "subscribe": ["stickers", "gifs"],
    "unsubscribe": ["cookies"]
}

Defines the Subscription List changes.

OBJECT PROPERTIES
  • subscribe array[string]

    Subscribe to the specified Subscription List identifier.

  • unsubscribe array[string]

    Unsubscribe the specified Subscription List identifier.

Named User update payload

At least one of associate, disassociate, tags, or attributes must be provided. If a channel is provided in both associate and disassociate sections, a 400 will be returned.

OBJECT PROPERTIES
  • associate array

    Associate a list of channels or email addresses with the Named User. If the channel_id or email_address is already associated with the Named User, this operation will do nothing.

  • attributes array

    Set or remove attributes on a Named User.

    A single request body may contain set or remove operations, or both. If both set and remove fields are present and the intersection of the attributes in these fields is not empty, then a 400 will be returned.

    If at least one of the attributes included in the request is valid, i.e., at least one attribute exists, Airship returns a 200 with a warning containing a list of attributes that failed to update.

  • disassociate array

    Disassociate a channel or an email address from the Named User.

  • tags object

    Add, remove, or set tags on a Named User. A single request body may contain add and/or remove objects or a single set field. At least one of the add, remove, or set objects must be present in a request.

    A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response.

    If at least one of the tags included in the request is valid, i.e., at least one tags exists, Airship returns a 200 with a warning containing a list of tags that failed to update.

    OBJECT PROPERTIES
    • add object<Tag Group object>

      Add the list of tags to the Named User, but do not remove any. If the tags are already present, they are not modified.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • remove object<Tag Group object>

      Remove the list of tags from the Named User, but do not remove any others. If the tags are not currently present, nothing happens.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • set object<Tag Group object>

      Set these tags for the Named User; any tags previously associated that are not in this current list are removed.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Notification object

Example notification with all platforms

{
   "audience": "all",
   "device_types": [
      "ios",
      "android",
      "amazon",
      "web",
      "email",
      "open::toaster"
   ],
   "notification": {
      "ios": {
         "alert": "Hello, iDevices"
      },
      "android": {
         "alert": "These are not the...yeah, lame joke."
      },
      "amazon": {
         "alert": "Read any good books lately?"
      },
      "web": {
         "alert": "Oh the tangled web we weave"
      },
      "email": {
         "subject": "Did you get that thing I sent you?",
         "html_body": "<h2>Richtext body goes here</h2><p>Wow!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
         "plaintext_body": "Plaintext version goes here [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
         "message_type": "commercial",
         "sender_name": "Airship",
         "sender_address": "team@urbanairship.com",
         "reply_to": "no-reply@urbanairship.com"
      },
      "open::toaster": {
         "alert": "Would you like avocados with that?"
      }
   }
}

The notification payload that is required unless either message or in_app is present. You can provide an alert and any platform overrides that apply to the device_type platforms you specify.

OBJECT PROPERTIES
  • actions object<Actions>

    Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

  • alert string

    A notification message, displayed for any platforms receiving the push without a platform override.

  • amazon object
    One of
    • Amazon Override Object

      The platform override section for Kindle Fire (for Amazon Device Messaging).

    • Amazon Override With Template

      Use a template with a Fire OS-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

  • android object
    One of
  • email object
    One of
    • Email Override Object

      Notification fields specific to email messages. This object is required when email is specified in the payload’s device_types field.

    • Email Override With Template

      Notification fields specific to email messages with an inline template for use in a Create and Send payload. Using a template enables you to provide and populate variables in your notification. You can also add conditional statements based on those variables, determining message text that to send to each member of your audience. Conditionals begin with {{#operator}} and end with {{/operator}}. For more information, see Handlebars.

  • interactive object<Interactive notification object>

    An interactive notification.

    Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

  • ios object
    One of
    • Ios Override Object

      The platform override section for iOS. Maximum 4,096 bytes.

    • Ios Override With Template

      Use a template with iOS-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

  • mms object
    One of
    • Mms Override Object

      Provides the content for a push to MMS channels. If sms is in the device_type array, your request may include this object. It cannot be combined with an SMS Platform Override as a single push can only include either an SMS or MMS payload.

    • Mms Override With Template

      Template and notification overrides for a Create and Send payload with device_types set to mms. With a template, you can provide and populate variables and conditional statements based on those variables. Conditionals begin with {{#operator}} and end with {{/operator}}. For more information, see Handlebars.

  • open::open_platform_name object
    One of
    • Open Channel Override Object

      The platform override section for open platforms uses the prefix attribute open:: before the configured open platform name. The open::<open_platform_name> object will contain an object with the following attributes.

    • Open Channel Override With Template

      Use a template with an open channel-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

  • sms object
    One of
    • Sms Override Object

      Provides override options when sms is one of the device_types specified in the payload.

    • Sms Override With Template

      Notification fields specific to SMS messages with an inline template for use in a Create and Send payload. Using a template enables you to provide and populate variables in your notification. You can also add conditional statements based on those variables, determining message text that to send to each member of your audience. Conditionals begin with {{#operator}} and end with {{/operator}}. For more information, see Handlebars.

  • web object
    One of
    • Web Override Object

      The web platform overrides determine message behaviors for web notifications.

      Safari behaves differently from other browsers and supports only the alert and title overrides. It ignores all other web overrides.

    • Web Override With Template

      Use a template with a Web-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

      Safari behaves differently from other browsers and supports only the alert and title overrides. It ignores all other web overrides.

Open channel options

Contains options that apply when the device_type is set to open.

OBJECT PROPERTIES
  • identifiers object

    A set of up to 100 key:value pairs representing identifiers for this channel in your own delivery systems and delivered as a part of webhook payloads.

  • old_address string

    If a channel exists for the value of old_address, replaces that channel’s address with the value of address. Use infrequently, such as when an end user’s phone number or email address permanently changes.

  • open_platform_name stringREQUIRED

    The name of the open channel that this channel_id is registered on.

Push object

Example push object

{
   "audience": {
      "OR": [
         {
            "tag": [
               "sports",
               "entertainment"
            ]
         },
         {
            "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
         }
      ]
   },
   "notification": {
      "alert": "Hi from Airship!{{#if super_sale }} We're having a sale on {{ products.0.name }}!{{/if}}",
      "ios": {
         "extra": {
            "url": "http://www.urbanairship.com"
         }
      }
   },
   "options": {
      "expiry": "2020-04-01T12:00:00"
   },
   "message": {
      "title": "Message title",
      "body": "<Your message here>",
      "content_type": "text/html"
   },
   "in_app": {
      "alert": "This part appears in-app!",
      "display_type": "banner",
      "expiry": "2020-04-01T12:00:00",
      "display": {
         "position": "top"
      }
   },
   "device_types": [ "ios", "android" ],
   "global_attributes": {
      "super_sale": true,
      "products": [
          {"id": 1, "name": "New Line Sneakers", "price": "79.95"},
          {"id": 2, "name": "Old Line Sneakers", "price": "59.95"}
      ]
   }
}

Example personalized push

{
   "audience": {
      "OR": [
         {
            "tag": [
               "sports",
               "entertainment"
            ]
         },
         {
            "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
         }
      ]
   },
   "notification": {
      "alert": "Hi from Airship!{{#if super_sale }} We're having a sale on {{ products.0.name }}!{{/if}}",
      "ios": {
         "extra": {
            "url": "http://www.urbanairship.com"
         }
      }
   },
   "options": {
      "expiry": "2020-04-01T12:00:00"
   },
   "message": {
      "title": "Message title",
      "body": "<Your message here>",
      "content_type": "text/html"
   },
   "in_app": {
      "alert": "This part appears in-app!",
      "display_type": "banner",
      "expiry": "2020-04-01T12:00:00",
      "display": {
         "position": "top"
      }
   },
   "device_types": [ "ios", "android" ],
   "global_attributes": {
      "super_sale": true,
      "products": [
          {"id": 1, "name": "New Line Sneakers", "price": "79.95"},
          {"id": 2, "name": "Old Line Sneakers", "price": "59.95"}
      ]
   }
}

{
   "device_types": [
      "sms"
   ],
   "options": {
      "personalization": true
   },
   "notification": {
      "sms": {
         "alert": "Hi {{name}}, {{#feed \"weather_updates\" kw="today" as |weather|}}It's going to be {{weather.temp}} in {{weather.loc}} today!{{/feed}}",
      }
   },
   "audience": {
      "tag": "local_updates",
      "group": "weather"
   },
   "feeds": [
      {
         "name": "weather_updates",
         "params": {
            "kw": "today"
         }
      }
   ]
}

Example localized push

{
   "audience": {
      "OR": [
         {
            "tag": [
               "sports",
               "entertainment"
            ]
         },
         {
            "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
         }
      ]
   },
   "notification": {
      "alert": "Hi from Airship!{{#if super_sale }} We're having a sale on {{ products.0.name }}!{{/if}}",
      "ios": {
         "extra": {
            "url": "http://www.urbanairship.com"
         }
      }
   },
   "options": {
      "expiry": "2020-04-01T12:00:00"
   },
   "message": {
      "title": "Message title",
      "body": "<Your message here>",
      "content_type": "text/html"
   },
   "in_app": {
      "alert": "This part appears in-app!",
      "display_type": "banner",
      "expiry": "2020-04-01T12:00:00",
      "display": {
         "position": "top"
      }
   },
   "device_types": [ "ios", "android" ],
   "global_attributes": {
      "super_sale": true,
      "products": [
          {"id": 1, "name": "New Line Sneakers", "price": "79.95"},
          {"id": 2, "name": "Old Line Sneakers", "price": "59.95"}
      ]
   }
}

{
   "device_types": [
      "sms"
   ],
   "options": {
      "personalization": true
   },
   "notification": {
      "sms": {
         "alert": "Hi {{name}}, {{#feed \"weather_updates\" kw="today" as |weather|}}It's going to be {{weather.temp}} in {{weather.loc}} today!{{/feed}}",
      }
   },
   "audience": {
      "tag": "local_updates",
      "group": "weather"
   },
   "feeds": [
      {
         "name": "weather_updates",
         "params": {
            "kw": "today"
         }
      }
   ]
}

{
  "device_types": [ "ios", "android" ],
  "audience": {
     "tag": "needs_a_greeting",
     "group": "new_customer"
  },
  "notification": {
     "alert": "Hi!"
  },
  "localizations": [
      {
         "language": "de",
         "country": "AT",
         "notification": {
            "alert": "Grüss Gott"
         }
      },
      {
         "language": "de",
         "country": "DE",
         "notification": {
            "alert": "Guten Tag"
         }
      }
  ]
}

A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

OBJECT PROPERTIES
  • audience object<Audience selector (max 1000)>REQUIRED

    An audience selector forms the expression that determines the set of channels to target.

  • campaigns object<Campaigns object>

    An object specifying custom campaign categories related to the notification.

  • device_types array[string]REQUIRED

    An array containing one or more strings identifying targeted platforms.

  • feed_references object<Feed references object>

    An object used to indicate that an external data feed should be invoked, the name of the feed to invoke, and the way in which to invoke it. You can only include a feed if you include a templates object in the payload or set the personalization option to true.

  • global_attributes object

    The global attributes object may contain an arbitrary set of keys and values, including arrays and nested objects, which will be added to the global attributes rendering namespace for this push. Top-level keys must start with a letter and cannot start with the reserved sequence ua_. If the global attributes object is nonempty, it implies the personalization: true option.

  • in_app object<In-app message>

    A JSON object describing an in-app message payload.

  • localizations array

    An array of localizations. Channels bearing the specified language/country combination will receive the corresponding message.

  • message object
    One of
  • message_type object<Message type>

    Indicates the purpose of a message.

  • notification object<Notification object>

    The notification payload that is required unless either message or in_app is present. You can provide an alert and any platform overrides that apply to the device_type platforms you specify.

  • options object<Push options>

    A JSON dictionary for specifying non-payload options related to the delivery of the push.

  • orchestration object

    An object used to indicate the strategy to employ when deciding which channels to target for a contact. An orchestration object can be stored in Airship as the default strategy. If the orchestration section is included in a push payload, it will override the configured default value. The overall default strategy is fan_out.

    OBJECT PROPERTIES
    • channel_priority array[string]

      An array of channel types in priority order. Required if type is set to channel_priority.

    • type stringREQUIRED

      The name of the orchestration strategy to employ.

      Possible values: channel_priority, fan_out, triggering_channel, last_active

  • snippet_references object<Snippet references object>

    An object used to indicate that a set of snippets should be loaded for use in message content. Use the following syntax in your payload: {{> your_snippet_name }} to reference the snippet content within a notification or rich message.

    See Snippets to see how to create a snippet in the Airship dashboard.

Push options

A JSON dictionary for specifying non-payload options related to the delivery of the push.

OBJECT PROPERTIES
  • audience_limits object<Audience limits object>

    Defines limits to be applied to Push Notifications and standard in-app messages (not In-App Automations or Scenes) only. See Audience Limit in the Message delivery user guide for additional information and limitations.

  • ban_list_parameters object<Ban List parameters>

    A list of parameters, where the key and value are both strings, that will be used to override the default values set for variables in a Ban List request URL.

  • bypass_ban_list_processing boolean

    If true, a user’s status on a Ban List will not be verified before sending the push.

  • bypass_frequency_limits boolean

    If true, the push ignores any Message Limits that would otherwise apply to your message.

  • bypass_holdout_groups boolean

    If true, the push ignores withholding any messages for users in a holdout group for a Holdout Experiment that is active at send time.

  • expiry object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • no_throttle boolean

    If true, the push will ignore global throttling rates that have been configured for the application, resulting in delivery as quickly as possible.

  • omit_from_activity_log boolean

    If true, the push is omitted from the Activity Log.

  • personalization boolean

    If true, enables Handlebars-style template syntax for eligible fields in a notification or message center objects. You can do this to enable handlebars for all available fields without using individual template objects for different platform overrides.

    This setting is implicitly true whenever your payload includes a platform override with a template object.

  • redact_payload boolean

    If true, the push payload will not appear in Airship’s logs. You cannot use this option with Message Center, A/B Tests, Automation, or Scheduled pushes, which all require the payload to be stored separately by design.

  • use_strict_sms_validation boolean

    This field is only compatible for Create and Send requests targeting SMS and MMS device_types.

    If true, Create and Send requests containing any selector entries that would result in silent row drops will return a 400 Bad Request response code. Detailed error messages will be returned for all invalid rows.

    If false, requests that contain row entries with silent errors as documented for the targeted required selector fields will return a 200 status code. However, all invalid entries will be silently dropped during request processing.

    By default, this attribute is implicitly set to false unless every entry in the request would be dropped silently as determined by the targeted selector type, at least one malformed JSON error is found in the request, or at least one validation error is encountered for a required selector field that is not documented to handle invalid data with silent drops.

Schedule object

Example schedule

{
    "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109",
    "schedule": {"scheduled_time": "2020-04-01T18:45:30"},
    "name": "My schedule",
    "push": {
        "audience": {"tag": "49ers"},
        "device_types": [ "ios", "android" ],
        "notification": {"alert": "Touchdown!"},
        "options": {"expiry": 10800}
    }
}

A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.

OBJECT PROPERTIES
  • localization_ids array[string]

    An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).

  • name string

    An optional string.

  • push object<Push object>REQUIRED

    A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

  • push_ids array[string]

    An array of the push IDs associated with the schedule. The push_ids key is set by the server, and so is present in responses but not in creation requests sent from the client. Requests that contain this key will return a HTTP 400 Bad Request.

  • schedule objectREQUIRED
    Any of
    • Schedule Spec

      The delivery time specified in UTC.

    • Recurring schedule object

      Recurring schedules allow you to send a message multiple times at a set cadence. This is useful for subscription reminders, birthdays, etc. This is accomplished by adding recurring data to the schedule endpoint.

      OBJECT PROPERTIES
      • recurring object
        OBJECT PROPERTIES
        • cadence objectREQUIRED

          Defines how often the message is to be sent. It consists of the type (unit) and an optional value (count).

          One of
          • Standard Cadence object
            OBJECT PROPERTIES
            • count integerREQUIRED

              The frequency of messaging corresponding to the type. For example, a count of 2 results in a message every 2 hours, days, weeks, months, etc. based on the type value.

            • type stringREQUIRED

              The unit of measurement for the cadence.

              Possible values: hourly, daily, monthly, yearly

          • Weekly Cadence object
            OBJECT PROPERTIES
            • count integerREQUIRED

              The frequency of messaging on the weekly cadence. For example, a count of 2 results in a message every 2 weeks.

            • days_of_week string

              The days of the week on which Airship can send your message.

              Possible values: monday, tuesday, wednesday, thursday, friday, saturday, sunday

            • type stringREQUIRED

              Possible values: weekly

        • end_time string

          The date-time when the schedule will end and stop sending messages.

        • exclusions array

          The date-time ranges when messages are not sent.

        • paused boolean

          If true, the schedule is paused, and will not result in sends at the regularly scheduled cadence.

  • url string

    The url key is set by the server, and so is present in responses but not in creation requests sent from the client.

Schedule specification

Global schedule

{
   "scheduled_time": "2020-04-01T18:45:30"
}

Best time example

{
   "scheduled_time": "2020-04-01T18:45:30"
}

{
  "best_time": {
    "send_date": "2020-06-01"
  }
}

Local time

{
   "scheduled_time": "2020-04-01T18:45:30"
}

{
  "best_time": {
    "send_date": "2020-06-01"
  }
}

{
   "local_scheduled_time": "2020-04-01T18:45:30"
}

The delivery time specified in UTC.

One of
  • Scheduled time object

    Scheduled push to be delivered globally at the same moment.

    OBJECT PROPERTIES
  • Local scheduled time object

    Deliver a message at each device’s local time. This ensures that users receive your message at the same time of day across all time zones in your app’s audience. This feature only works for channels that have a timezone tag (or Named Users containing at least one channel with a timezone tag). Devices in the audience that do not have a timezone tag will not receive your message.

    OBJECT PROPERTIES
    • local_scheduled_time string

      Alternative to scheduled_time. The scheduled device local date-time to send the notification.

  • Best time object

    Alternative to scheduled_time. Uses predictive analytics to send the notification at the optimal send time for each member of your audience.

    When your audience includes users without an optimal send time tag, those users will be dropped from delivery and will not receive the message. Since optimal send time is determined from user behavior over time, new users might not have an optimal send time determined for the first week or two after channel registration.

    OBJECT PROPERTIES
    • best_time object

      Schedules the notification for the optimal send time.

      OBJECT PROPERTIES
      • send_date string

        The date set by the user for when the push should go out, localized to the time zone for a given channel. Best-time pushes require activation of our predictive analytics toolset.

Scheduled bulk send object

Scheduled bulk send object

{
    "schedule": {
        "scheduled_time" : "2024-11-07T12:00:00"
    },
    "name" : "scheduled bulk send",
    "push" : {
        "audience" : {
            "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
        },
        "device_types" : [ "open::rcs" ],
        "notification" : {
            "alert" : "Hope you voted"
        },
        "campaigns": {
            "categories": ["midterms2024", "getoutthevote2024"]
        }
    }
}

A scheduled bulk send object wraps a bulk send object. It describes when the notification should be sent, an optional name for the notification, and the object defining the notification itself, which must be a bulk send object or Templated message content. The scheduled date must be within 60 days.

OBJECT PROPERTIES
  • name string

    A name for the scheduled push message.

  • push objectREQUIRED
    One of
    • Bulk Send Object

      A bulk send object describes everything about a Send message with bulk ID or Schedule message with bulk ID notification. The acceptable fields are identical to a standard push with two exceptions. The audience field can only be a single bulk_id and there can only be one device_type.

    • Templated Message Content

      Customers may use a template to specify message content instead of using static specification. The request format is consistent with Template Schemes. See description Platform Override Templates. All columns (for CSV) or keys (for JSON) not prefixed with ua_ are considered merge fields. Prefixed columns/keys are not usable in template evaluation. If the value of a delivery variable is also needed in the template, the requester should duplicate it into an unprefixed column.

      No verification is done in this API that the provided set of merge values matches the fields of the template. Customers using the UI will pass through a step where they’ll be alerted that some template field has no matching column in the uploaded CSV. Custom Create and Send fields are not limited to strings and can contain numbers, booleans, arrays, hierarchical JSON, etc.

      Merge fields are allowed to use nested property names in CSV upload headers by using a subset of legal Handlebars template expression syntax.

  • schedule objectREQUIRED

    As defined by the Schedule object, but only the scheduled_time key is valid.

    OBJECT PROPERTIES
    • scheduled_time stringREQUIRED

      The date-time when you want to perform your Create and Send operation. Users will receive the notification as soon as possible after the specified date-time.

Named User scoped batch item

Example scoped batch item

{
    "scope": ["app"],
    "subscription_lists": {
        "subscribe": ["stickers", "gifs"],
        "unsubscribe": ["cookies"]
    }
}

Contains scope and subscription_lists.

OBJECT PROPERTIES

Scopes

The channel types where membership applies. The app scope includes iOS, Android, and Amazon channels.

Sender ID

A sender_id describes the sender target to apply the keyword action event to. This must be a number the app is already configured to send from. If a sender exists in multiple countries, a country can be specified by prefixing the country code with a colon, e.g., US:12345.

The sender_id is composed of two parts:

  • A sender stem - Required numeric string.
  • A country_code - Optional 2-letter ISO 3166 country code.

SMS channel associated by contact

Example

{
  "type": "sms",
  "channel_id": "a537ac78-ef4f-4f74-8536-6fd620549186",
  "sender": "1234",
  "msisdn": "*******3379",
  "opt_in": true
}

An SMS channel associated with a contact.

OBJECT PROPERTIES
  • channel_id string

    The unique identifier.

  • msisdn string

    The phone number corresponding to the channel.

  • opt_in boolean

    If true, the channel is opted in to push notifications. If false, it is not.

  • sender string

    The sender corresponding to the channel.

  • type string

    The channel type.

    Possible values: sms

Snippet references object

Example push snippets request

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

 {
    "device_types": ["ios"],
    "audience": { "tag": "earlyBirds" },
    "notification": {
       "alert": "Hello, {{user}}, how are you today?{{> \"signoff\" }}"
    },
    "options": {
       "personalization": true
    },
    "snippet_references": {
       "snippets": [
          {
             "name": "signoff"
          }
       ]
    }
 }

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3
Content-Length: 123
Data-Attribute: push_ids

 {
    "ok": true,
    "operation_id": "5e7852b0-6909-4e60-a73f-4d6b92d94c80",
    "push_ids": [
       "bf28d158-fefe-475a-9c2a-ed4f69cc891e"
    ]
 }

Snippet references example: The `copyright` snippet is loaded by the `snippet_references` object and inserted at the end of the `alert` text.

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

 {
    "device_types": ["ios"],
    "audience": { "tag": "earlyBirds" },
    "notification": {
       "alert": "Hello, {{user}}, how are you today?{{> \"signoff\" }}"
    },
    "options": {
       "personalization": true
    },
    "snippet_references": {
       "snippets": [
          {
             "name": "signoff"
          }
       ]
    }
 }

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3
Content-Length: 123
Data-Attribute: push_ids

 {
    "ok": true,
    "operation_id": "5e7852b0-6909-4e60-a73f-4d6b92d94c80",
    "push_ids": [
       "bf28d158-fefe-475a-9c2a-ed4f69cc891e"
    ]
 }

{
   "notification": {
      "alert": "Hi {{ name }}: Thanks for your purchase! {{> copyright }}"
   },
   "snippet_references": {
      "snippets": [
         {
            "name": "copyright"
         }
      ]
   }
}

An object used to indicate that a set of snippets should be loaded for use in message content. Use the following syntax in your payload: {{> your_snippet_name }} to reference the snippet content within a notification or rich message.

See Snippets to see how to create a snippet in the Airship dashboard.

OBJECT PROPERTIES
  • snippets array[object]REQUIRED

    An array of snippets that you want to use to personalize your message.

List ID

A list ID that contains only alphanumeric characters, underscores, or hyphens.

Subscription List action

A string representing the membership mutation action to be taken for a given list.

Subscription List object

Example Subscription List object

{
  "action": "subscribe",
  "list_id": "exciting_news"
}
OBJECT PROPERTIES
  • action objectREQUIRED
    One of
    • Channel Subscription List action object

      Alters Subscription List membership for a channel.

      OBJECT PROPERTIES
      • action object<Subscription List action>REQUIRED

        A string representing the membership mutation action to be taken for a given list.

      • list_id object<List ID>REQUIRED

        A list ID that contains only alphanumeric characters, underscores, or hyphens.

      • type stringREQUIRED

        Possible values: channel

    • Contact subscription list action object

      Alters subscription list membership for a contact.

      OBJECT PROPERTIES
      • action object<Subscription List action>REQUIRED

        A string representing the membership mutation action to be taken for a given list.

      • list_id object<List ID>REQUIRED

        A list ID that contains only alphanumeric characters, underscores, or hyphens.

      • scope object<Scopes>REQUIRED

        The channel types where membership applies. The app scope includes iOS, Android, and Amazon channels.

      • type stringREQUIRED

        Possible values: contact

  • list_id object<List ID>REQUIRED

    A list ID that contains only alphanumeric characters, underscores, or hyphens.

  • timestamp string

    The date-time when the attribute changed. Server time is used when not present.

Subscription list result object

Example Subscription List result object

{
   "list_id": "example_listId-2",
   "name": "A nice readable name 2",
   "description": "A very nice description for you.",
   "scopes": ["app", "web"],
   "default_opted_in": true
}

Defines the subscription list result object.

OBJECT PROPERTIES
  • default_opted_in booleanREQUIRED

    True if the audience defined by scopes are opted in by default, otherwise false.

  • description object

    Description of the subscription list.

  • list_id object<List ID>REQUIRED

    A list ID that contains only alphanumeric characters, underscores, or hyphens.

  • message_type string

    The message type.

    Possible values: transactional, commercial

  • name string

    Human readable name.

  • scopes arrayREQUIRED

    An array of scopes applicable to the subscription list. Valid scopes are app, web, email, and sms.

Tag Group object

A simple tag group that has 2 tags associated with the group tags.

{
  "sports fan": ["Federer fan", "Messi fan"]
}

A simple Airship-specific tag group, associating one tag with the group

{
  "sports fan": ["Federer fan", "Messi fan"]
}

{
  "tag_groups": {
      "ua_locale_country": ["US"]
  }
}

An array of Tag Groups for a channel. Channels can have Airship-specific tag groups; Named Users do not have Airship-specific Tag Groups.

{
  "sports fan": ["Federer fan", "Messi fan"]
}

{
  "tag_groups": {
      "ua_locale_country": ["US"]
  }
}

{
  "tag_groups": [
      {
        "sports fan": [
            "Federer fan",
            "Messi fan"
        ]
      },
      {
        "music fan": [
            "Beyonce",
            "Muse"
        ]
      },
      {
        "ua_locale_country": [
            "US"
        ]
      },
      {
        "ua_locale_language": [
            "en"
        ]
      }
  ]
}

An array of Tag Groups for a Named User. Named Users do not have Airship-specific tag groups.

{
  "sports fan": ["Federer fan", "Messi fan"]
}

{
  "tag_groups": {
      "ua_locale_country": ["US"]
  }
}

{
  "tag_groups": [
      {
        "sports fan": [
            "Federer fan",
            "Messi fan"
        ]
      },
      {
        "music fan": [
            "Beyonce",
            "Muse"
        ]
      },
      {
        "ua_locale_country": [
            "US"
        ]
      },
      {
        "ua_locale_language": [
            "en"
        ]
      }
  ]
}

{
  "tags": {
      "crm_id": [
        "abc-123-def-456"
      ],
      "loyalty program": [
        "silver-member",
        "ten-plus-years",
        "valued-customer"
      ]
  }
}

Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

OBJECT PROPERTIES
  • * array[string]

    An array of tags.

Tag list metadata object

Contains all user-specified data when defining a tag list in Airship. Although add, remove, and set are optional, one or more must be present.

OBJECT PROPERTIES
  • add object<Tag Group object>

    Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • description string

    An optional description for the list.

  • extra object

    An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.

  • name stringREQUIRED

    The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.

  • remove object<Tag Group object>

    Removes the specified tags from the channel.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • set object<Tag Group object>

    Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Tag list response object

Tag list response object

{
  "name" : "ua_tags_foo",
  "description" : "",
  "extra" : { "key": "value" },
  "add":{
    "tag-group-name": [
      "tag-value"
    ],
    "tag-group-name2": [
      "tag-value2a",
      "tag-value2b"
    ]
  },
  "remove": {
    "tag-group-name3": [
      "tag-value"
    ]
  },
  "set": {
    "tag-group-name4": [
      "tag-value"
    ]
  },
  "created" : "2013-08-08T20:41:06",
  "last_updated" : "2014-05-01T18:00:27",
  "channel_count" : 0,
  "mutation_success_count": 1000,
  "mutation_error_count": 10,
  "error_path":  "https://go.urbanairship.com/api/tag-lists/users_a/errors",
  "status" : "ready"
}

Contains information (metadata) about the tag list.

OBJECT PROPERTIES
  • add object<Tag Group object>

    Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • channel_count integer

    A count of resolved channel identifiers for the last uploaded and successfully processed identifier list. This will always be 0 for attribute lists.

  • created string

    The date-time when the list was initially created.

  • description string

    An optional description for the list.

  • error_path string

    If non-empty, indicates that there were errors in the processed CSV file. The value is either an empty string or a URL to download a file describing the errors.

  • extra object

    An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.

  • last_updated string

    The date-time when the identifiers of the list were last updated successfully.

  • name stringREQUIRED

    The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.

  • remove object<Tag Group object>

    Removes the specified tags from the channel.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • set object<Tag Group object>

    Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • status string

    A string value representing the state of the list.

    • ready — The list was processed successfully and is ready for sending.
    • processing — The list is being processed.
    • failure — There was an error processing the last uploaded list.

    Possible values: ready, processing, failure

Templated message content

Example templated Send a message with bulk ID

{
  "audience" : {
      "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
  },
  "device_types" : [ "open::rcs" ],
  "notification" : {
      "open::rcs" : {
          "template": {
              "template_id" : "09641749-f288-46e6-8dc6-fae592e8c092"
          }
      }
  }
}

Example templated Create and Send a message

{
  "audience" : {
      "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
  },
  "device_types" : [ "open::rcs" ],
  "notification" : {
      "open::rcs" : {
          "template": {
              "template_id" : "09641749-f288-46e6-8dc6-fae592e8c092"
          }
      }
  }
}

{
  "audience": {
    "create_and_send": [
      {
        "ua_address": "some-person@example.com",
        "ua_commercial_opted_in": "2023-04-01T18:45:30",
        "ua_open_tracking_opted_in": "2023-04-01T18:45:30",
        "name": "Some Person, Esq.",
        "totalPurchases": "$ 239.85",
        "items": [
          {
            "text": "New Line Sneakers",
            "image": "https://marketing-image-production.example.com/uploads/newlinesneakers.png",
            "price": "$ 79.95"
          },
          {
            "text": "Old Line Sneakers",
            "image": "https://marketing-image-production.example.com/uploads/oldlinesneakers.png",
            "price": "$ 79.95"
          },
          {
            "text": "Blue Line Sneakers",
            "image": "https://marketing-image-production.example.com/uploads/bluelinesneakers.png",
            "price": "$ 79.95"
          }
        ],
        "receipt": true,
        "onlineAccount": {
          "username": "coolUser",
          "email_receipt": true,
          "email": "someone@example.com"
        },
        "userAddress": {
          "address01": "1234 Fake St.",
          "address02": "Apt. 123",
          "city": "Place",
          "state": "CO",
          "zip": "80202"
        },
        "num_of_purchases": 4
      },
      {
        "ua_address": "some-other-person@example.com",
        "ua_commercial_opted_in": "2023-04-01T18:45:30",
        "ua_click_tracking_opted_in": "2023-04-01T18:45:30",
        "name": "The Honorable Some Other Person"
      }
    ]
  },
  "device_types": [
    "email"
  ],
  "notification": {
    "email": {
      "template": {
        "fields": {
          "subject": "Hi there, {{name}}",
          "plaintext_body": "Your \n{{#each items}} {{this.text}} {{this.price}} {{/each}}\n are on the way{{#with userAddress}} to {{address01}}{{/with}}!"
        }
      },
      "sender_name": "Ultimate Sender",
      "message_type": "transactional",
      "sender_address": "no-reply@valid-sender-example.com",
      "reply_to": "no-reply@valid-sender-example.com"
    }
  }
}

Example CSV audience with nested keys

{
  "audience" : {
      "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
  },
  "device_types" : [ "open::rcs" ],
  "notification" : {
      "open::rcs" : {
          "template": {
              "template_id" : "09641749-f288-46e6-8dc6-fae592e8c092"
          }
      }
  }
}

{
  "audience": {
    "create_and_send": [
      {
        "ua_address": "some-person@example.com",
        "ua_commercial_opted_in": "2023-04-01T18:45:30",
        "ua_open_tracking_opted_in": "2023-04-01T18:45:30",
        "name": "Some Person, Esq.",
        "totalPurchases": "$ 239.85",
        "items": [
          {
            "text": "New Line Sneakers",
            "image": "https://marketing-image-production.example.com/uploads/newlinesneakers.png",
            "price": "$ 79.95"
          },
          {
            "text": "Old Line Sneakers",
            "image": "https://marketing-image-production.example.com/uploads/oldlinesneakers.png",
            "price": "$ 79.95"
          },
          {
            "text": "Blue Line Sneakers",
            "image": "https://marketing-image-production.example.com/uploads/bluelinesneakers.png",
            "price": "$ 79.95"
          }
        ],
        "receipt": true,
        "onlineAccount": {
          "username": "coolUser",
          "email_receipt": true,
          "email": "someone@example.com"
        },
        "userAddress": {
          "address01": "1234 Fake St.",
          "address02": "Apt. 123",
          "city": "Place",
          "state": "CO",
          "zip": "80202"
        },
        "num_of_purchases": 4
      },
      {
        "ua_address": "some-other-person@example.com",
        "ua_commercial_opted_in": "2023-04-01T18:45:30",
        "ua_click_tracking_opted_in": "2023-04-01T18:45:30",
        "name": "The Honorable Some Other Person"
      }
    ]
  },
  "device_types": [
    "email"
  ],
  "notification": {
    "email": {
      "template": {
        "fields": {
          "subject": "Hi there, {{name}}",
          "plaintext_body": "Your \n{{#each items}} {{this.text}} {{this.price}} {{/each}}\n are on the way{{#with userAddress}} to {{address01}}{{/with}}!"
        }
      },
      "sender_name": "Ultimate Sender",
      "message_type": "transactional",
      "sender_address": "no-reply@valid-sender-example.com",
      "reply_to": "no-reply@valid-sender-example.com"
    }
  }
}

ua_address,ua_commercial_opted_in,name,address.city,address.state,items.[0].name,items.[0].code,items.[1].name,items.[1].code
someone@example.com,2023-04-01T18:45:30,Joe Someone,Portland,OR,Rubber Gloves,abaccgdsagsde,Bleach Alternative,cacadgdesgaga
else@example.com,2023-04-21T16:13:01,Sir Else,Seattle,WA,Flashlight,zxcvxcbzxcbza,Shovel,aldfkghalsdkg

Equivalent JSON audience definition

{
  "audience" : {
      "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
  },
  "device_types" : [ "open::rcs" ],
  "notification" : {
      "open::rcs" : {
          "template": {
              "template_id" : "09641749-f288-46e6-8dc6-fae592e8c092"
          }
      }
  }
}

{
  "audience": {
    "create_and_send": [
      {
        "ua_address": "some-person@example.com",
        "ua_commercial_opted_in": "2023-04-01T18:45:30",
        "ua_open_tracking_opted_in": "2023-04-01T18:45:30",
        "name": "Some Person, Esq.",
        "totalPurchases": "$ 239.85",
        "items": [
          {
            "text": "New Line Sneakers",
            "image": "https://marketing-image-production.example.com/uploads/newlinesneakers.png",
            "price": "$ 79.95"
          },
          {
            "text": "Old Line Sneakers",
            "image": "https://marketing-image-production.example.com/uploads/oldlinesneakers.png",
            "price": "$ 79.95"
          },
          {
            "text": "Blue Line Sneakers",
            "image": "https://marketing-image-production.example.com/uploads/bluelinesneakers.png",
            "price": "$ 79.95"
          }
        ],
        "receipt": true,
        "onlineAccount": {
          "username": "coolUser",
          "email_receipt": true,
          "email": "someone@example.com"
        },
        "userAddress": {
          "address01": "1234 Fake St.",
          "address02": "Apt. 123",
          "city": "Place",
          "state": "CO",
          "zip": "80202"
        },
        "num_of_purchases": 4
      },
      {
        "ua_address": "some-other-person@example.com",
        "ua_commercial_opted_in": "2023-04-01T18:45:30",
        "ua_click_tracking_opted_in": "2023-04-01T18:45:30",
        "name": "The Honorable Some Other Person"
      }
    ]
  },
  "device_types": [
    "email"
  ],
  "notification": {
    "email": {
      "template": {
        "fields": {
          "subject": "Hi there, {{name}}",
          "plaintext_body": "Your \n{{#each items}} {{this.text}} {{this.price}} {{/each}}\n are on the way{{#with userAddress}} to {{address01}}{{/with}}!"
        }
      },
      "sender_name": "Ultimate Sender",
      "message_type": "transactional",
      "sender_address": "no-reply@valid-sender-example.com",
      "reply_to": "no-reply@valid-sender-example.com"
    }
  }
}

ua_address,ua_commercial_opted_in,name,address.city,address.state,items.[0].name,items.[0].code,items.[1].name,items.[1].code
someone@example.com,2023-04-01T18:45:30,Joe Someone,Portland,OR,Rubber Gloves,abaccgdsagsde,Bleach Alternative,cacadgdesgaga
else@example.com,2023-04-21T16:13:01,Sir Else,Seattle,WA,Flashlight,zxcvxcbzxcbza,Shovel,aldfkghalsdkg

{
  "audience": {
    "create_and_send" : [
        {
          "ua_address" : "someone@example.com",
          "ua_commercial_opted_in" : "2023-04-01T18:45:30",
          "name" : "Joe Someone",
          "address" : {
            "city" : "Portland",
            "state" : "OR"
          },
          "items" : [
            {
              "name" : "Rubber Gloves",
              "code" : "abaccgdsagsde"
            },
            {
              "name" : "Bleach Alternative",
              "code" : "cacadgdesgaga"
            }
          ]
        },
        {
          "ua_address" : "else@example.com",
          "ua_commercial_opted_in" : "2023-04-21T16:13:01",
          "name" : "Sir Else",
          "address" : {
            "city" : "Seattle",
            "state" : "WA"
          },
          "items" : [
            {
              "name" : "Flashlight",
              "code" : "zxcvxcbzxcbza"
            },
            {
              "name" : "Shovel",
              "code" : "aldfkghalsdkg"
            }
          ]
        }
    ]
  }
}

Customers may use a template to specify message content instead of using static specification. The request format is consistent with Template Schemes. See description Platform Override Templates. All columns (for CSV) or keys (for JSON) not prefixed with ua_ are considered merge fields. Prefixed columns/keys are not usable in template evaluation. If the value of a delivery variable is also needed in the template, the requester should duplicate it into an unprefixed column.

No verification is done in this API that the provided set of merge values matches the fields of the template. Customers using the UI will pass through a step where they’ll be alerted that some template field has no matching column in the uploaded CSV. Custom Create and Send fields are not limited to strings and can contain numbers, booleans, arrays, hierarchical JSON, etc.

Merge fields are allowed to use nested property names in CSV upload headers by using a subset of legal Handlebars template expression syntax.

OBJECT PROPERTIES
  • template object
    One of
    • Email

      The payload for a Create and Send operation to email channels. When sending to email channels, device_types must be set to email.

    • Sms

      The payload for a Create and Send operation to SMS channels. When sending to SMS channels, device_types must be set to sms.

    • Mms

      The payload for a Create and Send operation that sends a multimedia payload (MMS) to SMS channels. When sending an MMS payload, device_types must be set to mms.

    • Open

      The payload for a Create and Send operation to open channels. When sending to open channels, the device_type must be set to open::<open_channel_name>.