openapi: 3.0.3
info:
  title: MoEngage SMS Template API
  version: '1.0'
  description: API for creating, updating, and searching SMS templates within the MoEngage platform.
tags:
  - name: SMS Templates
    description: Operations to manage SMS templates.
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: []

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:
  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).

  schemas:
    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"

    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"

    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).

    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

    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

    SearchSmsTemplateResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SmsTemplate'