MoEngage Push API
Send transactional and targeted push notifications to Android, iOS, and Web devices, and create push campaigns targeting all users or a group of users. Served from a dedicated push host.
OpenAPI Specification
openapi: 3.0.3
info:
title: MoEngage Push API
version: '2.0'
description: |
# Overview
Push API is used to:
* Create campaigns (targeting all users or a group of users) to send notifications.
* Target a single user using a unique user attribute.
* Personalize payload for each user.
tags:
- name: Transactional
description: Operations to create and send push notification campaigns.
servers:
- url: 'https://pushapi-{dc}.moengage.com/v2'
description: MoEngage Push API Server
variables:
dc:
default: '01'
description: "The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number and replace the value of ‘dc’ in the URL by referring to the DC and API endpoint mapping [here](/api/introduction#data-centers). Your MoEngage Data Center (DC) can be 01, 02, 03, 04, 05, 06, or 101."
paths:
/transaction/sendpush:
post:
tags:
- Transactional
summary: Send Push Notification
description: |
This API creates and sends a push notification campaign. You can use this API to create campaigns (targeting all users or a group of users) to send notifications, target a single user using a unique user attribute, and personalize payload for each user.
#### Rate Limit
The rate limit is 10,000 requests per minute.
#### Migrating to v2.1
This version does not use a separate query-type header — MoEngage resolves the request category directly from the `targetAudience` field in the request body. The [v2.1 endpoint](/api/push/push-api) introduces the `X-MOE-Query-Type` header as an explicit equivalent, sent alongside `targetAudience` rather than in place of it. No action is required if you continue using this version.
x-mint:
content: |
#### Authentication
A signature is required to verify whether the client is authorized to make the API call. It is generated from a hash of the campaign name, app ID, and API key. MoEngage uses the SHA 256 method to generate this hash. Python code is used to generate the signature for your test account, and use your account's app_id.
1. On the left navigation menu in the MoEngage dashboard, go to **Settings** > **Account** > **APIs**.
2. Copy the following details:
* **app_id**: Under **Workspace ID (earlier app_id)**, click the copy icon to copy the app-id.
* **api_key**: In the **API keys** section, click the copy icon in the **Push** tile to copy the API key.
* **campaign_name**: Ensure the campaign name matches the one used in the request body.
### Generating Signature
Python code to generate the signature for your test account, use the app_id that is appropriate for your account.
<Tabs>
<Tab title="Python 3.XX">
```python
from hashlib import sha256
app_id = "{{Your Workspace ID}}"
campaign_name = "{{your campaign name}}"
api_key = "{{your push api key}}"
signature_key = app_id+'|'+ campaign_name+'|'+ api_key
signature = sha256(signature_key.encode('utf-8')).hexdigest()
print(signature)
```
</Tab>
<Tab title="Python 2.XX">
```python
from hashlib import sha256
app_id = "{{Your Workspace ID}}"
campaign_name = "{{your campaign name}}"
api_key = "{{your push api key}}"
signature_key = app_id+'|'+ campaign_name+'|'+ api_key
signature = sha256(signature_key).hexdigest()
print(signature)
```
</Tab>
</Tabs>
requestBody:
required: true
description: "The complete configuration for the push campaign."
content:
application/json:
schema:
$ref: '#/components/schemas/PushRequest'
examples:
Base Sample Request:
summary: 1. Base Sample Request
value:
appId: "{{your Workspace ID}}"
campaignName: "{{your campaign name}}"
signature: "{{Signature}}"
requestType: "push"
targetPlatform: ["ANDROID"]
targetAudience: "User"
targetUserAttributes:
attribute: "USER_ATTRIBUTE_USER_EMAIL"
comparisonParameter: "is"
attributeValue: "abc@example.com"
payload:
ANDROID:
message: "message"
title: "title"
campaignDelivery:
type: "soon"
Android App:
summary: 2. Ex 1 - Android App
value:
appId: "{{appId}}"
campaignName: "{{campaignName}}"
signature: "{{signature}}"
targetPlatform: ["ANDROID"]
targetAudience: "User"
targetUserAttributes:
attribute: "USER_ATTRIBUTE_UNIQUE_ID"
comparisonParameter: "is"
attributeValue: "123"
campaignDelivery:
type: "soon"
payload:
ANDROID:
message: "Message"
title: "Title"
channel_id: "ChannelId"
richContent:
- type: "image"
value: "https://images.iimg.in/c"
- type: "coupon"
value: "free"
- type: "sound"
value: "notification_tone.wav"
defaultAction:
type: "richlanding"
value: "https://www.google.co.in/webhp"
kvPairs:
key1: "value1"
Key2: "value2"
additionalActions:
- type: "call"
value: "{{phone_number}}"
name: "Call button"
iconURL: "{{call_icon_url}}"
- type: "copy"
value: "{{phone_number}}"
name: "Copy button"
iconURL: "{{copy_icon_url}}"
fallback: {}
iOS App:
summary: 3. Ex 1 - iOS App
value:
appId: "{{appId}}"
campaignName: "{{campaignName}}"
signature: "{{signature}}"
targetPlatform: ["IOS"]
targetAudience: "User"
targetUserAttributes:
attribute: "USER_ATTRIBUTE_UNIQUE_ID"
comparisonParameter: "is"
attributeValue: "123"
campaignDelivery:
type: "soon"
payload:
IOS:
message: "Message"
title: "Tittle"
subtitle: "Subtitle"
enableIosBadge: true
richContent:
- type: "sound"
value: "custSound4.wav"
- type: "coupon"
value: "free"
- type: "image"
value: "product_image.jpg"
additionalActions:
- category: "INVITE_CATEGORY"
defaultAction:
type: "navigation"
value: ""
kvPairs:
key1: "value1"
Key2: "value2"
fallback:
message: "fallback ios"
title: "title"
richContent:
- type: "coupon"
value: "iOS"
additionalActions:
- category: "INVITE_CATEGORY"
Web Chrome:
summary: 4. Ex 1 - Web (Chrome)
value:
appId: "{{appId}}"
campaignName: "{{campaignName}}"
signature: "{{signature}}"
targetPlatform: ["WEB"]
targetAudience: "User"
targetUserAttributes:
attribute: "USER_ATTRIBUTE_UNIQUE_ID"
comparisonParameter: "is"
attributeValue: "123"
campaignDelivery:
type: "soon"
payload:
WEB:
message: "Message"
title: "Title"
redirectURL: "https://www.google.com"
iconURL: "https://app.moengage.com/v3/images/favicon.ico"
imageURL: "https://cdn.dribbble.com/users/146881/screenshots/1180383/despicable_me_1x.jpg"
Target All Android:
summary: 5. Ex 2 - Target All (Android)
value:
appId: "{{your Workspace ID}}"
campaignName: "Test Push"
campaignTags: ["Transactional"]
signature: "{{Signature}}"
requestType: "push"
targetPlatform: ["ANDROID"]
targetAudience: "All Users"
payload:
ANDROID:
message: "Android Message"
title: "Android Message Title"
summary: "Android Summary"
richContent:
- type: "image"
value: "https://images.iimg.in/c"
- type: "coupon"
value: "free"
- type: "sound"
value: "notification_tone.wav"
defaultAction:
type: "richlanding"
value: "https://www.google.co.in/webhp"
additionalActions:
- type: "call"
value: "{{phone_number}}"
name: "Call button"
iconURL: "{{call_icon_url}}"
- type: "copy"
value: "{{phone_number}}"
name: "Copy button"
iconURL: "{{copy_icon_url}}"
campaignDelivery:
type: "soon"
conversionGoals:
- name: "amount 1"
eventName: "AddedTocart"
attrs:
filter: "is between"
name: "amount"
value: "10,100"
type: "numeric"
advancedSettings:
ttl:
ANDROID: 12
ignoreFC: "false"
sendAtHighPriority: "true"
inboxExpiry: 360
Target All iOS:
summary: 6. Ex 2 - Target All (iOS)
value:
appId: "{{your Workspace ID}}"
campaignName: "Test Push"
campaignTags: ["Promotional"]
signature: "{{Signature}}"
requestType: "push"
targetPlatform: ["IOS"]
targetAudience: "All Users"
payload:
IOS:
message: "iOS Message"
title: "iOS Message Title"
richContent:
- type: "sound"
value: "custSound4.wav"
additionalActions:
- category: "INVITE_CATEGORY"
campaignDelivery:
type: "soon"
conversionGoals:
- name: "amount 1"
eventName: "AddedTocart"
attrs:
filter: "is between"
name: "amount"
value: "10,100"
type: "numeric"
advancedSettings:
ignoreFC: "false"
inboxExpiry: 360
Target All Web:
summary: 7. Ex 2 - Target All (Web)
value:
appId: "{{your Workspace ID}}"
campaignName: "Test Push"
signature: "{{Signature}}"
requestType: "push"
targetPlatform: ["WEB"]
targetAudience: "All Users"
payload:
WEB:
message: "Web Message"
title: "Web Message Title"
redirectURL: "https://www.google.com"
iconURL: "https://app.moengage.com/v3/images/favicon.ico"
imageURL: "https://cdn.dribbble.com/users/146881/screenshots/1180383/despicable_me_1x.jpg"
campaignDelivery:
type: "soon"
conversionGoals:
- name: "amount 1"
eventName: "AddedTocart"
attrs:
filter: "is between"
name: "amount"
value: "10,100"
type: "numeric"
advancedSettings:
ttl:
WEB: 24
ignoreFC: "false"
sendAtHighPriority: "true"
All Platforms:
summary: 8. Ex 2 - All Platforms
value:
appId: "{{your Workspace ID}}"
campaignName: "Test Push"
signature: "{{Signature}}"
requestType: "push"
targetPlatform: ["ANDROID", "IOS", "WEB"]
targetAudience: "All Users"
payload:
ANDROID:
message: "Android Message"
title: "Android Message Title"
Summary: "summary"
richContent:
- type: "image"
value: "https://images.iimg.in/c"
- type: "coupon"
value: "free"
- type: "sound"
value: "notification_tone.wav"
defaultAction:
type: "richlanding"
value: "https://www.google.co.in/webhp"
additionalActions:
- type: "call"
value: "{{phone_number}}"
name: "Call button"
iconURL: "{{call_icon_url}}"
- type: "copy"
value: "{{phone_number}}"
name: "Copy button"
iconURL: "{{copy_icon_url}}"
IOS:
message: "iOS Message"
title: "iOS Message Tittle"
richContent:
- type: "sound"
value: "custSound4.wav"
additionalActions:
- category: "INVITE_CATEGORY"
WEB:
message: "Web Message"
title: "Web Message Title"
redirectURL: "https://www.google.com"
iconURL: "https://app.moengage.com/v3/images/favicon.ico"
imageURL: "https://cdn.dribbble.com/users/146881/screenshots/1180383/despicable_me_1x.jpg"
campaignDelivery:
type: "soon"
conversionGoals:
- name: "amount 1"
eventName: "AddedTocart"
attrs:
filter: "is between"
name: "amount"
value: "10,100"
type: "numeric"
advancedSettings:
ttl:
ANDROID: 12
WEB: 24
ignoreFC: "false"
sendAtHighPriority: "true"
inboxExpiry: 360
Target Single User:
summary: 9. Ex 3 - Target Single User
value:
appId: "{{your Workspace ID}}"
campaignName: "Test Push"
signature: "{{Signature}}"
requestType: "push"
targetPlatform: ["ANDROID"]
targetAudience: "User"
targetUserAttributes:
attribute: "USER_ATTRIBUTE_USER_EMAIL"
comparisonParameter: "is"
attributeValue: "abc@example.com"
payload:
ANDROID:
message: "Android Message"
title: "Android Message Title"
summary: "Android Summary"
richContent:
- type: "image"
value: "https://images.iimg.in/c"
- type: "coupon"
value: "free"
- type: "sound"
value: "notification_tone.wav"
defaultAction:
type: "richlanding"
value: "https://www.google.co.in/webhp"
additionalActions:
- type: "call"
value: "{{phone_number}}"
name: "Call button"
iconURL: "{{call_icon_url}}"
- type: "copy"
value: "{{phone_number}}"
name: "Copy button"
iconURL: "{{copy_icon_url}}"
campaignDelivery:
type: "soon"
conversionGoals:
- name: "amount 1"
eventName: "AddedTocart"
attrs:
filter: "is between"
name: "amount"
value: "10,100"
type: "numeric"
advancedSettings:
ttl:
ANDROID: 12
ignoreFC: "false"
sendAtHighPriority: "true"
inboxExpiry: 360
Custom Segment:
summary: 10. Ex 3 - Custom Segment
value:
appId: "{{your Workspace ID}}"
campaignName: "Test Push"
signature: "{{Signature}}"
requestType: "push"
targetPlatform: ["ANDROID", "IOS", "WEB"]
targetAudience: "Custom Segment"
customSegmentName: "Android_TranV2"
payload:
ANDROID:
message: "testing txn v2"
title: "testing txn v2"
Summary: "summary"
richContent:
- type: "image"
value: "https://images.iimg.in/c"
- type: "coupon"
value: "free"
- type: "sound"
value: "notification_tone.wav"
defaultAction:
type: "richlanding"
value: "https://www.google.co.in/webhp"
additionalActions:
- type: "call"
value: "{{phone_number}}"
name: "Call button"
iconURL: "{{call_icon_url}}"
- type: "copy"
value: "{{phone_number}}"
name: "Copy button"
iconURL: "{{copy_icon_url}}"
IOS:
message: "7th"
title: "Test Case custom segment5"
richContent:
- type: "sound"
value: "custSound4.wav"
additionalActions:
- category: "INVITE_CATEGORY"
WEB:
message: "Test Case WEB"
title: "Test Case WEB"
redirectURL: "https://www.google.com"
iconURL: "https://app.moengage.com/v3/images/favicon.ico"
imageURL: "https://cdn.dribbble.com/users/146881/screenshots/1180383/despicable_me_1x.jpg"
campaignDelivery:
type: "soon"
conversionGoals:
- name: "amount 1"
eventName: "AddedTocart"
attrs:
filter: "is between"
name: "amount"
value: "10,100"
type: "numeric"
advancedSettings:
ttl:
ANDROID: 12
WEB: 24
ignoreFC: "false"
sendAtHighPriority: "true"
inboxExpiry: 360
Custom Attribute:
summary: 11. Ex 3 - Custom Attribute
value:
appId: "{{your Workspace ID}}"
campaignName: "Test Push"
signature: "{{Signature}}"
requestType: "push"
targetPlatform: ["ANDROID"]
targetAudience: "User"
targetUserAttributes:
attribute: "user"
comparisonParameter: "is"
attributeValue: "user"
isCustom: true
payload:
ANDROID:
message: "Android Message"
title: "Android Message Title"
summary: "Android Summary"
richContent:
- type: "image"
value: "https://images.iimg.in/c"
- type: "coupon"
value: "free"
- type: "sound"
value: "notification_tone.wav"
defaultAction:
type: "richlanding"
value: "https://www.google.co.in/webhp"
additionalActions:
- type: "call"
value: "{{phone_number}}"
name: "Call button"
iconURL: "{{call_icon_url}}"
- type: "copy"
value: "{{phone_number}}"
name: "Copy button"
iconURL: "{{copy_icon_url}}"
campaignDelivery:
type: "soon"
conversionGoals:
- name: "amount 1"
eventName: "AddedTocart"
attrs:
filter: "is between"
name: "amount"
value: "10,100"
type: "numeric"
advancedSettings:
ttl:
ANDROID: 12
ignoreFC: "false"
sendAtHighPriority: "true"
inboxExpiry: 360
All Users Detailed:
summary: 12. Ex 3 - All Users (Detailed)
value:
appId: "{{your Workspace ID}}"
campaignName: "Test Push"
signature: "{{Signature}}"
requestType: "push"
targetPlatform: ["ANDROID", "IOS", "WEB"]
targetAudience: "All Users"
payload:
ANDROID:
message: "gp 7th nov"
title: "7th nov"
richContent:
- type: "image"
value: "https://images.iimg.in/c"
- type: "coupon"
value: "free"
- type: "sound"
value: "notification_tone.wav"
defaultAction:
type: "richlanding"
value: "https://www.google.co.in/webhp"
additionalActions:
- type: "call"
value: "{{phone_number}}"
name: "Call button"
iconURL: "{{call_icon_url}}"
- type: "copy"
value: "{{phone_number}}"
name: "Copy button"
iconURL: "{{copy_icon_url}}"
IOS:
message: "7th"
title: "Test Case custom segment5"
richContent:
- type: "sound"
value: "custSound4.wav"
additionalActions:
- category: "INVITE_CATEGORY"
WEB:
message: "Test Case WEB"
title: "Test Case WEB"
redirectURL: "https://www.google.com"
iconURL: "https://app.moengage.com/v3/images/favicon.ico"
imageURL: "https://cdn.dribbble.com/users/146881/screenshots/1180383/despicable_me_1x.jpg"
campaignDelivery:
type: "soon"
conversionGoals:
- name: "amount 1"
eventName: "AddedTocart"
attrs:
filter: "is between"
name: "amount"
value: "10,100"
type: "numeric"
advancedSettings:
ttl:
ANDROID: 12
WEB: 24
ignoreFC: "false"
sendAtHighPriority: "true"
inboxExpiry: 360
responses:
'200':
description: |
Request received. The status in the response body indicates whether it was successfully processed or failed.
Possible failures include:
* Invalid Request Type
* Invalid appId / appId not present
* Campaign Name too short (must be >= 5 chars) / Campaign name missing
* Request limit exceeded
* Signature missing or not verified
* Duplicate campaign name
* Key not of Type List or Value not allowed
* Error parsing parameters
**Response fields:**
* `status`: `Success` or `Fail`, indicating whether the campaign was accepted.
* `requestId`: The request ID you sent, echoed back (empty on failure).
* `responseId`: A unique ID MoEngage generates for this response.
* `cid`: The campaign ID (present on success only).
* `Error_Message`: A human-readable failure reason (present on failure only).
This response envelope (`status`, `requestId`, `responseId`, `cid`) predates MoEngage's newer API conventions (for example, the `{response_id, type, data}` shape used by the Analytics Custom Dashboards API) and is kept as-is here for backward compatibility.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/PushSuccessResponse'
- $ref: '#/components/schemas/PushFailureResponse'
examples:
Success:
summary: Success Response
value:
status: Success
requestId: "09562729-236b-4773-8207-63321523456"
responseId: "09562729-236b-4773-8207-63321523456"
cid: "66321523456"
Failure:
summary: Failure Response (200 OK)
value:
status: Fail
Error_Message: Campaign Name not found
responseId: "09562729-236b-4773-8207-63321523456"
requestId: ""
'401':
description: Unauthorized. Invalid authentication credentials or JSON format.
content:
application/json:
example: []
'404':
description: Not Found. Invalid endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
example:
code: 404
status: error
reason: "Page not found. Please recheck the URL"
'500':
description: Internal Server Error.
content:
application/json:
example:
code: 500
status: error
reason: "There seems to be an error. We are working to fix this."
reference: "reference"
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: |
Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'.
- **Username**: Use your MoEngage workspace ID (also known as the App ID). You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**.
- **Password**: Use your API Key, which you can find within the **Push** tile.
For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).
apiKeyAuth:
type: apiKey
in: header
name: MOE-APPKEY
description: This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**.
schemas:
TargetUserAttributes:
type: object
properties:
attribute:
type: string
description: |
This field denotes a unique identifier or characteristic of an entity or object used to specify the target users. This value is required when the targetAudience value is User. Other fields used are:
* for unique ID: USER_ATTRIBUTE_UNIQUE_ID
* for email: USER_ATTRIBUTE_USER_EMAIL
* For mobile number: USER_ATTRIBUTE_USER_MOBILE
* for Google Advertising identifier: MOE_GAID
* for iOS Identifier for advertising: ADVERTISING_IDENTIFIER
* for device push token: PUSH_ID (the same key is used for Android GCM ID, iOS push token)
For more information, refer to [Target User Attributes](/hc/en-us/articles/32986034181268#h_01JGZQ07FC9P3RHKXYJ67AJ9QV).
enum: [USER_ATTRIBUTE_UNIQUE_ID, USER_ATTRIBUTE_USER_EMAIL, USER_ATTRIBUTE_USER_MOBILE, MOE_GAID, ADVERTISING_IDENTIFIER, PUSH_ID]
comparisonParameter:
type: string
description: |
This field denotes a condition or operator that compares the user attributes against a specific value. Supported values are:
* The "is" query type
* The "in" query type
* Note: The maximum number of parameters that can be added while using the "in" comparisonParameter is 50. This value is required when the targetAudience value is User.
enum: [is, in]
attributeValue:
oneOf:
- type: string
- type: array
items:
type: string
description: "This field denotes the actual value assigned to an attribute, which is use
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/moengage/refs/heads/main/openapi/moengage-push-openapi.yml