MoEngage Transactional API

openapi: 3.2.0
info:
  title: Moengage Transactional API
  version: '1.0'
  description: 'Operations tagged Transactional across 2 of this provider''s published API definitions: moengage-push-openapi.yml, moengage-push-v2-1-openapi.yml. Each path carries the servers of the definition it was published in.'
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.
- url: https://pushapi-{dc}.moengage.com
  description: MoEngage Push API Server
  variables:
    dc:
      default: '01'
      enum:
      - '01'
      - '02'
      - '03'
      - '04'
      - '05'
      - '06'
      - '101'
      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.
tags:
- name: Transactional
  description: Operations to create and send push notification campaigns.
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: "\n#### Authentication\n\nA 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.\n\n1. On the left navigation menu in the MoEngage dashboard, go to **Settings** > **Account** > **APIs**.\n2. Copy the following details:\n* **app_id**: Under **Workspace ID (earlier app_id)**, click the copy icon to copy the app-id.\n* **api_key**: In the **API keys** section, click the copy icon in the **Push** tile to copy the API key.\n* **campaign_name**: Ensure the campaign name matches the one used in the request body. \n\n### Generating Signature\n\nPython code to generate the signature for your test account, use the app_id that is appropriate for your account.\n\n <Tabs>\n <Tab title=\"Python 3.XX\">\n ```python\n from hashlib import sha256\n app_id = \"{{Your Workspace ID}}\"\n campaign_name = \"{{your campaign name}}\"\n api_key = \"{{your push api key}}\"\n signature_key = app_id+'|'+ campaign_name+'|'+ api_key\n signature = sha256(signature_key.encode('utf-8')).hexdigest()\n print(signature)\n ```\n </Tab>\n <Tab title=\"Python 2.XX\">\n ```python\n from hashlib import sha256 \n app_id = \"{{Your Workspace ID}}\" \n campaign_name = \"{{your campaign name}}\" \n api_key = \"{{your push api key}}\" \n signature_key = app_id+'|'+ campaign_name+'|'+ api_key \n signature = sha256(signature_key).hexdigest() \n print(signature)\n ```\n </Tab>\n </Tabs>   \n \n"
      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
    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.
  /v2.1/transaction/sendpush:
    post:
      operationId: send_push_v2_1
      tags:
      - Transactional
      summary: Send Push Notification (V2.1)
      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.


        This endpoint accepts three request headers: `X-MOE-APPKEY` (your Workspace ID), `X-MOE-PushAPI-Signature` (the authorization signature), and `X-MOE-Query-Type` (the target audience, corresponding to the `targetAudience` field in the request body).


        #### Rate Limit


        The rate limit is 10,000 requests per minute.

        '
      parameters:
      - $ref: '#/components/parameters/XMoeAppKey'
      - $ref: '#/components/parameters/XMoePushSignature'
      - $ref: '#/components/parameters/XMoeQueryType'
      x-mint:
        content: '

          #### Rate Limiting (429 Responses)


          When the per-`app_key` rate limit for the resolved `X-MOE-Query-Type` category is exceeded, the request is rejected with HTTP `429` and an empty response body. The category is resolved as `seg_user_search` for `user`, and `seg_user_query` for `all users` and `custom segment`. The rate-limit details are returned in the following response headers:


          | Header | Description | Example |

          | :--- | :--- | :--- |

          | `x-envoy-ratelimited` | Present and set to `true` when the request was rate limited. | `true` |

          | `x-ratelimit-limit` | The configured limit for the resolved category. | `5, 5;w=60` |

          | `x-ratelimit-remaining` | Requests remaining in the current window (`0` when throttled). | `0` |

          | `x-ratelimit-reset` | Seconds until the current rate-limit window resets. | `23` |

          '
      requestBody:
        required: true
        description: The complete configuration for the push campaign.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushRequest_2'
            examples:
              Base Sample Request:
                summary: Base Sample Request
                value:
                  campaignName: '{{your campaign name}}'
                  requestType: push
                  targetPlatform:
                  - ANDROID
                  targetAudience: User
                  targetUserAttributes:
                   

# --- truncated at 32 KB (120 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/moengage/refs/heads/main/openapi/moengage-transactional-api-openapi.yml