MoEngage SMS Templates API

openapi: 3.2.0
info:
  title: MoEngage SMS Template SMS Templates API
  version: '1.0'
  description: API for creating, updating, and searching SMS 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: SMS Templates
  description: Operations to manage SMS templates.
paths:
  /custom-templates/sms:
    post:
      tags:
      - SMS Templates
      summary: Create SMS Template
      description: This API creates an SMS template in MoEngage. It helps you upload templates created outside the MoEngage ecosystem to MoEngage and use them for campaign creation.
      x-mint:
        content: '#### Rate Limit

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

          '
      requestBody:
        required: true
        description: The details of the SMS template to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSmsTemplateRequest'
            example:
              basic_details:
                message: Hello {{UserAttribute['first_name']}}, your order is on its way!
              meta_info:
                created_by: john.doe@example.com
                template_id: shipping_update_v1
                template_name: Shipping Update Template
                template_version: '1'
      responses:
        '200':
          description: Success. This response is returned when the template is created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  external_template_id:
                    type: string
                    format: uuid
                    description: This field contains the unique ID assigned to the newly created template by MoEngage.
              examples:
                success:
                  summary: Successful Creation
                  value:
                    external_template_id: d05a44f0-a7cf-471a-bcb6-63054800a367
        '400':
          description: Bad Request. Returned when required parameters are missing, invalid, or duplicates exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_failure:
                  summary: Validation Failure
                  value:
                    error:
                      code: 400 Bad Request
                      message: Validation failed because of invalid request data
                      details:
                      - code: NotSupported
                        target: '[''summary'']'
                        message: '[''summary''] are not expected in this request.'
                      - code: MissingValue
                        target: platform
                        message: Template Body is missing for ANDROID.
                      request_id: LMwPhRMB
                empty_name:
                  summary: Empty Template Name
                  value:
                    error:
                      code: 400 Bad Request
                      message: Validation failed because of invalid request data
                      details:
                      - code: MissingValue
                        target: template_name
                        message: template_name value is required but value is passed empty.
                      request_id: jUxStmFn
                missing_fields:
                  summary: Missing Mandatory Fields
                  value:
                    error:
                      code: 400 Bad Request
                      message: Validation failed because of invalid request data
                      details:
                      - code: MissingValue
                        target: title
                        message: title value is required but value is passed empty.
                      request_id: eYXFWciv
                duplicate:
                  summary: Duplicate Request
                  value:
                    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:basicios12 template_version:12 is already present.
                      request_id: cLCcgLQj
                limit_breach:
                  summary: Max Template Limit Breach
                  value:
                    error:
                      code: 400 Bad Request
                      message: Maximum Template limit exceeded
                      details:
                      - code: NotSupported
                        target: Maximum Template limit exceeded
                        message: You have already created maximum allowed template allowed for client
                      request_id: eLeZXIlW
        '401':
          description: Authentication Failure. Returned when authorization parameters are missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                auth_required:
                  summary: Authentication Required
                  value:
                    title: Authentication required
                    description: MOE-APPKEY missing in Authentication Header
        '403':
          description: Unauthorized Access. Returned when authorization fails due to incorrect keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_secret:
                  summary: Invalid App Secret Key
                  value:
                    error:
                      code: 403 Forbidden
                      message: Authentication required
                      details:
                      - code: InvalidValue
                        target: APP_SECRET_KEY
                        message: Invalid APP_SECRET_KEY is provided.
                      request_id: oZEMYhqA
                invalid_appid:
                  summary: Invalid App ID
                  value:
                    error:
                      code: 403 Forbidden
                      message: Authentication required
                      details:
                      - code: InvalidValue
                        target: APP_ID
                        message: Invalid APP_ID is provided.
                      request_id: TWdrwUMN
        '415':
          description: Unsupported File Type. Content-Type header is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unsupported_media:
                  summary: Unsupported Media Type
                  value:
                    title: Unsupported media type
                    description: Content type is not supported
        '429':
          description: Rate Limit Breach (100 RPM).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate_limit:
                  summary: Rate Limit Breach
                  value:
                    response_id: OUUkHvcn
                    type: custom_segment
                    error:
                      code: Too Many Requests
                      message: 'API rate limit breached. Current limit: n/m mins'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
              examples:
                server_error:
                  summary: Internal Server Error
                  value:
                    title: Internal Server Error
                    message: An unexpected error was encountered while processing this request. Please contact MoEngage Team
    put:
      tags:
      - SMS Templates
      summary: Update SMS Template
      description: This API updates an SMS template by specifying its external template ID. You can specify in the request whether the updated version of the template can be used in active campaigns.
      x-mint:
        content: '#### Rate Limit

          The rate limit is **100 RPM**.

          '
      requestBody:
        required: true
        description: The updated details for the SMS template.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSmsTemplateRequest'
            example:
              external_template_id: d05a44f0-a7cf-471a-bcb6-63054800a367
              update_campaigns: false
              basic_details:
                message: Hi {{UserAttribute['first_name']}}, your order has been delivered!
              meta_info:
                template_name: Shipping Update Template V2
                updated_by: jane.doe@example.com
                template_version: '2'
      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.
              examples:
                success:
                  summary: Successful Update
                  value:
                    external_template_id: eca024b7-a8ea-4f31-9154-5b80c85d18a9
        '400':
          description: Bad Request. Invalid `external_template_id` or other request data validation errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_id:
                  summary: Invalid Template ID
                  value:
                    error:
                      code: 400 Bad Request
                      message: Invalid template id
                      details:
                      - code: MissingValue
                        target: 9925c8
                        message: 9925c8 is invalid template id.
                      request_id: BTkUaYgU
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
              examples:
                server_error:
                  summary: Internal Server Error
                  value:
                    title: Internal Server Error
                    message: An unexpected error was encountered while processing this request. Please contact MoEngage Team
  /custom-templates/sms/search:
    post:
      tags:
      - SMS Templates
      summary: Search SMS Templates
      description: This API searches and retrieves a list of SMS templates, created in your MoEngage account, based on specified filter criteria.
      x-mint:
        content: '<Note>

          **Mandatory Pagination Update**


          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>


          #### Rate Limit

          The rate limit is **100 RPM**.

          '
      requestBody:
        required: true
        description: Use search filters to find SMS templates.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchSmsTemplateRequest'
            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/SearchSmsTemplateResponse'
              examples:
                success:
                  summary: Successful Search
                  value:
                    data:
                    - external_template_id: b564524f-aa08-4149-a498-dbde0b7b3740
                      version: 1
                      basic_details:
                        message: Sample SMS Template message
                      meta_info:
                        template_id: CCIJASDA12345
                        template_name: CouponCodeTemplate1
                        template_version: '1'
                        created_by: Jane Doe
                        channel: SMS
                        template_type: CUSTOM
                      created_by: Jane Doe
                      created_at: '2023-02-27T12:33:05.575000'
                      updated_by: John Doe
                      updated_at: '2023-02-27T12:33:05.575000'
        '400':
          description: Bad Request. Invalid field values in the search criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_field:
                  summary: Invalid Field Value
                  value:
                    title: Invalid Field Value
                    description: Some of the field values are invalid
                    code: nGpUNpDQ
        '429':
          description: Rate limit breached (100 RPM).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate_limit:
                  summary: Rate Limit Breach
                  value:
                    response_id: OUUkHvcn
                    type: custom_segment
                    error:
                      code: Too Many Requests
                      message: 'API rate limit breached. Current limit: n/m mins'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
              examples:
                server_error:
                  summary: Internal Server Error
                  value:
                    title: Internal Server Error
                    message: An unexpected error was encountered while processing this request. Please contact MoEngage Team
