1. Home
  2. Developer
  3. REST APIs
  4. Airship
  5. Operations
  6. Push

Push

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

View as Markdown

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 Message Center message that was part of an automated or local time delivery, you can provide a group ID to the batch-delete endpoint.

Jump to examples ↓

DELETE /api/user/messages/{push_id}

Note

For time-sensitive messages, set an expiry on the In-app message object so you don’t have to delete them manually.

Security:

Path parameters:

  • push_id stringREQUIRED
    The push_id or message_id of the Message Center 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

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

Deletes multiple Message Center messages completely, removing them from every user’s inbox. You can provide up to 50 IDs in a request. This is an asynchronous call. A success response means that the deletion has been queued for processing.

When providing a group ID, only messages delivered by the time this request is made will be deleted. Messages that are delivered after this request, such as by an ongoing automation, will continue to be available.

Jump to examples ↓

POST /api/user/messages/batch-delete

Security:

Request body:

An array of message IDs or group IDs to delete. Provide either message_ids or group_ids, but not both.

  • Content-Type: application/json

    One of
    • Delete by message IDs object
      OBJECT PROPERTIES
      • message_ids array[string]REQUIRED

        Array of message_id or push_id values.

        Min items: 1, Max items: 50

    • Delete by group IDs object
      OBJECT PROPERTIES
      • group_ids array[string]REQUIRED

        Array of group_id values.

        Min items: 1, Max items: 50

Responses

  • 202

    The deletion request has been accepted for processing.

    Response body:

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

        Message IDs queued for deletion. Populated when the request uses message_ids. Always an empty array when the request uses group_ids.

      • errors array[object]REQUIRED

        Errors for individual message IDs in the request. An empty array when all IDs were accepted. Always an empty array when the request uses group_ids.

  • 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

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

Example delete by group IDs

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

{
    "group_ids": [
        "79a122fc-48e2-4369-843f-a0973fd52d78"
    ]
}

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

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

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.

        Max items: 100

      • 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.

        Format: uuid

        Example: ef625038-70a3-41f1-826f-57bc11dd625a

      • push_ids array[string]

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

        Min items: 1, Max items: 100

        Example: [00256e0b-b02f-4f12-a77f-4c3d57078330 f59970d3-3d42-4584-907e-f5c57f5d46a1]

  • 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

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

{
   "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": {
        "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

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