openapi: 3.1.0
info:
  title: Email Templates API V1
  description: |
    The Create Email Template API can be used to create an email template in MoEngage. This API helps you upload templates created outside the MoEngage ecosystem to MoEngage and use them for campaign creation on the MoEngage Dashboard.
    
    <Note>
    **Note**
    
    Templates created using this API cannot be used in the Drag and Drop Editor in the MoEngage Dashboard. They are supported only for the Custom HTML Editor (Froala Editor).
    </Note>
  version: v2
  contact:
    name: MoEngage Support
    url: https://help.moengage.com
servers:
  - url: https://api-{dc}.moengage.com/v2
    description: MoEngage 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: []
    appKey: []

tags:
  - name: Email Templates
    description: Manage email templates in MoEngage.
paths:
  /email-templates:
    post:
      summary: Create Email Template (V1)
      description: |
        This API creates an email template in MoEngage. You can use this API to upload templates created outside the MoEngage ecosystem to MoEngage and use them for campaign creation on the MoEngage dashboard.
      operationId: createEmailTemplate
      tags:
        - Email Templates
      x-mint:
        content: |
          #### Rate Limit
          The rate limits are at the workspace level, and a maximum of 1000 (sum of all the API requests per workspace) requests are allowed for a workspace per minute.

      parameters:
        - name: MOE-APPKEY
          in: header
          required: true
          schema:
            type: string
          description: |
            This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**.
          example: "APP ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateCreateRequest'
      responses:
        '200':
          description: This response is returned when the request is processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                    description: |
                      This field contains the status of the request and denotes whether it was successful or not.
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: |
                          This field contains the template id and needs to be stored by you. This template id would be used for searching a specific template and updating it. The template id is a String.
                        example: "63f4962d4d31f4c68d980a01"
                      msg:
                        type: string
                        description: |
                          This field contains information about the successful creation of the template.
                        example: "Custom email template saved"
              examples:
                Success:
                  value:
                    status: "success"
                    data:
                      id: "63f4962d4d31f4c68d980a01"
                      msg: "Custom email template saved"
        '400':
          description: This response is returned when the required parameters are missing from the request or when the provided parameters are invalid, or when a template already exists with the same version, name, or id.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 InvalidRequestBody:
                   value:
                     status: "error"
                     data:
                       code: 400
                       title: "Invalid request body"
                       description: "MOE-APPKEY header is invalid or empty"
                 EmptyName:
                   value:
                     status: "error"
                     data:
                       code: 400
                       title: "Invalid email name"
                       description: "Name field is empty"
        '401':
          description: This response is returned when the authorization parameters are missing in the HTTP Auth Header.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 AuthFailure:
                   value:
                     status: "error"
                     data:
                       code: 401
                       title: "Authentication required"
                       description: "Invalid APP_ID used in Authentication Header"
        '429':
          description: This response is returned when the number of requests per minute has exceeded the rate limit.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 RateLimit:
                   value:
                     status: "error"
                     data:
                       code: 429
                       title: "rate limiter exception"
                       description: "Exceeded rate limit for this app"
        '500':
          description: This response is returned when the system runs into an unexpected error.
          content:
             application/json:
               schema:
                 type: object
                 properties:
                   title: 
                     type: string
                   message: 
                     type: string
               examples:
                 ServerError:
                   value:
                     title: "Internal Server Error"
                     message: "An unexpected error was encountered while processing this request. Please contact MoEngage Team"

    get:
      summary: Get All Templates
      description: |
        This API fetches the list of all the email templates available in your MoEngage account.
      operationId: getAllTemplates
      tags:
        - Email Templates
      x-mint:
        content: |
          #### Rate Limit
          The rate limits are at the workspace level, and a maximum of 1000 (sum of all the API requests per workspace) requests are allowed for a workspace per minute.
      parameters:
        - name: MOE-APPKEY
          in: header
          required: true
          schema:
            type: string
          description: |
            This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**.
          example: "WORKSPACE ID"
        - name: page
          in: query
          description: |
            This parameter represents the page number. If this value is not specified, it will be considered as one by default. Each page will have a batch size of 20( 20 templates will be returned in a page).
          schema:
            type: integer
            default: 1
            example: 1
      responses:
        '200':
          description: This response is returned when the request is processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                    description: This field contains the status of the request and denotes whether it was successful or not.
                  data:
                    type: object
                    description: |
                        This field contains the id of the created template when the request is successful and the error details in case of an unsuccessful request.
                    properties:
                      templates:
                        type: array
                        items:
                          $ref: '#/components/schemas/TemplateDetails'
                      no_of_templates:
                        type: integer
                        description: The number of templates returned is also available in the response.
                        example: 13
              examples:
                Success:
                  value:
                    status: "success"
                    data:
                      templates:
                        - template_id: "645a2bd910e0307e6d7f7717"
                          template_name: "Coupon_code_template"
                          is_archived: false
                          builder_supported: false
                          editor: "Froala Editor"
                          created_date: "2023-05-09 11:17:43.112000"
                          updated_at: "2023-05-09 11:18:37.692000"
                          updated_by: "jane.doe@example.com"
                      no_of_templates: 13
        '400':
          description: This response is returned when the required parameters are missing from the request or when the provided parameters are invalid, or when a template already exists with the same version, name, or id.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 InvalidTemplateId:
                   value:
                     status: "error"
                     data:
                       code: 400
                       title: "Invalid template id"
                       description: "Please provide a valid template id"
        '401':
          description: This response is returned when the authorization parameters are missing in the HTTP Auth Header.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 AuthFailure:
                   value:
                     status: "error"
                     data:
                       code: 401
                       title: "Authentication required"
                       description: "Invalid APP_ID used in Authentication Header"
        '429':
          description: This response is returned when the number of requests per minute has exceeded the rate limit or the number of templates has exceeded the allowed quota per channel.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 RateLimit:
                   value:
                     status: "error"
                     data:
                       code: 429
                       title: "rate limiter exception"
                       description: "Exceeded rate limit for this app"
        '500':
          description: This response is returned when the system runs into an unexpected error.
          content:
             application/json:
               schema:
                 type: object
                 properties:
                   title: 
                     type: string
                   message: 
                     type: string
               examples:
                 ServerError:
                   value:
                     title: "Internal Server Error"
                     message: "An unexpected error was encountered while processing this request. Please contact MoEngage Team"

  /email-templates/{id}:
    get:
      summary: Get Specific Template
      description: |
        This API fetches an email template using its template ID.
      operationId: getTemplateById
      tags:
        - Email Templates
      x-mint:
        content: |
          #### Rate Limit
          The rate limits are at the workspace level, and a maximum of 1000 (sum of all the API requests per workspace) requests are allowed for a workspace per minute.
          
      parameters:
        - name: MOE-APPKEY
          in: header
          required: true
          schema:
            type: string
          description: |
            This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**.
          example: "Workspace ID"
        - name: id
          in: path
          required: true
          description: |
            This is the Template id of the template being searched. The template id is a unique identifier that is generated at the time of template creation.
          schema:
            type: string
            example: "63f30792c66ddcaac2ef9109"
      responses:
        '200':
          description: This response is returned when the request is processed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateDetailsFlat'
              examples:
                Success:
                  value:
                    status: "success"
                    template_id: "645a0cec10e0307e6d7f7716"
                    template_name: "End_of_season_sale_template"
                    subject: ""
                    template_content: "<!DOCTYPE html><html>...</html>"
                    attachments: []
                    source: "Partner"
                    sender_name: "Your Brand Name"
                    editor: "Froala Editor"
                    created_date: "2023-05-09 09:05:46.350000"
                    updated_at: "2023-05-09 10:00:57.149000"
                    updated_by: "john.doe@example.com"
        '400':
          description: This response is returned when the required parameters are missing from the request or when the provided parameters are invalid, or when a template already exists with the same version, name, or id.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 InvalidTemplateId:
                   value:
                     status: "error"
                     data:
                       code: 400
                       title: "Invalid template id"
                       description: "Please provide a valid template id"
        '401':
          description: This response is returned when the authorization parameters are missing in the HTTP Auth Header.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 AuthFailure:
                   value:
                     status: "error"
                     data:
                       code: 401
                       title: "Authentication required"
                       description: "Invalid APP_ID used in Authentication Header"
        '429':
          description: This response is returned when the number of requests per minute has exceeded the rate limit, or the number of templates has exceeded the allowed quota per channel.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 RateLimit:
                   value:
                     status: "error"
                     data:
                       code: 429
                       title: "rate limiter exception"
                       description: "Exceeded rate limit for this app"
        '500':
          description: This response is returned when the system runs into an unexpected error.
          content:
             application/json:
               schema:
                 type: object
                 properties:
                   title: 
                     type: string
                   message: 
                     type: string
               examples:
                 ServerError:
                   value:
                     title: "Internal Server Error"
                     message: "An unexpected error was encountered while processing this request. Please contact MoEngage Team"

    put:
      summary: Update Specific Template
      description: Updates an existing email template by specifying its template ID in the path.
      operationId: updateTemplateById
      tags:
        - Email Templates
      x-mint:
        content: |
          #### Rate Limit
          The rate limits are at the workspace level, and a maximum of 1000 (sum of all the API requests per workspace) requests are allowed for a workspace per minute.
      parameters:
        - name: MOE-APPKEY
          in: header
          required: true
          schema:
            type: string
          description: |
            This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**.
          example: "Workspace ID"
        - name: id
          in: path
          required: true
          description: |
            This is the Template id of the template being updated. It is mandatory to add this field when updating a template.
          schema:
            type: string
            example: "63f30792c66ddcaac2ef9109"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateUpdateRequest'
      responses:
        '200':
          description: This response is returned when the request is processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                    description: This field contains the status of the request and denotes whether it was successful or not.
                  data:
                    type: object
                    description: This field contains the id of the created template when the request is successful and the error details in case of an unsuccessful request.
                    properties:
                      id:
                        type: string
                        example: "63f4962d4d31f4c68d980a01"
                      msg:
                        type: string
                        example: "Custom email template updated"
        '400':
          description: This response is returned when the required parameters are missing from the request or when the provided parameters are invalid, or when a template already exists with the same version, name, or id.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: This response is returned when the authorization parameters are missing in the HTTP Auth Header.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: This response is returned when the number of requests per minute has exceeded the rate limit or the number of templates has exceeded the allowed quota per channel.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: This response is returned when the system runs into an unexpected error.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'

  /bulk/email-templates:
    put:
      summary: Bulk Create/Update Templates
      description: |
        This API creates or updates email templates in bulk. You can create or update up to 50 templates in a single request.
      operationId: bulkCreateUpdateTemplates
      tags:
        - Email Templates
      x-mint:
        content: |
          #### Rate Limit
          The rate limits are at the workspace level, and a maximum of 1000 (sum of all the API requests per workspace) requests are allowed for a workspace per minute.
          
      parameters:
        - name: MOE-APPKEY
          in: header
          required: true
          schema:
            type: string
          description: |
            This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**.
          example: "APP ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              description: You can pass the templates to be created and/or updated as an array of JSON Objects.
              maxItems: 50
              items:
                $ref: '#/components/schemas/TemplateBulkUpdateRequest'
      responses:
        '200':
          description: This response is returned when the request is processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                    description: This field contains the status of the request and denotes whether it was successful or not.
                  data:
                    type: object
                    description: This field contains the id of the created template when the request is successful and the error details in case of an unsuccessful request.
                    properties:
                      new_templates:
                        type: array
                        items:
                          type: string
                        description: |
                          This field contains the list of template ids for the newly created templates, and these need to be stored by you. The template id would be used for searching a specific template and updating it.
                        example: ["63f497844d31f4c68d980a02", "63f499344d31f4c68d720b04"]
                      updated_templates:
                        type: array
                        items:
                          type: string
                        description: |
                          This field contains the list of template ids for the updated templates.
                        example: ["645a2bd910e0307e6d7f7717"]
              examples:
                Success:
                  value:
                    status: "success"
                    data:
                      new_templates:
                        - "645a2c0d10e0307e6d7f7719"
                      updated_templates:
                        - "645a2bd910e0307e6d7f7717"
        '400':
          description: This response is returned when the required parameters are missing from the request or when the provided parameters are invalid, or when a template already exists with the same version, name, or id.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 ValidationFailure:
                   value:
                     status: "success"
                     data:
                       new_templates:
                         - "Email attachment should be valid one with size less than 6mb & total attachments size less than 20mb"
                       updated_templates:
                         - "Given id is invalid email template id"
        '401':
          description: This response is returned when the authorization parameters are missing in the HTTP Auth Header.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 AuthFailure:
                   value:
                     status: "error"
                     data:
                       code: 401
                       title: "Authentication required"
                       description: "Invalid APP_ID used in Authentication Header"
        '429':
          description: This response is returned when the number of requests per minute has exceeded the rate limit or the number of templates has exceeded the allowed quota per channel.
          content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 RateLimit:
                   value:
                     status: "error"
                     data:
                       code: 429
                       title: "rate limiter exception"
                       description: "Exceeded rate limit for this app"
        '500':
          description: This response is returned when the system runs into an unexpected error.
          content:
             application/json:
               schema:
                 type: object
                 properties:
                   title: 
                     type: string
                   message: 
                     type: string
               examples:
                 ServerError:
                   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 **Data** tile.

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

  schemas:
    # Common Error Response Schema
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        data:
          $ref: '#/components/schemas/ErrorData'

    # Base properties common to create and update
    TemplateBase:
      type: object
      required:
        - name
        - html
        - source
      properties:
        name:
          type: string
          minLength: 5
          maxLength: 50
          pattern: '^[a-zA-Z0-9_]+$'
          description: |
            This field contains the name of the template and would be used for identifying the template. You can look for the template created using this API in the second step of campaign creation in the 'My Saved Templates' tab using this name.
            
            **Note:**
            * The name field can contain only alphanumeric and underscore characters.
            * The length of this field can be between 5-50 characters.
          example: "End_Of_Season_Sale_Template"
        html:
          type: string
          description: |
            This field contains the message body of the email. This is where you define the email template being created. The HTML tag and BODY tag (with text/tags) are mandatory. The SCRIPT tag is not allowed.
          example: "<!DOCTYPE html><html><body><p>Content</p></body></html>"
        subject:
          type: string
          description: "This field contains the subject of the email campaign."
          example: "End of Season Sale!"
        attachments:
          type: array
          description: |
            This field contains the attachments to be included in the email.
            
            **Note:**
            * Only URLs can be added as part of Email attachments.
            * A maximum of ten attachments are allowed.
            * The URL should start with https and end with a valid extension. The following extensions are not allowed: .dmg, .exe, .xls, .ddl, .class, .obj, .int, .gnt, .o, .so, .lbr, and .net
            * Individual attachments should be less than 6 MB, and the total size of the attachments should be less than 20 MB.
          maxItems: 10
          items:
            type: string
            format: uri
            example: "https://app-cdn.moengage.com/assets/LogoThumbnail.jpg"
        sender_name:
          type: string
          description: |
            This field contains the name displayed that is displayed in the inboxes of your recipients. Sender names are one of the first things people see when you send them an email.
          example: "Your Brand Name"
        source:
          type: string
          description: |
            This field contains information about the source of template creation. This can be the name of the email partner.
            
            **Note:** Only alphanumerics, spaces, and underscores are allowed in this field.
          example: "Partner"
        updated_by:
          type: string
          description: |
            This field contains information about who created the template.
            
            **Note:** Only alphanumerics, spaces, and hyphens are allowed in this field. This field can contain the email ID of the creator as well. The email id should be in the right format and a valid one.
          example: "john.doe@example.com"

    # Schema for Creating a single template
    TemplateCreateRequest:
      allOf:
        - $ref: '#/components/schemas/TemplateBase'

    # Schema for Updating (requires ID in Bulk operations, but not in Path-based update)
    TemplateUpdateRequest:
      allOf:
        - $ref: '#/components/schemas/TemplateBase'

    # Schema specifically for the Bulk array where ID is required for updates
    TemplateBulkUpdateRequest:
      allOf:
        - $ref: '#/components/schemas/TemplateBase'
        - type: object
          properties:
            id:
              type: string
              description: |
                This is the Template id of the template being updated. It is mandatory to add this field when updating a template. The template id is a unique identifier that is generated at the time of template creation using the Create Email Template API.
              example: "63f30792c66ddcaac2ef9109"

    # Schema for GET All response objects
    TemplateDetails:
      type: object
      properties:
        template_id:
          type: string
          description: Template id - the unique identifier that is created at the time of template creation
          example: "645a2bd910e0307e6d7f7717"
        template_name:
          type: string
          description: name of the template being fetched
          example: "Coupon_code_template"
        is_archived:
          type: boolean
          example: false
        builder_supported:
          type: boolean
          description: |
            For the Froala editor, the builder_supported value is false. Thus, for all the templates created using APIs, this would be false.
          example: false
        editor:
          type: string
          example: "Froala Editor"
        created_date:
          type: string
          description: timestamp of template creation
          example: "2023-05-09 11:17:43.112000"
        updated_at:
          type: string
          description: timestamp of when the template was last updated
          example: "2023-05-09 11:18:37.692000"
        updated_by:
          type: string
          description: details about who created or updated the template
          example: "jane.doe@example.com"

    # Schema for GET Specific response
    TemplateDetailsFlat:
      type: object
      properties:
        status:
          type: string
          example: success
          description: |
            This field contains the status of the request and denotes whether it was successful or not.
        template_id:
          type: string
          example: "645a0cec10e0307e6d7f7716"
          description: |
            This field contains the id of the created template when the request is successful and the error details in case of an unsuccessful request.
        template_name:
          type: string
          example: "End_of_season_sale_template"
        subject:
          type: string
          description: subject of the template being fetched
        template_content:
          type: string
          description: html content of the template
        attachments:
          type: array
          description: |
            The attachments field is a list of JSON Objects that contain the details about an attachment, such as its type, url, name, id, and so on.
          items:
            type: object
            properties:
              id:
                 type: string
              name: 
                 type: string
              type: 
                 type: string
              fileType: 
                 type: string
              url:
                 type: string
        source:
          type: string
          description: source of the template being fetched
        sender_name:
          type: string
        editor:
          type: string
        created_date:
          type: string
          description: timestamp of template creation
        updated_at:
          type: string
          description: timestamp of when the template was last updated
        updated_by:
          type: string
          description: details about who created or updated the template

    ErrorData:
      type: object
      properties:
        code:
          type: integer
          description: |
            This field contains the error code and is a String. Example: 400 (for a Bad Request), 401( for Authentication failures), and so on. This field is present in the response only in the case of errors.
          example: 400
        title:
          type: string
          description: |
            This field contains the type of error encountered. Example: Bad Request, Authentication Required, and so on. This field is present in the response only in the case of errors.
          example: "Invalid request body"
        description:
          type: string
          description: |
            This field describes why the request has failed and is a String.
          example: "MOE-APPKEY header is invalid or empty"

  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              data:
                $ref: '#/components/schemas/ErrorData'
    Unauthorized:
      description: Authorization Failure
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              data:
                $ref: '#/components/schemas/ErrorData'
    RateLimit:
      description: Rate Limit Breach
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              data:
                $ref: '#/components/schemas/ErrorData'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              title:
                type: string
                example: "Internal Server Error"
              message:
                type: string
                example: "An unexpected error was encountered."