components:
  schemas:
    ErrorResponse:
      type: object
      description: Standard error response format for 4xx errors.
      properties:
        error:
          type: object
          description: This field contains the reason for the request's failure.
          properties:
            code:
              type: string
              description: The HTTP status code and error type.
              example: 4xx Status Code
            message:
              type: string
              description: A description of the error.
              example: Brief description of the error.
            details:
              type: array
              description: This is a List of the error details objects. Each object contains the following information.
              items:
                type: object
                properties:
                  code:
                    type: string
                    example: ErrorCode
                  target:
                    type: string
                    example: Field Name
                  message:
                    type: string
                    example: Error description for this field.
            request_id:
              type: string
              description: This field contains the unique id pertaining to the request.
              example: Unique Request ID
    SearchSmsTemplateRequest:
      type: object
      description: '

        **Notes:**

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

        - You can send only template_ids if you want specific older versions of the SMS template. In other cases, you will receive the latest version of the template.'
      required:
      - page
      - entries
      properties:
        page:
          type: integer
          description: This field contains the index of the pages to be returned in the search result
          default: 1
        entries:
          type: integer
          description: This field contains the number of templates to return per page.
          maximum: 15
          default: 15
        template_name:
          type: string
          description: This field indicates the name of the template. When this value is specified, the template that matches the name specified in this field will be returned (partial search is supported).
        template_source:
          type: array
          description: This field indicates the template source that created the template. When specified, templates whose source matches the one specified in this list will be returned.
          items:
            type: string
            enum:
            - API
            - MOENGAGE
        template_type:
          type: array
          description: This field indicates whether the template is a custom one or a pre-built one. When specified, templates whose template type matches the one specified in this list will be returned.
          items:
            type: string
            enum:
            - CUSTOM
            - PRE_BUILT
        created_by:
          type: array
          description: This field indicates the user who created the template. When specified, the templates for which the created_by user information matches that specified in this list will be returned.
          items:
            type: string
            format: email
        updated_by:
          type: array
          description: This field indicates the user who updated the template. When specified, the templates for which the updated_by user information matches that specified in this list will be returned.
          items:
            type: string
            format: email
        sort_params:
          type: array
          description: This field indicates the sorting parameters for the search result and the sort 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
        template_ids:
          type: array
          description: This field indicates the list of template IDs that must be fetched. When this value is specified, the template that matches the ID specified in this field will be returned.
          items:
            type: object
            properties:
              external_template_id:
                type: string
                format: uuid
              version:
                type: integer
    SearchSmsTemplateResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SmsTemplate'
    CreateSmsTemplateRequest:
      type: object
      required:
      - basic_details
      - meta_info
      properties:
        basic_details:
          type: object
          description: This field contains the basic details of the SMS template.
          required:
          - message
          properties:
            message:
              type: string
              description: This field contains the message of the template.
        meta_info:
          type: object
          description: This field contains information about the template being created.
          required:
          - created_by
          - template_id
          - template_name
          - template_version
          properties:
            created_by:
              type: string
              description: This field contains details about who created the template. You must provide this value.
            template_id:
              type: string
              description: This field contains the ID for the template and is unique. You must provide this value.
            template_name:
              type: string
              description: This field contains the name of the template. You must provide this value, and it will be used for identifying the template.
            template_version:
              type: string
              description: This field contains the version of the template. You must provide this value, and it will be used for tracking the template's version.
    UpdateSmsTemplateRequest:
      type: object
      required:
      - external_template_id
      - basic_details
      - meta_info
      properties:
        external_template_id:
          type: string
          format: uuid
          description: This field contains the unique identifier that is generated by MoEngage during the template creation.
        update_campaigns:
          type: boolean
          default: false
          description: If true, this field contains a flag used to update all active campaigns currently using the template being updated to the newer version (being updated in this request).
        basic_details:
          type: object
          description: This field contains the basic details of the SMS template.
          required:
          - message
          properties:
            message:
              type: string
              description: This field contains the updated content of the template.
        meta_info:
          type: object
          description: This field contains information about the template being created.
          required:
          - template_name
          - updated_by
          properties:
            template_name:
              type: string
              description: This field contains the name of the template being updated.
            updated_by:
              type: string
              format: email
              description: This field contains the email ID of the person updating the template.
            template_version:
              type: string
              description: This field contains the version of the template (optional).
    InternalServerError:
      type: object
      description: Schema for 500 Internal Server Error.
      properties:
        title:
          type: string
          example: Internal Server Error
        message:
          type: string
          example: An unexpected error was encountered while processing this request. Please contact MoEngage Team
    SmsTemplate:
      type: object
      properties:
        external_template_id:
          type: string
          format: uuid
        version:
          type: integer
        basic_details:
          type: object
          properties:
            message:
              type: string
        meta_info:
          type: object
          properties:
            template_id:
              type: string
            template_name:
              type: string
            template_version:
              type: string
            created_by:
              type: string
            channel:
              type: string
              example: SMS
            template_type:
              type: string
              enum:
              - CUSTOM
              - PRE_BUILT
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_by:
          type: string
        updated_at:
          type: string
          format: date-time
  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).

        '