--- schema_version: "1" id: 0488e47c578ab83e909ea43d1543f58a7a199dccf305b308764964b911376e27 title: Push collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/references/generated-api-specs/mc_rest_push.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_push source_site: developer.salesforce.com content_type: documentation content_hash: 700767f716d679684f7ce19f3c4fb7b94630ad9dc2105a9e2881742cba6a04b5 products: - Marketing Cloud Engagement APIs and Programmatic Languages - Marketing Cloud --- Push # Push Use the push endpoints to programmatically manage push notification send definitions and send push notifications. This table lists the use cases that the Transactional Push API supports. | Supported Use Case | HTTP Verb | URI | | --- | --- | --- | | [Get push messages](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Get%2BPush%2BMessages) | GET | /push/v1/messages | | [Create push message](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Create%2Ba%2BPush%2BMessage) | POST | /push/v1/message | | [Get push message by ID](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Get%2Ba%2BPush%2BMessage%2Bby%2BID) | GET | /push/v1/message/{messageId} | | [Update a push message](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Update%2Ba%2BPush%2BMessage) | PUT | /push/v1/message/{messageId} | | [Delete a push message](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Delete%2Ba%2BPush%2BMessage) | DELETE | /push/v1/message/{messageId} | | [Get locations](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Get%2BLocations) | GET | /push/v1/location | | [Create a location](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Create%2Ba%2BLocation) | POST | /push/v1/location | | [Get a location](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Get%2Ba%2BLocation) | GET | /push/v1/location/{locationId} | | [Update a location](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Update%2Ba%2BLocation) | PUT | /push/v1/location/{locationId} | | [Delete a location](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Delete%2Ba%2BLocation) | DELETE | /push/v1/location/{locationId} | | [Get apps](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Get%2BApps) | GET | /push/v1/application | | [Get an app by ID](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Get%2Ban%2BApp%2Bby%2BID) | GET | /push/v1/application/{appId} | | [Get app keys](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Get%2BApp%2BKeys) | GET | /push/v1/application/{appId}/key | | [Update app keys](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Update%2BApp%2BKeys) | PUT | /push/v1/application/{appId}/key | | [Delete all app keys](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Delete%2BApp%2BKeys) | DELETE | /push/v1/application/{appId}/key | | [Delete an app key](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Delete%2Ban%2BApp%2BKey) | DELETE | /push/v1/application/{appId}/key/{key} | | [Refresh a list](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Refresh%2Ba%2BList) | POST | /push/v1/contacts/refreshList/{listId} | | [Get list refresh status](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Get%2BList%2BRefresh%2BStatus) | GET | /push/v1/contacts/refreshList/{listId}/status/{tokenId} | | [Send a message to all app users](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Send%2Ba%2BMessage%2Bto%2BAll%2BUsers) | POST | /push/v1/messageApp/{messageId}/send | | [Send a message to tagged users](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Send%2Ba%2BMessage%2Bto%2BTagged%2BUsers) | POST | /push/v1/messageTag/{messageId}/send | | [Send a message to a list](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Send%2Ba%2BMessage%2Bto%2Ba%2BList) | POST | /push/v1/messageList/{messageId}/send | | [Send a batch of messages](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Send%2Ba%2BBatch%2BMessage) | POST | /push/v1/messageBatch/{messageid}/send | | [Send a message to specific devices](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Send%2Ba%2BMessage%2Bto%2BSpecific%2BDevices) | POST | /push/v1/messageContact/{messageId}/send | | [Get status for a message sent to all users](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Send%2Ba%2BMessage%2Bto%2BAll%2BUsers) | GET | /push/v1/messageApp/{messageId}/deliveries/{tokenId} | | [Get status for a message sent using tags](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Get%2BMessageTag%2BDelivery%2BStatus) | GET | /push/v1/messageTag/{messageId}/deliveries/{tokenId} | | [Get status for a message sent to a list](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Get%2BMessageList%2BDelivery%2BStatus) | GET | /push/v1/messageList/{messageId}/deliveries/{tokenId} | | [Get status for a message sent to specific contacts](/docs/marketing/marketing-cloud/references/mc_rest_push?meta=Get%2BMessageContact%2BDelivery%2BStatus) | GET | /push/v1/messageContact/{messageId}/deliveries/{tokenId} | Append the operation endpoint addresses to this base URL, replacing `{subdomain}` with the unique subdomain for your Marketing Cloud Engagement tenant: **Version:** 1 ## Servers * `https://{subdomain}.rest.marketingcloudapis.com` * `subdomain (default N/A) The unique API subdomain for your Marketing Cloud Engagement tenant. You can find this value in the Installed Packages section of Marketing Cloud Engagement Setup.` ## Operations ### GET Retrieve all push messages in your account. `GET /push/v1/message` Operation ID: `Get Push Messages`. Required Permission Scope To execute this operation, you must have the `Channels | Push | Read` permission. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `$page` (query, string) The page of results to retrieve. Each page includes the number of records specified by the `$pagesize` parameter. You can retrieve additional pages by incrementing this number in subsequent calls. * `$pageSize` (query, number) The number of records to return on each page of results. The default value is 25. * `$filter` (query, string) A filter to apply to the results. You can filter on the values of the `messageType`, `contentType`, and `status` fields. Filters can include these operators: `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, and `like`. Separate each filter statement with a space. * `$orderBy` (query, string) The field and sort method to use to sort the results. You can sort on these fields: `id`, `name`, `statusId`, `status`, `scheduledDate`, `application`, `applicationId`, `app`, `campaign`, `sendMethodId`, `subject`, `geofenceId`, `createdDate`, and `lastUpdated`. You can sort these fields in ascending (`ASC`) or descending (`DESC`) order. #### Responses * **200** This response indicates that the API accepted the request to retrieve a push message. Media type: `application/json`. Schema: `getPushResponseBody`. _Example_ ``` { "count": 2, "page": 1, "pageSize": 50, "links": {}, "items": [ { "links": {}, "id": "MzexMTV6BM", "messageType": 1, "contentType": 1, "messageObjectId": "ab2182e3-d0dd-47d0-893a-1228fe0b8c9b", "application": { "links": {}, "messageCategories": [ { "id": 16, "name": "MyApp", "buttons": [] } ], "id": "bc93a43d-a227-432e-844e-2cb6eac2ae75", "key": "UGVjcXZDZwT2ZWlMa09FVGl5Mjt4UToxMTc6MA", "name": "My Push Message", "description": "", "createdDate": "2023-11-29T00:17:00Z", "modifiedDate": "2023-11-29T00:19:24.923Z", "configuration": { "customSound": false, "openDirect": false, "customKeys": false, "payloadEditor": false, "messageCategories": false } }, "name": "My Message", "tzPastSendAction": 0, "sendInitiator": 1, "status": 1, "activeTimes": [], "createdDate": "2024-06-10T17:15:00", "lastUpdated": "2024-06-10T17:16:00" }, { "id": "MzeyMTV6BM", "alert": "This is a message", "sound": "default", "badge": "+1", "startDateUtc": "2023-11-29T00:21:00.000Z", "startDate": "2023-11-28T18:21:00", "messageType": 1, "contentType": 1, "messageObjectId": "6d691c6a-9881-4341-bebf-6a0148c74282", "application": { "id": "bc2ae73d-a227-432e-844e-2cb6ea93a4c5", "key": "UGVjcXZDZWlMa09FVGl5MjZwT2t4UToxMTc6MA", "name": "My Message 2", "description": "", "createdDate": "2023-11-29T00:17:00Z", "modifiedDate": "2023-11-29T00:19:24.923Z", "configuration": { "customSound": false, "openDirect": false, "customKeys": false, "payloadEditor": false, "messageCategories": true } }, "name": "Testing123", "tzPastSendAction": 0, "sendInitiator": 0, "status": 1, "title": "Message", "createdDate": "2023-11-28T18:20:00", "lastUpdated": "2023-11-28T18:21:00", "isDuplicationAllowed": false, "currentEditStep": 4, "scheduledTimezone": { "offset": -6, "name": "Central Standard Time (no DST)" } } ] } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### POST Create a push message. `POST /push/v1/message` Operation ID: `Create a Push Message`. Required Permission Scope To execute this operation, you must have the `Channels | Push | Write` permission. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` #### Request body (required) Media type: `application/json`. Schema: `createPushRequestBody`. #### Responses * **201** This response indicates that the API accepted the request to create a push message. Media type: `application/json`. Schema: `createPushResponseBody`. _Example_ ``` { "id": "MTIzOjExNDow", "messageType": 1, "contentType": 1, "name": "My Message Name", "application": { "id": "237690ac-41ff-4d3f-82f2-9c7efd89185f", "name": "MyApplication" }, "alert": "Alert message to show on device", "sound": "Sound to play, or 'default'", "badge": "+1", "content-available": 1, "openDirect": "OD001", "keys": [ { "key": "key01", "value": "value01" }, { "key": "key02", "value": "value02" }, { "key": "key03", "value": "value03" } ], "custom": { "customA": 1, "customB": "custom text b", "customC": { "cC": "custom text c" } }, "sendInitiator": 0, "startDate": "2024-04-30T14:50:00Z", "messagesPerPeriod": 1000, "minutesPerPeriod": 60, "numberOfPeriods": 24, "periodType": 5, "isRollingPeriod": false, "messageLimit": 1, "tzBased": true, "tzPastSendAction": 0, "scheduledTzOffset": -4, "scheduledTzSupportsDst": true, "inclusionLists": [ { "id": "listID01" }, { "id": "listID02" }, { "id": "listID03" } ], "exclusionLists": [ { "id": "listID04" }, { "id": "listID05" }, { "id": "listID06" } ], "status": 2 } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### GET Retrieves a single push message in your account. `GET /push/v1/message/{messageId}` Operation ID: `Get a Push Message by ID`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `messageId` (path, string, required) The unique ID of the message to retrieve. #### Responses * **200** This response indicates that the API accepted the request to retrieve a push message. Media type: `application/json`. Schema: `getPushByIdResponseBody`. _Example_ ``` { "links": {}, "id": "MzexMTV6BM", "messageType": 1, "contentType": 1, "messageObjectId": "ab2182e3-d0dd-47d0-893a-1228fe0b8c9b", "application": { "links": {}, "messageCategories": [ { "id": 16, "name": "MyApp", "buttons": [] } ], "id": "bc93a43d-a227-432e-844e-2cb6eac2ae75", "key": "UGVjcXZDZwT2ZWlMa09FVGl5Mjt4UToxMTc6MA", "name": "My Push Message", "description": "", "createdDate": "2023-11-29T00:17:00Z", "modifiedDate": "2023-11-29T00:19:24.923Z", "configuration": { "customSound": false, "openDirect": false, "customKeys": false, "payloadEditor": false, "messageCategories": false } }, "name": "My Message", "tzPastSendAction": 0, "sendInitiator": 1, "status": 1, "activeTimes": [], "createdDate": "2024-06-10T17:15:00", "lastUpdated": "2024-06-10T17:16:00" } ``` * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Validation Error", "errorcode": 10006, "documentation": "", "validationErrors": [ { "message": "Application is required", "errorcode": 10002, "documentation": "" } ] } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### PUT Update the content or details of a push message. `PUT /push/v1/message/{messageId}` Operation ID: `Update a Push Message`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `messageId` (path, string, required) The unique ID of the message to retrieve. #### Responses * **200** This response indicates that the API accepted the request to create a push message. Media type: `application/json`. Schema: `createPushResponseBody`. _Example: same as POST /push/v1/message 201 response._ * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### DELETE Delete a push message in your account. `DELETE /push/v1/message/{messageId}` Operation ID: `Delete a Push Message`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` #### Responses * **200** Indicates that the API accepted the request to delete the push message. The response doesn’t contain any additional information. * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### GET Retrieve all locations in your account. `GET /push/v1/location` Operation ID: `Get Locations`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `$page` (query, string) The page of results to retrieve. Each page includes the number of records specified by the `$pagesize` parameter. You can retrieve additional pages by incrementing this number in subsequent calls. * `$pageSize` (query, number) The number of records to return on each page of results. The default value is 25. * `$filter` (query, string) A filter to apply to the results. You can filter on the values of the `name` and `locationType` fields. Filters can include these operators: `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, and `like`. There are two possible values for the `locationType` field: `1` (geofence) and `3` (beacon). Separate each filter with `%20`. * `$orderBy` (query, string) The field and sort method to use to sort the results. You can sort on these fields: `locationType`, `name`, `geofenceId`, `createdDate`, and `modifiedDate`. You can sort these fields in ascending (`ASC`) or descending (`DESC`) order. #### Responses * **200** This response indicates that the API accepted the request to retrieve a list of locations. Media type: `application/json`. Schema: `getLocationsResponseBody`. _Example_ ``` { "count": 2, "page": 1, "pageSize": 25, "links": {}, "items": [ { "id": "5555555555A", "name": "testA", "location": "Main Location on Elm Street", "description": "Location at 123 Elm St, Nowhere, CA 00000", "center": { "latitude": 30.750362, "longitude": -95.374712 }, "radius": 50, "locationType": 1 }, { "id": "5555555555B", "name": "testB", "location": "Secondary Location on Maple Street", "description": "Location at 456 Maple St, Nowhere, CA 00000", "center": { "latitude": 30.751362, "longitude": -95.374712 }, "radius": 50, "locationType": 1 } ] } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### POST Create a new geofenced or beacon-based location. `POST /push/v1/location` Operation ID: `Create a Location`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` #### Request body (required) Media type: `application/json`. Schema: `createLocationRequestBody`. #### Responses * **201** This response indicates that the API accepted the request to create a location. Media type: `application/json`. Schema: `createLocationResponseBody`. _Example_ ``` { "id": "5555555555A" } ``` * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### GET Retrieve details of a specific location. `GET /push/v1/location/{locationId}` Operation ID: `Get a Location`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `locationId` (path, string, required) The unique ID of a location object. #### Responses * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### PUT Modify the details of an existing location. `PUT /push/v1/location/{locationId}` Operation ID: `Update a Location`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `locationId` (path, string, required) The unique ID of a location object. #### Request body (required) Media type: `application/json`. Schema: `createLocationRequestBody`. #### Responses * **200** Indicates that the API accepted the request to update the location. The response doesn’t contain any additional information. * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### DELETE Delete a specific location by providing its ID. `DELETE /push/v1/location/{locationId}` Operation ID: `Delete a Location`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `locationId` (path, string, required) The unique ID of a location object. #### Responses * **200** Indicates that the API accepted the request to delete the location. The response doesn’t contain any additional information. * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### GET Retrieve a list of all applications in an account. `GET /push/v1/application` Operation ID: `Get Apps`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` #### Responses * **200** This response indicates that the API accepted the request to retrieve a list of applications. Media type: `application/json`. Schema: `getApplicationsResponseBody`. _Example_ ``` [ { "id": "bc2ae73d-a227-432e-2cb6-ea844e93a4c5", "key": "UGVjcXZToxMTcDZWlMa09FVt4Gl5MjZwT2U6MA", "name": "My New App", "description": "", "createdDate": "2023-11-29T00:17:00Z", "modifiedDate": "2023-11-29T00:19:24.923Z", "apnsEnabled": false, "gcmEnabled": true, "configuration": { "customSound": false, "openDirect": false, "customKeys": false, "payloadEditor": false, "messageCategories": true }, "deviceEndpoint": "https://mct3hhcl3k2y71y5r--20f0q7cs84.device.marketingcloudapis.com/" } ] ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### GET Retrieve information about a specific app by providing its ID. `GET /push/v1/application/{appId}` Operation ID: `Get an App by ID`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `appId` (path, string (uuid), required) The unique ID of an app that receives push messages. #### Responses * **200** This response indicates that the API accepted the request to retrieve a list of applications. Media type: `application/json`. Schema: `getApplicationResponseBody`. _Example_ ``` { "links": {}, "messageCategories": [ { "id": 16, "name": "TestAPI", "buttons": [] } ], "id": "bc2ae73d-a227-432e-2cb6-ea844e93a4c5", "key": "UGVjcXZToxMTcDZWlMa09FVt4Gl5MjZwT2U6MA", "name": "My New App", "description": "", "createdDate": "2023-11-29T00:17:00Z", "modifiedDate": "2023-11-29T00:19:24.923Z", "apnsEnabled": false, "gcmEnabled": true, "configuration": { "customSound": false, "openDirect": false, "customKeys": false, "payloadEditor": false, "messageCategories": true }, "deviceEndpoint": "https://mct3hhcl3k2y71y5r--20f0q7cs84.device.marketingcloudapis.com/" } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### GET Retrieve a list of custom keys for an app. `GET /push/v1/application/{appId}/key` Operation ID: `Get App Keys`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `appId` (path, string (uuid), required) The unique ID of an app that receives push messages. #### Responses * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### PUT Update the custom keys for an app. When you update the keys for an app, the existing keys are removed and replaced with the keys specified in the request. `PUT /push/v1/application/{appId}/key` Operation ID: `Update App Keys`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `appId` (path, string (uuid), required) The unique ID of an app that receives push messages. #### Request body (required) Media type: `application/json`. Schema: `array of string`. Array of `string`. _Example_ ``` [ "key1", "key2" ] ``` #### Responses * **200** Indicates that the API accepted the request to update the app keys. The response doesn’t contain any additional information. * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### DELETE Delete the custom keys for an app. A successful deletion request removes all of the keys for the app. `DELETE /push/v1/application/{appId}/key` Operation ID: `Delete App Keys`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `appId` (path, string (uuid), required) The unique ID of an app that receives push messages. #### Responses * **200** Indicates that the API accepted the request to delete the app keys. The response doesn’t contain any additional information. * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### DELETE Delete a specific app key by specifying its value. `DELETE /push/v1/application/{appId}/key/{key}` Operation ID: `Delete an App Key`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `appId` (path, string (uuid), required) The unique ID of an app that receives push messages. * `key` (path, string, required) The value of a custom key for an app. #### Responses * **200** Indicates that the API accepted the request to delete an app key. The response doesn’t contain any additional information. * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### POST Refresh a list of recipients in MobilePush. `POST /push/v1/contacts/refreshList/{listId}` Operation ID: `Refresh a List`. This POST request doesn’t require a request body. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `listId` (path, string, required) The unique ID of a list. #### Responses * **202** This response indicates that the API accepted the request to refresh a list of app users. Media type: `application/json`. Schema: `refreshListResponseBody`. _Example_ ``` { "tokenId": "NDo8NDow", "lastPublishDate": "2024-06-12T15:38:12.030Z" } ``` * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request contains the correct endpoint URI. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 404, "message": "Not Found" } ``` ### GET Retrieve the status of a MobilePush list refresh request. `GET /push/v1/contacts/refreshList/{listId}/status/{tokenId}` Operation ID: `Get List Refresh Status`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `listId` (path, string, required) The unique ID of a list. * `tokenId` (path, string, required) The token associated with a request to refresh a MobilePush list. #### Responses * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request contains the correct endpoint URI. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 404, "message": "Not Found" } ``` ### POST Broadcast a push message to all users of a push-enabled app. `POST /push/v1/messageApp/{messageId}/send` Operation ID: `Send a Message to All Users`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `messageId` (path, string, required) The unique ID of the message to retrieve. #### Request body (required) Media type: `application/json`. Schema: `sendMessageRequestBody`. #### Responses * **202** This response indicates that the API accepted the request to send the push message. Media type: `application/json`. Schema: `sendMessageResponseBody`. _Example_ ``` { "tokenId": "fe79d2ea-b7fd-4c86-92e3-e443194a5fe0" } ``` * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### POST Send a push message to all users of a push-enabled app who have specific tags. `POST /push/v1/messageTag/{messageId}/send` Operation ID: `Send a Message to Tagged Users`. The request body must include the `inclusionTags` or `exclusionTags` array, or both. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `messageId` (path, string, required) The unique ID of the message to retrieve. #### Request body (required) Media type: `application/json`. Schema: `sendMessageTagRequestBody`. #### Responses * **202** This response indicates that the API accepted the request to send the push message. Media type: `application/json`. Schema: `sendMessageResponseBody`. _Example_ ``` { "tokenId": "fe79d2ea-b7fd-4c86-92e3-e443194a5fe0" } ``` * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### POST Send a push message to all contacts in a MobilePush list. `POST /push/v1/messageList/{messageId}/send` Operation ID: `Send a Message to a List`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `messageId` (path, string, required) The unique ID of the message to retrieve. #### Request body (required) Media type: `application/json`. Schema: `sendMessageListRequestBody`. #### Responses * **202** This response indicates that the API accepted the request to send the push message. Media type: `application/json`. Schema: `sendMessageResponseBody`. _Example_ ``` { "tokenId": "fe79d2ea-b7fd-4c86-92e3-e443194a5fe0" } ``` * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### POST Send a batch of push messages to specific users by specifying tags or device tokens. `POST /push/v1/messageBatch/{messageid}/send` Operation ID: `Send a Batch Message`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `messageId` (path, string, required) The unique ID of the message to retrieve. #### Request body (required) Media type: `application/json`. Schema: `sendMessageBatchRequestBody`. #### Responses * **202** This response indicates that the API accepted the request to send the push message. Media type: `application/json`. Schema: `sendMessageBatchResponseBody`. _Example_ ``` [ { "tokenId": "5b64365d-6add-4f84-a8bf-a5f786a293ea", "deviceTokens": [ "DeviceToken1", "DeviceToken2" ] }, { "tokenId": "b0824a90-b354-402e-8ac7-cf5d72e2768d", "subscriberKeys": [ "SubscriberKey1" ] } ] ``` * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### POST Send a push message to specific users of an app by specifying their device tokens or subscriber keys. `POST /push/v1/messageContact/{messageId}/send` Operation ID: `Send a Message to Specific Devices`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `messageId` (path, string, required) The unique ID of the message to retrieve. #### Request body (required) Media type: `application/json`. Schema: `sendMessageContactRequestBody`. #### Responses * **202** This response indicates that the API accepted the request to send the push message. Media type: `application/json`. Schema: `sendMessageResponseBody`. _Example_ ``` { "tokenId": "fe79d2ea-b7fd-4c86-92e3-e443194a5fe0" } ``` * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### GET Retrieve the status of push messages that were sent to users of an app. `GET /push/v1/messageApp/{messageId}/deliveries/{tokenId}` Operation ID: `Get MessageApp Delivery Status`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `messageId` (path, string, required) The unique ID of the message to retrieve. #### Responses * **200** This response indicates that the API accepted the request to provide message delivery status. Media type: `application/json`. Schema: `getMessageAppDeliveryResponseBody`. _Example_ ``` { "message": "MyPushMessage", "count": 50, "createDate": "2023-08-05T11:57:19.247" } ``` * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### GET Retrieve the status of push messages that were sent to contacts based on their tags. `GET /push/v1/messageTag/{messageId}/deliveries/{tokenId}` Operation ID: `Get MessageTag Delivery Status`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `messageId` (path, string, required) The unique ID of the message to retrieve. #### Responses * **200** This response indicates that the API accepted the request to provide message delivery status. Media type: `application/json`. Schema: `getMessageAppDeliveryResponseBody`. _Example_ ``` { "message": "MyPushMessage", "count": 50, "createDate": "2023-08-05T11:57:19.247" } ``` * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### GET Retrieve the status of push messages that were sent to contacts who are on a MobilePush list. `GET /push/v1/messageList/{messageId}/deliveries/{tokenId}` Operation ID: `Get MessageList Delivery Status`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `messageId` (path, string, required) The unique ID of the message to retrieve. #### Responses * **200** This response indicates that the API accepted the request to provide message delivery status. Media type: `application/json`. Schema: `getMessageAppDeliveryResponseBody`. _Example_ ``` { "message": "MyPushMessage", "count": 50, "createDate": "2023-08-05T11:57:19.247" } ``` * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ### GET Retrieve the status of push messages that were sent to specific users of a mobile app. `GET /push/v1/messageContact/{messageId}/deliveries/{tokenId}` Operation ID: `Get MessageContact Delivery Status`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `messageId` (path, string, required) The unique ID of the message to retrieve. #### Responses * **200** This response indicates that the API accepted the request to provide message delivery status. Media type: `application/json`. Schema: `getMessageAppDeliveryResponseBody`. _Example_ ``` { "message": "MyPushMessage", "count": 50, "createDate": "2023-08-05T11:57:19.247" } ``` * **400** This response indicates that the request contained information that the API couldn’t process. When you receive a 400 response, verify that the request uses the correct syntax, and that the properties in the request body refer to valid values. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example: same as GET /push/v1/message/{messageId} 400 response._ * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "Contact your Marketing Cloud administrator for permission to Schedule and Send Message", "errorcode": 20002, "documentation": "" } ``` ## Schemas ### getPushResponseBody * `count` (_number (integer)_) The number of results returned in the current result set. * `page` (_number (integer)_) The current page number of results. * `pageSize` (_number (integer)_) The maximum number of items included in the current page of results. * `items` (_array of pushMessageObject_) An array of objects. Each object contains information about push messages that match your filter criteria. ### httpErrorResponseBody * `documentation` (_string_) Contains a link to the [Marketing Cloud Engagement developer documentation page about handling REST API errors](https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm). * `errorcode` (_integer_) The error code. In some situations, this value can be 0. * `message` (_string_) The error message. ### mceErrorResponseBody * `documentation` (_string_) An empty string. * `errorcode` (_integer_) An internal error code. For a complete list of error codes, see [Handle Errors in REST API](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/error-handling.html). * `message` (_string_) The error message. ### createPushRequestBody ### createPushResponseBody Includes all fields of `id`, `pushMessageObject`. ### getPushByIdResponseBody Includes all fields of `id`, `pushMessageObject`. ### getLocationsResponseBody * `count` (_number (integer)_) The number of results returned in the current result set. * `page` (_number (integer)_) The current page number of results. * `pageSize` (_number (integer)_) The maximum number of items included in the current page of results. * `items` (_array of object_) An array of objects. Each object contains information about locations that match your filter criteria. Includes all fields of `id`, `locationObject`. ### createLocationRequestBody ### createLocationResponseBody * `id` (_string_) A unique identifier for the location. ### getApplicationsResponseBody Array of `applicationObject`. ### getApplicationResponseBody Includes all fields of `messageCategories`, `applicationObject`. ### refreshListResponseBody * `tokenId` (_string_) A unique token that represents the request to refresh the list. Use this token to retrieve the status of the refresh operation. * `lastPublishDate` (_string (date-time)_) The date and time when the list was last published. ### sendMessageRequestBody An object that defines the content and properties of the message. * `inclusionTags` (_array of string_) An array that contains tags that identify the contacts who the message is sent to. * `exclusionTags` (_array of string_) An array that contains tags that identify the contacts who are excluded from the message. * `override` (_boolean_) A value that indicates whether to override the text and settings of the specified message. If the value is `true`, you can override the message title, subtitle, and body, as well as other settings such as the sound that's played when a user receives a message. * `messageText` (_boolean_) The message body. If you specify it in the request, and if the value of `override` is `true`, then this replaces the body text in the message. * `title` (_string_) The message title. If you specify it in the request, and if the value of `override` is `true`, then this replaces the title text in the message. * `subtitle` (_string_) The message subtitle. If you specify it in the request, and if the value of `override` is `true`, then this replaces the subtitle text in the message. * `mutable-content` (_boolean_) A value that indicates whether to enable rich push functionality for the message. * `sendTime` (_string (date-time)_) The date and time to send the message. This value must be a time in the future, and must use the format `YYYY-MM-DD HH:MM`. * `blackoutWindow` (_object_) An object that describes a period in which messages aren't sent. * `windowStart` (_string_) The start time for the window. Specify this value using a 24-hour time, such as `2230` for 10:30 PM. * `windowEnd` (_string_) The end time for the window. Specify this value using a 24-hour time, such as `2230` for 10:30 PM. * `utcOffset` (_string_) The time offset for the window. This value describes the number of hours and minutes before or after Coordinated Universal Time (UTC), such as `0530` for UTC+5:30 or `-0800` for UTC-08:00. * `sound` (_string_) The name of a sound file to play when the message arrives on the recipient’s device. The file name can contain up to 100 characters. This value overrides the value in the push message definition. * `badge` (_string_) The number to show in the notification badge on iOS devices. With iOS SDK version 4.9.5 and newer, the badge displays this number and increments by one for each new unread message. With older iOS SDK versions, the badge displays this number but doesn’t increment. * `openDirect` (_string_) A value that determines the location in the app that the user is sent to when they tap the push message. This value overrides the value on the push message definition. The value can contain up to 15 characters. * `customPayload` (_object_) An object that contains key-value pairs that represent a custom payload for the push message. * `customKeys` (_object_) An object that contains key-value pairs that represent custom keys for the push message. _Example_ ``` { "Override": true, "MessageText": "The Reticulated Widget and other new items are available for a limited time!", "title": "New Items Just Added", "subtitle": "Visit the shop now to see what's new", "mutable-content": 1, "SendTime": "2024-06-13 09:00", "Sound": "MyFile.caf", "Badge": "+1", "OpenDirect": "OD01", "CustomKeys": { "keyA": "valueA", "keyB": "valueB" }, "CustomPayload": { "customA": "customA_value" } } ``` ### sendMessageResponseBody * `tokenId` (_string_) A token that represents a request to send a push message. You can use this token to request the status of the send. ### sendMessageTagRequestBody An object that defines the content and properties of the message. * `inclusionTags` (_array of string_) An array that contains tags that identify the contacts who the message is sent to. * `exclusionTags` (_array of string_) An array that contains tags that identify the contacts who are excluded from the message. * `override` (_boolean_) A value that indicates whether to override the text and settings of the specified message. If the value is `true`, you can override the message title, subtitle, and body, as well as other settings such as the sound that's played when a user receives a message. * `messageText` (_boolean_) The message body. If you specify it in the request, and if the value of `override` is `true`, then the value of this property replaces the body text in the message. * `title` (_string_) The message title. If you specify it in the request, and if the value of `override` is `true`, then the value of this property replaces the title text in the message. * `subtitle` (_string_) The message subtitle. If you specify it in the request, and if the value of `override` is `true`, then the value of this property replaces the subtitle text in the message. * `mutable-content` (_boolean_) A value that indicates whether to enable rich push functionality for the message. * `sendTime` (_string (date-time)_) The date and time to send the message. This value must be a time in the future, and must use the format `YYYY-MM-DD HH:MM`. * `blackoutWindow` (_object_) An object that describes a period in which messages aren't sent. * `windowStart` (_string_) The start time for the window. Specify this value using a 24-hour time, such as `2230` for 10:30 PM. * `windowEnd` (_string_) The end time for the window. Specify this value using a 24-hour time, such as `2230` for 10:30 PM. * `utcOffset` (_string_) The time offset for the window. This value describes the number of hours and minutes before or after Coordinated Universal Time (UTC), such as `0530` for UTC+5:30 or `-0800` for UTC-08:00. * `sound` (_string_) The name of a sound file to play when the message arrives on the recipient’s device. The file name can contain up to 100 characters. This value overrides the value in the push message definition. * `badge` (_string_) The number to show in the notification badge on iOS devices. With iOS SDK version 4.9.5 and newer, the badge displays this number and increments by one for each new unread message. With older iOS SDK versions, the badge displays this number but doesn’t increment. * `openDirect` (_string_) A value that determines the location in the app that the user is sent to when they tap the push message. This value overrides the value on the push message definition. The value can contain up to 15 characters. * `customPayload` (_object_) An object that contains key-value pairs that represent a custom payload for the push message. * `customKeys` (_object_) An object that contains key-value pairs that represent custom keys for the push message. _Example_ ``` { "InclusionTags": [ "Midwest" ], "ExclusionTags": [ "Indiana, Ohio" ], "Override": true, "MessageText": "The Reticulated Widget and other new items are available for a limited time!", "title": "New Items Just Added", "subtitle": "Visit the shop now to see what's new", "mutable-content": 1, "SendTime": "2024-06-13 09:00", "Sound": "MyFile.caf", "Badge": "+1", "OpenDirect": "OD01", "CustomKeys": { "keyA": "valueA", "keyB": "valueB" }, "CustomPayload": { "customA": "customA_value" } } ``` ### sendMessageListRequestBody An object that defines the content and properties of the message. * `inclusionListIds` (_array of string_) An array that contains the IDs of lists to send the message to. * `exclusionListIds` (_array of string_) An array that contains the IDs of lists to exclude from the send. * `inclusionDataExtensionIds` (_array of string_) An array that contains the external keys of data extensions to send the message to. * `exclusionDataExtensionIds` (_array of string_) An array that contains the external keys of data extensions to exclude from the send. * `override` (_boolean_) A value that indicates whether to override the text and settings of the specified message. If the value is `true`, you can override the message title, subtitle, and body, as well as other settings such as the sound that's played when a user receives a message. * `messageText` (_boolean_) The message body. If you specify it in the request, and if the value of `override` is `true`, then the value of this property replaces the body text in the message. * `title` (_string_) The message title. If you specify it in the request, and if the value of `override` is `true`, then the value of this property replaces the title text in the message. * `subtitle` (_string_) The message subtitle. If you specify it in the request, and if the value of `override` is `true`, then the value of this property replaces the subtitle text in the message. * `mutable-content` (_boolean_) A value that indicates whether to enable rich push functionality for the message. * `sendTime` (_string (date-time)_) The date and time to send the message. This value must be a time in the future, and must use the format `YYYY-MM-DD HH:MM`. * `blackoutWindow` (_object_) An object that describes a period in which messages aren't sent. * `windowStart` (_string_) The start time for the window. Specify this value using a 24-hour time, such as `2230` for 10:30 PM. * `windowEnd` (_string_) The end time for the window. Specify this value using a 24-hour time, such as `2230` for 10:30 PM. * `utcOffset` (_string_) The time offset for the window. This value describes the number of hours and minutes before or after Coordinated Universal Time (UTC), such as `0530` for UTC+5:30 or `-0800` for UTC-08:00. * `sound` (_string_) The name of a sound file to play when the message arrives on the recipient’s device. The file name can contain up to 100 characters. This value overrides the value in the push message definition. * `badge` (_string_) The number to show in the notification badge on iOS devices. With iOS SDK version 4.9.5 and newer, the badge displays this number and increments by one for each new unread message. With older iOS SDK versions, the badge displays this number but doesn’t increment. * `openDirect` (_string_) A value that determines the location in the app that the user is sent to when they tap the push message. This value overrides the value on the push message definition. The value can contain up to 15 characters. * `customPayload` (_object_) An object that contains key-value pairs that represent a custom payload for the push message. * `customKeys` (_object_) An object that contains key-value pairs that represent custom keys for the push message. _Example_ ``` { "InclusionListIds": [ "UTZ6QTh4MVRmMC1XZlN5QUtnS3hWdzo2NTow" ], "ExclusionListIds": [ "VWRoY1IzcWh2RXVvc3FDYTRfcGtvQTo2NTow" ], "Override": true, "MessageText": "The Reticulated Widget and other new items are available for a limited time!", "title": "New Items Just Added", "subtitle": "Visit the shop now to see what's new", "mutable-content": 1, "SendTime": "2024-06-13 09:00", "Sound": "MyFile.caf", "Badge": "+1", "OpenDirect": "OD01", "CustomKeys": { "keyA": "valueA", "keyB": "valueB" }, "CustomPayload": { "customA": "customA_value" } } ``` ### sendMessageBatchRequestBody An object that defines the content and properties of a batch of push messages. Array of `object`. * `deviceTokens` (_array of string_) An array that contains one or more device tokens to send the message to. Your request must include either this or the `inclusionTags` array. * `inclusionTags` (_array of string_) An array that contains one or more contact tags to send the message to. Your request must include either this or the `deviceTokens` array. * `message` (_object_) An object that defines the content of a message. Each object in a batch request must include the `message` object. * `alert` (_string_) The content of the message. * `badge` (_string_) The number to show in the notification badge on iOS devices. With iOS SDK version 4.9.5 and newer, the badge displays this number and increments by one for each new unread message. With older iOS SDK versions, the badge displays this number but doesn’t increment. * `sound` (_string_) The name of a sound file to play when the message arrives on the recipient’s device. The file name can contain up to 100 characters. This value overrides the value in the push message definition. * `custom` (_object_) An object that contains custom data to include with the message send. Specify each custom data element as a key-value pair. * `{key}` (_string_) * `mutable-content` (_boolean_) A value that indicates whether to enable rich push functionality for the message. * `title` (_string_) The message title. If you don't specify a title in your request, the message is sent using the title text from the message specified by the `messageId` parameter. * `subtitle` (_string_) The message subtitle. If you don't specify a subtitle in your request, the message is sent using the subtitle text from the message specified by the `messageId` parameter. _Example_ ``` [ { "deviceTokens": [ "DeviceToken1", "DeviceToken2" ], "inclusionTags": [ "footballTeam" ], "message": { "alert": "Your team WINS!", "badge": "+1", "sound": "default", "custom": { "6": "20" } } }, { "subscriberKeys": [ "SubscriberKey1" ], "inclusionTags": [ "hockeyTeam" ], "message": { "alert": "Good game, team!", "badge": "+1", "sound": "default", "custom": { "6": "20" } } } ] ``` ### sendMessageBatchResponseBody An array that contains one or more tokens. Each token represents a request to send a push message. You can use this token to request the status of the send. Array of `object`. * `tokenId` (_string_) A token that represents a request to send a push message. You can use this token to request the status of the send. ### sendMessageContactRequestBody An object that defines the content and properties of the message. * `inclusionTags` (_array of string_) An array that contains tags that identify the contacts who the message is sent to. * `exclusionTags` (_array of string_) An array that contains tags that identify the contacts who are excluded from the message. * `deviceTokens` (_array of string_) An array that contains one or more device tokens to send the message to. Your request must include either this array or the `subscriberKeys` array. * `subscriberKeys` (_array of string_) An array that contains one or more subscriber keys to send the message to. Your request must include either this array or the `deviceTokens` array. * `override` (_boolean_) A value that indicates whether to override the text and settings of the specified message. If the value is `true`, you can override the message title, subtitle, and body, as well as other settings such as the sound that's played when a user receives a message. * `messageText` (_boolean_) The message body. If you specify it in the request, and if the value of `override` is `true`, then the value of this property replaces the body text in the message. * `title` (_string_) The message title. If you specify it in the request, and if the value of `override` is `true`, then the value of this property replaces the title text in the message. * `subtitle` (_string_) The message subtitle. If you specify it in the request, and if the value of `override` is `true`, then the value of this property replaces the subtitle text in the message. * `mutable-content` (_boolean_) A value that indicates whether to enable rich push functionality for the message. * `sendTime` (_string (date-time)_) The date and time to send the message. This value must be a time in the future, and must use the format `YYYY-MM-DD HH:MM`. * `blackoutWindow` (_object_) An object that describes a period in which messages aren't sent. * `windowStart` (_string_) The start time for the window. Specify this value using a 24-hour time, such as `2230` for 10:30 PM. * `windowEnd` (_string_) The end time for the window. Specify this value using a 24-hour time, such as `2230` for 10:30 PM. * `utcOffset` (_string_) The time offset for the window. This value describes the number of hours and minutes before or after Coordinated Universal Time (UTC), such as `0530` for UTC+5:30 or `-0800` for UTC-08:00. * `sound` (_string_) The name of a sound file to play when the message arrives on the recipient’s device. The file name can contain up to 100 characters. This value overrides the value in the push message definition. * `badge` (_string_) The number to show in the notification badge on iOS devices. With iOS SDK version 4.9.5 and newer, the badge displays this number and increments by one for each new unread message. With older iOS SDK versions, the badge displays this number but doesn’t increment. * `openDirect` (_string_) A value that determines the location in the app that the user is sent to when they tap the push message. This value overrides the value on the push message definition. The value can contain up to 15 characters. * `customPayload` (_object_) An object that contains key-value pairs that represent a custom payload for the push message. * `customKeys` (_object_) An object that contains key-value pairs that represent custom keys for the push message. _Example_ ``` { "DeviceTokens": [ "DeviceToken1", "DeviceToken2", "DeviceToken3" ], "InclusionTags": [ "Midwest" ], "ExclusionTags": [ "Indiana", "Ohio" ], "Override": true, "MessageText": "The Reticulated Widget and other new items are available for a limited time!", "title": "New Items Just Added", "subtitle": "Visit the shop now to see what's new", "mutable-content": 1, "SendTime": "2024-06-13 09:00", "Sound": "MyFile.caf", "Badge": "+1", "OpenDirect": "OD01", "CustomKeys": { "keyA": "valueA", "keyB": "valueB" }, "CustomPayload": { "customA": "customA_value" } } ``` ### getMessageAppDeliveryResponseBody * `message` (_string_) The ID of the message object. * `count` (_number (integer)_) The number of messages sent as part of the request. * `createDate` (_string (date-time)_) The date and time when the request to send the message was created. ### pushMessageObject An object that contains information about a push message, such as its contents, media attributes, included recipients, and excluded recipients. * `alert` (_string_) The content of the message. * `application` (_object_) Information about the app that the message is associated with. * `id` (_string_) The unique ID of the app. * `name` (_string_) The name of the app. * `badge` (_number (integer)_) The number to show in the notification badge on iOS devices. With iOS SDK version 4.9.5 and newer, the badge displays this number and increments by one for each new unread message. With older iOS SDK versions, the badge displays this number but doesn’t increment. * `content-available` (_number (integer)_) A value that indicates whether content is available to deliver to the device by using background push. Set this value to `1` to deliver the message as a silent push. This parameter applies only to apps integrated with the background push functionality available in iOS and Android. * `contentType` (_number (integer)_) Indicates the type of content that's included in the message. Possible values: `1` (alert), `2` (inbox), and `3` (inbox and alert). The default value is `1`. * `custom` (_object_) If your use case requires you to manually specify the body of the push request, place it in this object. * `endDate` (_string (date-time)_) Date and time when the message is no longer available for sends. This parameter applies only to messages where the value of `contentType` is `CloudPage` or `Alert+CloudPage`. The value of the `endDate` property must be later than that of `startDate`. * `exclusionLists` (_array of object_) An array of ID objects. Each object contains the ID of an exclusion list. Include this array only when the value of `sendInitiator` is `0`. * `id` (_string_) The unique ID of an exclusion list. * `geofences` (_array of object_) An array of objects that indicate the geofences associated with the message. Use only when the value of `sendInitiator` is `1`. * `id` (_string_) The unique ID of a geofence. * `inclusionLists` (_array of object_) An array of ID objects. Each object contains the ID of an inclusion list. Include this array only when the value of `sendInitiator` is `0`. * `id` (_string_) The unique ID of an inclusion list. * `isRollingPeriod` (_boolean_) A value that indicates whether a message sending limit resets after a rolling time period or ends at a specified time. * `keys` (_array of object_) An array of key-value pairs that correspond to customer values defined in MobilePush. These keys override the values in the push message definition. * `key` (_string_) * `value` (_string_) * `media` (_object_) An array that describes the rich media content to include in the message. * `iosUrl` (_string_) The URL of the media content to use when sending the message to iOS devices. * `androidUrl` (_string_) The URL of the media content to use when sending the message to Android devices. * `alt` (_string_) The text to display if the rich media content can’t be included in the message. * `messageLimit` (_number (integer)_) The total number of times a message displays on a mobile device. * `messageType` (_number (integer)_) Indicates the type of message. Possible values: `1` (outbound), `3` (location entry), `4` (location exit), `5` (beacon), or `8` (inbox). The default value is `1`. * `messageObjectId` (_string (uuid)_) A unique, system-generated ID for the push message. * `messagesPerPeriod` (_number (integer)_) The number of messages that can be sent during a specified time period. Use this value to prevent a large volume of users from responding to the notification at the same time. Specify this value only if the value of `sendInitiator` is `0`. * `name` (_string_) The name of the message. The name can contain up to 100 characters. For Content Builder messages, use the format `{content name}-{unique identifier}`. For example, `my message-0debaa7a11e11b0a00b12345ef384b1z`. * `numberOfPeriods` (_number (integer)_) Indicates the time span of the message sending period. Possible values: `1` (year), `2` (month), `3` (week), `4` (day), `5` (hour). * `openDirect` (_string_) A value that determines the location in the app that the user is sent to when they tap the push message. This value overrides the value on the push message definition. The value can contain up to 15 characters. * `pageId` (_number (integer)_) The unique ID of the page associated with the message. Use only with CloudPage and Alert+CloudPage sends. * `periodType` (_number (integer)_) * `scheduledTzOffset` (_number (float)_) The UTC offset for the message. The default value is `-6.0`. * `scheduledTzSupportsDst` (_boolean_) A value that indicates whether the scheduled time zone supports Daylight Saving Time (DST). The default value is `false`. * `sendInitiator` (_number (integer)_) The method used to initiate the send for a push message. Possible values: `0` (UI-based send), `1` (API), `2` (automation), or `3` (Journey Builder). The default value is `1`. * `sound` (_string_) The name of a sound file to play when the message arrives on the recipient’s device. The file name can contain up to 100 characters. This value overrides the value in the push message definition. * `startDate` (_string (date-time)_) The date and time when the message becomes available for sending. The default value is the message creation time. * `status` (_number (integer)_) A value that indicates the status of the message. Possible values: `1` (draft), `2` (active), `3` (inactive), or `4` (deleted). The default value is `2`. * `subject` (_string_) The subject line of the message. * `tzBased` (_boolean_) A value that indicates whether a send occurs based on the specified time zone for a mobile device, as reflected in the recipient’s contact record. To ensure timely delivery for each time zone, make sure that any dependent data extensions and audiences are available to be refreshed up to 14 hours before the scheduled send time. The default value is `false`. Specify this value only when the value of `sendInitiator` is `0`. * `tzPastSendAction` (_number (integer)_) Indicates the action to perform when a time-zone-based send occurs, but the send time has already passed for some time zones. Possible values: `1` (send immediately), `2` (send at scheduled time on the next day), or `3` (never send). The default value is `1`. * `url` (_string_) The URL of a destination page for the message. Use this value with the CloudPage and Alert+CloudPage send types. _Example_ ``` { "messageType": 1, "contentType": 1, "name": "My Message Name", "application": { "id": "237690ac-41ff-4d3f-82f2-9c7efd89185f", "name": "MyApplication" }, "alert": "Alert message to show on device", "sound": "Sound to play, or 'default'", "badge": "+1", "content-available": 1, "openDirect": "OD001", "keys": [ { "key": "key01", "value": "value01" }, { "key": "key02", "value": "value02" }, { "key": "key03", "value": "value03" } ], "custom": { "customA": 1, "customB": "custom text b", "customC": { "cC": "custom text c" } }, "sendInitiator": 0, "startDate": "2024-04-30T14:50:00Z", "endDate": "2024-04-30T14:55:00Z", "messagesPerPeriod": 1000, "minutesPerPeriod": 60, "numberOfPeriods": 24, "periodType": 5, "isRollingPeriod": false, "messageLimit": 1, "tzBased": true, "tzPastSendAction": 0, "scheduledTzOffset": -4, "scheduledTzSupportsDst": true, "inclusionLists": [ { "id": "listID01" }, { "id": "listID02" }, { "id": "listID03" } ], "exclusionLists": [ { "id": "listID04" }, { "id": "listID05" }, { "id": "listID06" } ], "status": 2, "pageId": 456, "url": "http://www.example.com", "subject": "My inbox subject line", "media": { "iosUrl": "https://example.com", "androidUrl": "https://example.com", "alt": "Example ALT Text" }, "geofences": [ { "id": "MTIzOjEyODow" }, { "id": "MzIxOjEyODow" } ] } ``` ### id A unique object identifier. Type: `string`. ### locationObject An object that contains details about a location. * `attributes` (_array of object_) An array that contains additional attributes related to the location. * `attribute` (_string_) * `value` (_string_) * `center` (_object_) An object that contains the coordinates of the center point of the location. * `latitude` (_number (float)_) The latitude of the center of the location. * `longitude` (_number (float)_) The longitude of the center of the location. * `description` (_string_) A description of the location. * `location` (_string_) A name or description of the location. * `locationType` (_number (integer)_) A value that indicates the type of location. Possible values: `1` (geofence) and `3` (beacon). * `major` (_number (integer)_) A number that identifies a group of beacons. For example, a major number can be used to indicate all locations of a department store in a particular city. * `minor` (_number (integer)_) A number that identifies a specific beacon. For example, a minor number can be used to indicate the women’s clothing section in a department store. * `name` (_string_) A name for the location object. * `proximityUuid` (_string_) A unique identifier for a beacon, typically found on the beacon hardware. This value is required when the value of `locationType` is `3`. * `radius` (_number (integer)_) The number of miles that the radius of location extends from the center point. _Example_ ``` { "name": "Location A", "location": "Main Location on Elm Street", "description": "Location at 123 Elm St, Nowhere, CA 00000", "center": { "latitude": 30.750362, "longitude": -95.374712 }, "radius": 50, "attributes": [ { "attribute": "Address 1", "value": "123 Elm St" }, { "attribute": "City", "value": "Nowhere" }, { "attribute": "State", "value": "CA" }, { "attribute": "Zip", "value": "00000" } ] } ``` ### applicationObject An object that contains information about an app that can receive push messages. * `apnsEnabled` (_boolean_) A value that indicates whether Apple Push Notification Service (APNs) is enabled for the app. * `configuration` (_object_) An object that contains additional configuration data for the app. * `customSound` (_boolean_) A value that indicates whether the app supports custom sounds. * `openDirect` (_boolean_) A value that indicates whether the app supports opening a specific area of the app when a recipient taps a push notification. * `customKeys` (_boolean_) A value that indicates whether the app supports custom key-value pairs. * `payloadEditor` (_boolean_) A value that indicates whether payload editing is enabled for the app. * `messageCategories` (_boolean_) A value that indicates whether the app supports custom category and button values. * `createdDate` (_string_) The date and time when the app was created. * `description` (_string_) Additional information about the app. * `deviceEndpoint` (_string_) A URL that’s used to configure the MobilePush SDK. * `gcmEnabled` (_boolean_) A value that indicates whether Firebase Cloud Messaging (FCM) is enabled for the app. * `id` (_string_) The unique ID of the app. * `key` (_string_) The external ID of the app. * `modifiedDate` (_string_) The date and time when the app was last modified. * `name` (_string_) The name of the app. ### messageCategories An array that contains information about custom categories for the app. Array of `object`. * `buttons` (_array of object_) An array that contains information about custom buttons for the app. * `deviceType` (_string_) The platform name for a button. Possible values are `iOS` and `Android`. * `name` (_string_) The name of the button. * `id` (_number (integer)_) The ID of the custom category. * `name` (_string_) The name of the custom category. ### count The number of results returned in the current result set. Type: `number (integer)`. ### page The current page number of results. Type: `number (integer)`. ### pageSize The maximum number of items included in the current page of results. Type: `number (integer)`. ### getLocationResponseBody Includes all fields of `id`, `locationObject`.