Push API (V5)

Creates a transactional push campaign and sends it to the selected audience.

Rate Limit

The rate limit is 10,000 requests per minute.

POST /v5/push/notifications

cURL

Base Request

curl --request POST \
  --url https://api-{dc}.moengage.com/v5/push/notifications \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'X-MOE-Query-Type: <x-moe-query-type>' \
  --data '
{
  "requestId": "req_7f3c2a90",
  "campaignName": "Order shipped",
  "targetPlatform": [
    "ANDROID"
  ],
  "targetAudience": "User",
  "targetUserAttributes": {
    "attribute": "USER_ATTRIBUTE_UNIQUE_ID",
    "comparisonParameter": "is",
    "attributeValue": "user-123"
  },
  "payload": {
    "ANDROID": {
      "title": "Order Shipped",
      "message": "Your order has shipped",
      "defaultAction": {
        "type": "deeplinking",
        "value": "myapp://orders/123"
      }
    }
  },
  "campaignDelivery": {
    "type": "soon"
  }
}
'

201

{
  "response_id": "resp_09562729-236b-4773-8207-633215234560",
  "type": "push_notification",
  "data": {
    "campaign_id": "camp_66321523456aa0e1c2b3d4e5",
    "request_id": "req_7f3c2a90"
  }
}

Authorizations

Authorization · string · header · required

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). Find it in the MoEngage dashboard at Settings > Account > API keys.
• Password: Use an API key from Settings > Account > API keys.

The Push API also supports OAuth 2.0 and AWS STS Auth. Refer to API Key Dashboard for the supported authentication types and for creating and managing keys.

Headers

X-MOE-Query-Type · string · required

This field denotes the target audience of the request and must match the targetAudience field in the request body, case-insensitive. Supported values are:

• all users
• custom segment
• user
• bulk users: Use this value instead of user when bulkUserRequest is true.

A missing value, or a value that does not match targetAudience, returns 400.

Example:

"user"

Body

application/json

campaignName · string · required

This field denotes the campaign name. The campaign name must be at least 5 characters long. Note:

• The API creates the campaign with this name. You do not need to create the campaign on the dashboard first.
• For All Users and Custom Segment audiences, the campaign name must be unique. A name that already exists returns 409.
• For User audiences, reuse the same campaign name across requests to group them into one campaign.

Minimum string length: 5

targetPlatform · enum<string>[] · required

This field denotes the platforms targeted by the campaign. You can target one or more platforms. Supported values are:

• ANDROID
• IOS
• WEB

Each platform you list here must have a matching block in payload.

Minimum array length: 1

Available options: ANDROID, IOS, WEB

targetAudience · enum<string> · required

This field denotes the target audience for the campaign. Send the same value, case-insensitive, in the X-MOE-Query-Type header. Supported values are:

• All Users: Targets all users of your app or website. A new campaign is created on every request.
• Custom Segment: Targets an existing custom segment, named in customSegmentName. A new campaign is created on every request. You can create custom segments on the MoEngage dashboard or with the Create Custom Segment API.
• User: Targets the users that match targetUserAttributes. The campaign is reused across requests that pass the same campaignName, and the notification is sent immediately.

Available options: All Users, Custom Segment, User

payload · object · required

This object contains the notification content for each platform. Supported values are:

• ANDROID
• IOS
• WEB

Include one block for each platform listed in targetPlatform.

Show child attributes

requestId · string

This field denotes a client-side trace ID for the request. MoEngage returns it in data.request_id in the response. Note:

• This field is required when bulkUserRequest is true.

requestType · enum<string> · default: push

This field denotes the intention of the API request. The only supported value is push, which is also the default.

Available options: push

campaignTags · string[]

This field denotes the list of campaign tags to add to the campaign. Tags add context to a campaign, such as its theme or purpose, and you can use them to filter campaigns on the dashboard. Note:

• Each tag must already exist in the workspace. Tag names that do not exist are ignored.
• A maximum of 5 tags is applied.

customSegmentName · string

This field denotes the name of the custom segment to target. The segment must exist and must not be archived. Note:

• This field is required when targetAudience is Custom Segment.

targetUserAttributes · object

This object contains the attributes used to identify the target users. Note:

• This object is required when targetAudience is User.

Show child attributes

bulkUserRequest · boolean

This field specifies whether to process a User request asynchronously, in bulk mode. Note:

• Bulk mode is honored only when it is enabled for the workspace.
• When this field is true, send bulk users in the X-MOE-Query-Type header and include requestId in the body.

campaignDelivery · object

This object contains the delivery schedule for the campaign. Note:

• When you do not send this object, the campaign is sent with the soon type.
• User requests are always sent immediately, whatever the delivery type.

Show child attributes

conversionGoals · object[]

This field denotes the list of conversion goals for the campaign. A conversion goal is an event that you want users to perform after they receive the notification. Note:

• The first valid goal in the list is the primary goal.
• A maximum of 5 goals is used.
• When you do not send this field, the conversion goal defaults to the MOE_APP_OPENED event.

Show child attributes

advancedSettings · object

This object contains the advanced delivery settings for the campaign. Note:

• Flags of type string take the values "true" and "false", in lowercase.
• When you send this object, ignoreMinimumDelay and bypassDND default to true.

Show child attributes

attributionWindow · integer · default: 36

This field denotes the attribution window, in hours, during which impressions and clicks are attributed to the campaign. Supported values are 0 to 36. The default value is 36.

Required range: 0 <= x <= 36

Response

201

application/json

Notification accepted for sending.

response_id · string · required

This field denotes the unique ID of the response. Quote this ID when you contact MoEngage Support.

type · enum<string> · required

This field denotes the type of resource returned. The value is always push_notification.

Available options: push_notification

data · object · required

This object contains the details of the created campaign.

Show child attributes