MoEngage Inform API
Unified transactional messaging infrastructure for building and managing transactional alerts across SMS, Email, and Push from a single send endpoint. Publishes a dedicated sandbox host alongside the production host.
OpenAPI Specification
openapi: 3.0.3
info:
title: MoEngage Inform API
version: '1.0'
description: |-
API for MoEngage Inform, a unified messaging infrastructure for building and managing transactional alerts across multiple channels like SMS, Email, and Push.
tags:
- name: Transactional Alerts
description: Send transactional alerts using pre-configured templates.
servers:
- url: 'https://api-{dc}.moengage.com/v1.0'
description: Live Alerts Endpoint
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.'
- url: 'https://sandbox-api-{dc}.moengage.com/v1.0'
description: Test/Sandbox Alerts Endpoint
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:
/alerts/send:
post:
tags:
- Transactional Alerts
summary: Send Transactional Alert
description: "This API is used to trigger a transactional message/alert to the user via one or more configured channels."
x-mint:
content: |
#### Rate Limit
The default rate limit is 10K RPM.
security:
- basicAuth: []
moeAppKey: []
requestBody:
required: true
description: The payload containing the alert identifier, transaction details, and recipient information for each channel.
content:
application/json:
schema:
$ref: '#/components/schemas/InformRequest'
examples:
singleChannelWithoutPersonalization:
summary: Single Channel (SMS) without Personalization
value:
alert_id: "636b77e6e2cf83277195fb60"
alert_reference_name: "Demo_ID"
user_id: "USER_12345"
transaction_id: "TXN_ABCDEF123"
payloads:
SMS:
recipient: "1234567890"
multichannelWithoutPersonalization:
summary: Multichannel Without Personalization
value:
alert_id: "636b77e6e2cf83277195fb60"
alert_reference_name: "Demo_ID"
user_id: "USER_ID"
transaction_id: "YOUR_TRANSACTION_ID_VAL_HERE"
payloads:
PUSH:
recipient: "<push-token>"
EMAIL:
recipient: "john.doe@moengage.com"
singleChannelWithPersonalization:
summary: Single Channel With Personalization (SMS)
value:
alert_id: "636b77e6e2cf83277195fb60"
alert_reference_name: "Demo_ID"
user_id: "USER_ID"
transaction_id: "YOUR_TRANSACTION_ID_VAL_HERE"
payloads:
SMS:
recipient: "123456789"
personalized_attributes:
firstname: "YOUR_firstname_ATTRIBUTE_VAL_HERE"
orderid: "YOUR_orderid_ATTRIBUTE_VAL_HERE"
deliverydate: "YOUR_deliverydate_ATTRIBUTE_VAL_HERE"
deliveryslot_starttime: "YOUR_deliveryslot_starttime_ATTRIBUTE_VAL_HERE"
deliveryslot_endtime: "YOUR_deliveryslot_endtime_ATTRIBUTE_VAL_HERE"
multiChannelWithPersonalization:
summary: Multi-Channel with Personalization
value:
alert_id: "636b77e6e2cf83277195fb60"
alert_reference_name: "Demo_ID"
user_id: "USER_12345"
transaction_id: "TXN_987654321"
payloads:
PUSH:
recipient: "<push-token>"
personalized_attributes:
firstname: "John"
orderid: "ORD_554433"
EMAIL:
recipient: "john.doe@moengage.com"
personalized_attributes:
firstname: "John"
orderid: "ORD_554433"
liveActivity:
summary: iOS Live Activity (PUSH)
value:
alert_id: "696737255def18872642f9d2"
alert_reference_name: "Live Activity Only Test"
user_id: "USER_ID"
transaction_id: "YOUR_TRANSACTION_ID_VAL_HERE"
payloads:
PUSH:
recipient: "<push-token>"
personalized_attributes:
stale_date: "YOUR_stale_date_VAL_HERE"
dismissal_date: "YOUR_dismissal_date_VAL_HERE"
live_activity_attributes:
la_type: "start"
attribute_info:
order_id: "ORD_554433"
content_state:
delivery_status: "Out for delivery"
eta_minutes: 12
responses:
'200':
description: |
Request has been received and processed. The response body contains the status for the overall request and for each individual channel.
**Note**: Reach out to your Customer Success Manager to enable sending the channel level details as part of your API response.
content:
application/json:
schema:
$ref: '#/components/schemas/InformSuccessResponse'
'400':
description: Bad Request. Invalid payload format, incorrect JSON, or invalid Alert ID.
content:
application/json:
schema:
$ref: '#/components/schemas/InformErrorResponse'
example:
message: "Invalid Alert ID"
err_code: "BAD_REQUEST"
status_code: 120002
'401':
description: Unauthorized. Invalid authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/InformErrorResponse'
example:
message: "Invalid App Key or Basic Auth"
err_code: "UNAUTHORIZED"
status_code: 120001
'409':
description: Duplicate Request. A request with the same `transaction_id` was received within 5 minutes of a previously successful or in-progress request.
content:
application/json:
schema:
$ref: '#/components/schemas/InformErrorResponse'
example:
message: "Duplicate Transaction ID"
err_code: "DUPLICATE_REQUEST_RECEIVED"
status_code: 120105
'429':
description: Rate Limit Reached. The number of requests per minute has exceeded the rate limit.
content:
application/json:
schema:
$ref: '#/components/schemas/InformErrorResponse'
example:
message: "Too many requests"
err_code: "Rate Limit"
status_code: 140110
'500':
description: Internal Server Error. The system ran into an unexpected error. You can retry the request up to 3 times with exponential backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/InformErrorResponse'
example:
message: "Unexpected error occurred"
err_code: "Internal Server Error"
status_code: 140109
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 **Inform** tile.
**Note**: After you generate and save the Inform API Key (SECRET KEY), DO NOT generate a new key unless there is a security breach. After you generate a different key and save it, API calls using the older key won't work.
For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).
moeAppKey:
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:
PayloadChannel:
type: object
required:
- recipient
properties:
recipient:
type: string
description: 'The target for the notification. This should be a mobile number for SMS, an email address for EMAIL, or a push token for PUSH.'
personalized_attributes:
type: object
additionalProperties: true
description: |
Key-value map for personalization. Personalization attributes are sent by the brand when invoking the Inform API and are used to resolve the content of the message.
For iOS Live Activities (PUSH channel), the following keys are also recognized here:
- `stale_date`: Timestamp at which the system considers the activity outdated.
- `dismissal_date`: Timestamp at which the system automatically removes the activity from the user's screen.
sender_attributes:
type: array
items:
type: string
description: A list of API attributes for evaluating which sender to use. If not passed, the alert will not be sent out.
personalized_attachments:
type: object
additionalProperties:
type: string
format: byte
description: 'A map where keys are attachment identifiers (defined in the template) and values are Base64-encoded strings of the attachment content.'
live_activity_attributes:
type: object
description: |
List of attributes used to manage the lifecycle, static data, and dynamic state of an iOS Live Activity. Applicable to the `PUSH` channel only.
Live Activities are supported starting from MoEngage SDK version `10.09.0`.
properties:
la_type:
type: string
enum:
- start
- update
- end
description: 'The lifecycle stage of the activity: `start` (initiate), `update` (refresh content), or `end` (terminate).'
attribute_info:
type: object
additionalProperties: true
description: JSON object containing static data that remains constant throughout the activity (for example, Order ID or Flight Number).
content_state:
type: object
additionalProperties: true
description: JSON object containing the dynamic data that updates in real-time (for example, Delivery Status or ETA). Values can be set as key-value pairs using personalization tags to fetch values from the event.
InformRequest:
type: object
required:
- transaction_id
- payloads
properties:
alert_id:
type: string
description: This field uniquely identifies the Alert to be sent to the user. For the staging endpoint, use the test alert id and for the live endpoint, use the alert id. For more information, refer to [Live and Test Alerts](#live-vs-test-environments).
alert_reference_name:
type: string
description: This field is used to identify the Alert using your reference Name and can be used to identify the alert as an alternative to Alert ID.
user_id:
type: string
description: This is the unique user identifier information you maintain. This information should be passed in the request to facilitate the mapping of the channel events back to the user profile to which this user_id is associated in MoEngage.
transaction_id:
type: string
description: |
This is the unique identifier denoting the transaction for which the Alert is being sent to the user. This information is maintained by the brand and is passed in the request. The maximum length allowed for this field is 50 characters.
The Inform API supports idempotency using this parameter. If a request contains a `transaction_id` and is successful and another request with the same `transaction_id` is received within 5 minutes of the successful request, the new request would be deemed a duplicate one.
payloads:
type: object
description: The payload contains the following channel-level information for all the configured channels.
properties:
SMS:
$ref: '#/components/schemas/PayloadChannel'
EMAIL:
$ref: '#/components/schemas/PayloadChannel'
PUSH:
$ref: '#/components/schemas/PayloadChannel'
ChannelStatus:
type: object
properties:
message:
type: string
err_code:
type: string
status_code:
type: integer
InformSuccessResponse:
type: object
properties:
message:
type: string
example: "Successfully Received"
request_id:
type: string
SMS:
$ref: '#/components/schemas/ChannelStatus'
EMAIL:
$ref: '#/components/schemas/ChannelStatus'
PUSH:
$ref: '#/components/schemas/ChannelStatus'
# FIX: Removed hardcoded examples from here so the specific response examples take precedence
InformErrorResponse:
type: object
properties:
message:
type: string
err_code:
type: string
status_code:
type: integer