Push Overview

Create campaigns and send personalized push notifications to individual users or segments across Android, iOS, and Web.

The MoEngage Push API allows you to trigger push notifications. It is designed for high-throughput transactional and marketing use cases, supporting complex targeting logic and deep personalization for every recipient.

Ensure you select the API that corresponds to your specific use case:

• Transactional: For system-triggered events (for example, OTPs, status updates), use the Push API.
• Non-Transactional: For marketing, promotions, and broadcast messages, MoEngage highly recommends you use the Push Campaigns API.

Use this API to:

• Target Segments: Send notifications to all users or specific pre-defined segments.
• Target Individuals: Reach a single user using unique attributes like Email, Mobile Number, or Unique ID.
• Personalize at Scale: Use Jinja templating to dynamically inject user-specific data into the notification payload.
• Reach Every Platform: Send to Android, iOS, and Web from a single request.

Send a notification with Push API (V5), which creates the campaign for you — you do not need to create one on the dashboard first.

API Versions

Version	Endpoint	Status	Summary
V5	Push API (V5)	Supported	POST https://api-{dc}.moengage.com/v5/push/notifications. Credentials go in the Authorization header, and an X-MOE-Query-Type header matching targetAudience is required. Request fields are camelCase, and responses use the {response_id, type, data} envelope with standard HTTP status codes.
v2.1	Push API (v2.1, Legacy)	Stops working after 30 November 2026	POST https://pushapi-{dc}.moengage.com/v2.1/transaction/sendpush. Sends appId and signature as the X-MOE-APPKEY and X-MOE-PushAPI-Signature headers, plus an X-MOE-Query-Type header matching targetAudience.
v2	Push API (v2, Legacy)	Stops working after 30 November 2026	POST https://pushapi-{dc}.moengage.com/transaction/sendpush. The original version, with appId and signature as request-body fields. Available on request only.

The v2.1 and v2 endpoints are deprecated as of 30 October 2026 and stop working after 30 November 2026. They are no longer maintained. Move every integration to Push API (V5) before then.

Authentication

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.

Refer to API Key Dashboard for details on creating and managing API keys.

For rotating and revoking keys, refer to Rotate API Keys and Secure API Access.

Audience Types

targetAudience determines who receives the notification and how campaignName is treated. Send the matching value in the X-MOE-Query-Type header, case-insensitive.

targetAudience	X-MOE-Query-Type	Campaign behavior	campaignDelivery.type
User	user, or bulk users when bulkUserRequest is true	The campaign is reused across calls that pass the same campaignName.	Always sent immediately.
Custom Segment	custom segment	A new campaign is created on every call, so campaignName must be unique.	soon, later, or periodic. Defaults to soon.
All Users	all users	A new campaign is created on every call, so campaignName must be unique.	soon, later, or periodic. Defaults to soon.

Some workspaces are enabled only for User audiences. In those workspaces, a request that targets Custom Segment or All Users returns a 403. To send to these audiences, contact your Customer Success Manager (CSM) or MoEngage Support.

IP Whitelisting

IP whitelisting is optional, and MoEngage recommends configuring it.

Postman Collection

We have made it easy for you to test the APIs:

• Push API (V5) — Send the example payloads directly from Push API (V5).
• Push API (v2.1, Legacy) collection
• Push API (v2, Legacy) collection

FAQs

Does the Push API support silent notifications?

Yes, on iOS. Set payload.IOS.contentAvailable to 1 to send a silent background update.

Can I use HTML to format notification text?

Yes, the basic template supports standard HTML tags for text formatting on supported platforms.

What happens if personalization fails for a specific user?

Add a fallback object inside the platform payload. If the personalization logic fails, for example because a user attribute is missing, MoEngage sends the fallback content instead.

How do I target a user using their device token directly?

Set targetUserAttributes.attribute to PUSH_ID and pass the device token in targetUserAttributes.attributeValue.

What is the difference between request_id and response_id?

request_id is the trace ID you send as requestId in the request body. It is echoed back in data.request_id. response_id identifies the response itself. Quote response_id when you contact MoEngage Support.

Which status code means the notification was accepted?

A 201 means the notification was accepted for sending. Any other status code is an error, with the reason in error.code and error.message.

Can I throttle delivery by both RPM and time?

If you set both advancedSettings.campaignThrottleRpm and advancedSettings.campaignThrottleTime, campaignThrottleRpm takes precedence. A throttle value outside your workspace limits returns a 422.

Do I need IP whitelisting to use the Push API?

No. It is optional, but MoEngage recommends configuring it so that only your approved servers can reach your workspace. See IP Whitelisting.