Push

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

Delete message from inbox

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.

Jump to examples ↓

DELETE /api/user/messages/{push_id}

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:

basicAuth

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.

Examples

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 multiple messages from inbox

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.

Jump to examples ↓

POST /api/user/messages/batch-delete

Security:

basicAuth

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.

Examples

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);

Send a push

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

Jump to examples ↓

POST /api/push

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.

Examples

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": []
}

Validate a push

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.

Jump to examples ↓

POST /api/push/validate

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.

Examples

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()