MoEngage

MoEngage OSM Templates API

Operations to manage On-Site Messaging (OSM) templates.

Documentation GitHub OpenAPI

Operations 3

POST /custom-templates/osm Create OSM Template

PUT /custom-templates/osm Update OSM Template

POST /custom-templates/osm/search Search OSM Templates

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/moengage-osm-templates-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: MoEngage On-Site Messaging (OSM) Template OSM Templates API
  version: '1.0'
  description: API for creating, updating, and searching On-Site Messaging (OSM) templates within the MoEngage platform.
servers:
- url: https://api-{dc}.moengage.com/v1.0
  description: MoEngage Custom Templates 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.
security:
- basicAuth: []
tags:
- name: OSM Templates
  description: Operations to manage On-Site Messaging (OSM) templates.
paths:
  /custom-templates/osm:
    post:
      tags:
      - OSM Templates
      summary: Create OSM Template
      description: This API creates a new On-Site Messaging (OSM) template. You can use this API to upload templates created outside the MoEngage ecosystem to MoEngage and use them for campaign creation.
      x-mint:
        content: '<Note>

          API templates cannot be used in the Drag and Drop Editor in the MoEngage Dashboard. They are only supported for the Custom HTML Editor.

          </Note>


          #### Rate Limit

          The rate limit is 100 RPM. You can upload a maximum of 100 templates per minute.

          '
      requestBody:
        required: true
        description: The details of the OSM template to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOsmTemplateRequest'
            example:
              basic_details:
                payload: <html><body><h1>Your HTML Content Here</h1></body></html>
                template_type: BANNER
              meta_info:
                created_by: testuser@moengage.com
                template_id: '123123123'
                template_name: Test
                template_version: '1'
      responses:
        '200':
          description: Template created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  external_template_id:
                    type: string
                    format: uuid
                    description: The unique ID assigned to the newly created template by MoEngage. This ID is used for subsequent updates or searches.
              example:
                external_template_id: d05a44f0-a7cf-471a-bcb6-63054800a367
        '400':
          description: Bad Request. Returned when required parameters are missing, invalid, or when a template already exists with the same version, name, or ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
              example:
                error:
                  code: 400 Bad Request
                  message: Duplicate - template_id and template_version
                  details:
                  - code: InvalidValue
                    target: Duplicate - template_id and template_version
                    message: template_id:13343440 template_version:1 is already present.
                  request_id: xZLmJvUi
        '401':
          description: Authentication Failure. Returned when authorization parameters are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
              example:
                title: Authentication required
                description: MOE-APPKEY missing in Authentication Header
        '415':
          description: Unsupported Media Type. Returned when the header Content-Type is not provided or is not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
              example:
                title: Unsupported media type
                description: Content type is not supported
        '429':
          description: Rate limit breached. Returned when requests per minute exceed the limit or template quota is exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
              example:
                response_id: OUUkHvcn
                type: custom_template
                error:
                  code: Too Many Requests
                  message: 'API rate limit breached. Current limit: n/m mins'
        5XX:
          description: Internal Server Error. Returned when the system runs into an unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
              example:
                title: Internal Server Error
                message: An unexpected error was encountered while processing this request. Please contact MoEngage Team
    put:
      tags:
      - OSM Templates
      summary: Update OSM Template
      description: This API updates an OSM template as per your requirements.
      x-mint:
        content: '#### Rate Limit

          The rate limit is 100 RPM.

          '
      requestBody:
        required: true
        description: The updated details for the OSM template.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOsmTemplateRequest'
            example:
              external_template_id: 81e1a740-3e57-4c70-8ec7-ffc84d576498
              update_campaigns: false
              basic_details:
                payload: <html><body><h1>Updated HTML Content</h1></body></html>
              meta_info:
                template_name: AD template updated API 1
                template_id: '133434477456'
                template_version: '2'
                updated_by: testuser@moengage.com
      responses:
        '200':
          description: Template updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  external_template_id:
                    type: string
                    format: uuid
                    description: The unique ID of the updated template.
              example:
                external_template_id: 4a1afbc5-4c31-4f19-8c23-793e27af01aa
        '400':
          description: Bad Request. Validation failed or missing parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
              example:
                error:
                  code: 400 Bad Request
                  message: Validation failed because of invalid request data
                  details:
                  - code: MissingValue
                    target: external_template_id
                    message: external_template_id value is required but value is passed empty.
                  request_id: cTRlnJaG
        5XX:
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
              example:
                title: Internal Server Error
                message: An unexpected error was encountered while processing this request. Please contact MoEngage Team
  /custom-templates/osm/search:
    post:
      tags:
      - OSM Templates
      summary: Search OSM Templates
      description: This API searches the OSM templates created in your MoEngage account.
      x-mint:
        content: '<Note>

          **Mandatory Pagination**

          We are introducing mandatory pagination, effective **November 15, 2025**. All calls to this API must include the following two parameters:


          * `page`: The page number of the results you wish to fetch.

          * `entries`: The number of templates to return per page, with a maximum value of *15*.


          Please update all integrations to include these parameters. API requests submitted without them after the effective date will result in an error and fail to execute.

          </Note>


          <Information>

          * If the request body is passed empty, then all templates will be returned.

          * The `preview_image` field in the response will be generated by MoEngage for the HTML template payload.

          </Information>


          #### Rate Limit

          The rate limit is 100 RPM.

          '
      requestBody:
        required: true
        description: Search filters for finding OSM templates.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchOsmTemplateRequest'
            example:
              page: 1
              entries: 10
              template_source:
              - API
              sort_params:
              - last_modified_date: DESCENDING
      responses:
        '200':
          description: Search successful. Returns a list of templates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchOsmTemplateResponse'
              example:
                data:
                - meta_info:
                    template_id: '1234567890123'
                    template_name: NAME_OF_THE_TEMPLATE
                    template_version: '1'
                    created_by: test@moengage.com
                    channel: ON-SITE
                    template_source: API
                    template_type: CUSTOM
                  external_template_id: 4a1afbc5-4c31-4f19-8c23-793e27af01aa
                  version: 1
                  basic_details:
                    payload: <html>...</html>
                    preview_image: https://pbs.twimg.com/profile_images/10ydbKG1.jpg
                  created_by: test@moengage.com
                  created_at: '2023-08-01T07:58:53.880000'
                  updated_by: test@moengage.com
                  updated_at: '2023-08-01T07:58:53.880000'
        '400':
          description: Bad Request. Missing or invalid search parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
              example:
                error:
                  code: 400 Bad Request
                  message: Validation failed because of invalid request data
                  details:
                  - code: MissingValue
                    target: external_template_ids
                    message: external_template_id or version is missing in external_template_ids.
                  request_id: npmQrbNE
        '429':
          description: Rate limit breached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
              example:
                response_id: OUUkHvcn
                type: custom_template
                error:
                  code: Too Many Requests
                  message: 'API rate limit breached. Current limit: n/m mins'
        5XX:
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleErrorResponse'
              example:
                title: Internal Server Error
                message: An unexpected error was encountered while processing this request. Please contact MoEngage Team
components:
  schemas:
    StandardErrorResponse:
      type: object
      description: Standard error structure used for 400 and 429 responses.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A brief explanation of the error.
              example: 4XX Bad Request
            message:
              type: string
              description: Describes why the request failed (e.g., Duplicate - template_id).
              example: Duplicate - template_id and template_version
            details:
              type: array
              description: A list of error detail objects containing code, target, and specific messages.
              items:
                type: object
                properties:
                  code:
                    type: string
                    description: Descriptive Error Code.
                    example: InvalidValue
                  target:
                    type: string
                    description: Denotes the field causing the issue.
                    example: Duplicate - template_id and template_version
                  message:
                    type: string
                    description: Descriptive Error Message.
                    example: template_id:BasicTemplate1 template_version:1 is already present.
            request_id:
              type: string
              description: Unique identifier for the request.
              example: cLCcgLQj
    SimpleErrorResponse:
      type: object
      description: Simplified error structure used for 401, 415, and 5xx responses.
      properties:
        title:
          type: string
          description: The title of the error.
          example: Authentication required
        description:
          type: string
          description: A description of the error (used in 401/415).
          example: MOE-APPKEY missing in Authentication Header
        message:
          type: string
          description: A message describing the error (used in 5xx).
          example: An unexpected error was encountered.
    UpdateOsmTemplateRequest:
      type: object
      required:
      - external_template_id
      - basic_details
      - meta_info
      properties:
        external_template_id:
          type: string
          format: uuid
          description: The unique identifier generated by MoEngage during template creation.
        update_campaigns:
          type: boolean
          default: false
          description: 'Flag to update all campaigns currently using this template to the newer version.

            * **`true`**: All campaigns running with this template will be updated.

            * **`false`**: A new version of the template is created; existing campaigns remain unchanged.

            '
        basic_details:
          type: object
          description: Details about the template payload.
          required:
          - payload
          properties:
            payload:
              type: string
              description: 'The updated HTML content.

                * Payload type must be HTML.

                * No limit restriction on field length.

                '
        meta_info:
          type: object
          description: Updates template information such as name, version, and updater details.
          required:
          - template_name
          - template_id
          - updated_by
          properties:
            template_name:
              type: string
              description: The name of the template being updated.
            template_id:
              type: string
              description: A unique ID for the template provided by you.
            template_version:
              type: string
              description: Optional new version for the template. The version will be increased by 1 automatically after every update.
            updated_by:
              type: string
              format: email
              description: The email ID of the person updating the template.
    SearchOsmTemplateResponse:
      type: object
      properties:
        data:
          type: array
          description: A list containing the details of the templates found.
          items:
            $ref: '#/components/schemas/OsmTemplate'
    CreateOsmTemplateRequest:
      type: object
      required:
      - basic_details
      - meta_info
      properties:
        basic_details:
          type: object
          description: Details about the template, including its payload and template type.
          required:
          - payload
          - template_type
          properties:
            payload:
              type: string
              description: 'Payload type must be HTML. The data type is a string.

                * No limit restriction on field length.

                * For payload structure examples, see the main endpoint documentation.

                '
            template_type:
              type: string
              description: The type of template being created.
              enum:
              - BANNER
              - POP_UP
              - NUDGE
        meta_info:
          type: object
          description: This field contains information about the template being created, such as its name, version, ID, and the creator's details.
          required:
          - created_by
          - template_id
          - template_name
          - template_version
          properties:
            created_by:
              type: string
              description: Identifier for the creator of the template (e.g., email).
            template_id:
              type: string
              description: A unique ID for the template provided by you.
            template_name:
              type: string
              description: The name of the template.
            template_version:
              type: string
              description: The version of the template.
    OsmTemplate:
      type: object
      properties:
        external_template_id:
          type: string
          format: uuid
          description: The unique system-generated ID for the template.
        version:
          type: integer
          description: The numeric version of the template.
        basic_details:
          type: object
          properties:
            payload:
              type: string
              description: The HTML payload of the template.
            preview_image:
              type: string
              format: uri
              description: A preview image URL generated by MoEngage for the HTML payload.
        meta_info:
          type: object
          properties:
            template_id:
              type: string
              description: The user-provided template ID.
            template_name:
              type: string
              description: The name of the template.
            template_version:
              type: string
              description: The user-provided string version.
            created_by:
              type: string
              description: The creator of the template.
            channel:
              type: string
              example: ON-SITE
              description: The channel associated with the template.
            template_source:
              type: string
              enum:
              - API
              - MOENGAGE
              description: The source of the template creation.
            template_type:
              type: string
              enum:
              - CUSTOM
              - PRE_BUILT
              description: The type classification of the template.
        created_by:
          type: string
          description: The user who created the template.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the template was created.
        updated_by:
          type: string
          description: The user who last updated the template.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the template was last updated.
    SearchOsmTemplateRequest:
      type: object
      description: '

        **Notes:**

        - `page` and `entries` are mandatory effective November 15, 2025. All other fields are optional.

        - An empty request body will fetch all templates.'
      required:
      - page
      - entries
      properties:
        page:
          type: integer
          description: The index of the page to be returned. Mandatory after Nov 15, 2025.
        entries:
          type: integer
          description: The number of entries/templates to return per page. Max 15. Mandatory after Nov 15, 2025.
          maximum: 15
        template_name:
          type: string
          description: The name of the template to search for. Returns templates matching this name.
        template_id:
          type: string
          description: The unique ID of the template provided by you.
        template_source:
          type: array
          description: Filter templates by their source.
          items:
            type: string
            enum:
            - API
            - MOENGAGE
        template_type:
          type: array
          description: Filter templates by type (Custom or Pre-built).
          items:
            type: string
            enum:
            - CUSTOM
            - PRE_BUILT
        created_by:
          type: array
          description: Filter templates by the creator's email identifier.
          items:
            type: string
            format: email
        updated_by:
          type: array
          description: Filter templates by the updater's email identifier.
          items:
            type: string
            format: email
        sort_params:
          type: array
          description: Sort the templates by multiple fields in ASCENDING or DESCENDING order. Priority follows the array order.
          items:
            type: object
            properties:
              template_name:
                type: string
                enum:
                - ASCENDING
                - DESCENDING
              last_modified_date:
                type: string
                enum:
                - ASCENDING
                - DESCENDING
              last_modified_by:
                type: string
                enum:
                - ASCENDING
                - DESCENDING
        external_template_ids:
          type: array
          description: Search for multiple templates using pairs of `external_template_id` and `version`.
          items:
            type: object
            properties:
              external_template_id:
                type: string
                format: uuid
              version:
                type: integer
  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 **Campaign report/Business events/Custom templates/Catalog API/Inform Report** tile.


        For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).

        '