openapi: 3.0.3
info:
  title: MoEngage Content Block API
  version: '1.0'
  description: >
    Content blocks allow marketers to reuse the same content across multiple campaigns. For example, a block might be a repeatedly used header, footer, or designed call-to-action button.



    This API enables you to fetch, create, and update content blocks on your MoEngage dashboard. [Read more about Content blocks in MoEngage](/user-guide/content/content-blocks/content-blocks).
tags:
  - name: Content Blocks
    description: Use these operations to programmatically fetch, create, and update reusable content blocks.
servers:
  - url: 'https://api-{dc}.moengage.com/v1/external/campaigns'
    description: MoEngage Content Blocks 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:
  /content-blocks:
    post:
      tags:
        - Content Blocks
      summary: Create Content Block
      description: >
        This API creates a content block in MoEngage.


        Use the `source` field in the request body to specify the communication type for the content block:

        - `"source": "ENGAGE"`: Creates a content block for use in Engage campaigns.

        - `"source": "INFORM"`: Creates a content block for use in Inform alerts.
      x-mint-groups:
        - Management
      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: 'YOUR_WORKSPACE_ID_XXXX'
      requestBody:
        required: true
        description: The details of the content block to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContentBlockRequest'
            examples:
              engage:
                summary: Create content block for Engage
                value:
                  name: "Summer_Sale_Header"
                  label: "summer_sale_header_2025"
                  description: "Header for all summer sale communications"
                  content_type: "HTML"
                  raw_content: "<h1>Huge Summer Sale!</h1>"
                  images_used: []
                  status: "ACTIVE"
                  created_by: "marketing@example.com"
                  content_block_used: []
                  source: "ENGAGE"
              inform:
                summary: Create content block for Inform
                value:
                  name: "Order_Status_Update"
                  label: "order_status_update"
                  description: "Reusable alert copy for order status notifications"
                  content_type: "TEXT"
                  raw_content: "Your order {{order_id}} has shipped."
                  images_used: []
                  status: "ACTIVE"
                  created_by: "alerts@example.com"
                  content_block_used: []
                  source: "INFORM"
      responses:
        '200':
          description: |
            Success. The response body is empty. To retrieve the ID of the newly created content block, use the Search Content Blocks API.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                title: "Invalid Field Value"
                description: "app_key - Some of the field values are invalid: app_key : None"
                code: "nGpUNpDQ"
        '5XX':
          description: Failure. Server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                title: "Internal Server Error"
                description: "An unexpected error occurred on the server."
                code: "SRV_ERR_123"
    put:
      tags:
        - Content Blocks
      summary: Update Content Block
      description: >
        This API updates the content blocks in MoEngage.
      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: 'YOUR_WORKSPACE_ID_XXXX'
      requestBody:
        required: true
        description: The updated details for the content block.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContentBlockRequest'
            example:
              id: "634fdf4db9c206ba55b8223b"
              name: "Summer_Sale_Header_Updated"
              status: "ACTIVE"
              raw_content: "<h1>Massive Summer Sale!</h1>"
              updated_by: "abc@gmail.com"
              content_block_used: []
      responses:
        '200':
          description: |
            Success. The response body is empty.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                title: "Invalid Field Value"
                description: "app_key - Some of the field values are invalid: app_key : None"
                code: "nGpUNpDQ"
        '5XX':
          description: Failure. Server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                title: "Internal Server Error"
                description: "An unexpected error occurred on the server."
                code: "SRV_ERR_123"
  /content-blocks/get-by-ids:
    post:
      tags:
        - Content Blocks
      summary: Get Specific Content Blocks
      description: >
        This API retrieves specific content blocks from the available content blocks in your MoEngage account.
      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: 'YOUR_WORKSPACE_ID_XXXX'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetByIdsRequest'
            example:
              ids: ["634fdf4db9c206ba55b8223b"]
              is_raw_content_required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetByIdsListResponse'
              example:
                data:
                  - id: "634fdf4db9c206ba55b8223ab"
                    name: "Contentblocktest2"
                    label: "Contentblocktest2"
                    description: ""
                    content_type: "TEXT"
                    content: "aa"
                    raw_content: "aa"
                    status: "ACTIVE"
                    created_by: "user@email.com"
                    created_at: "2022-10-19T11:28:13.925000"
                    updated_by: "test"
                    updated_at: "2022-10-21T08:38:51.419000"
                    tag_ids: ["0"]
                    team_ids: ["test"]
                    images_used: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                title: "Invalid Field Value"
                description: "app_key - Some of the field values are invalid: app_key : None"
                code: "nGpUNpDQ"
        '5XX':
          description: Failure. Server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                title: "Internal Server Error"
                description: "An unexpected error occurred on the server."
                code: "SRV_ERR_123"
  /content-blocks/search:
    post:
      tags:
        - Content Blocks
      summary: Search Content Blocks
      description: >
        This API searches for the available content blocks in your MoEngage account.
      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: 'YOUR_WORKSPACE_ID_XXXX'
      requestBody:
        required: true
        description: A set of filters to apply to the search.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchContentBlockRequest'
            example:
              filters:
                content_type: ["TEXT"]
                team_ids: ["0"]
                tag_ids: ["6141c7ec9b4cbd0b57c872e5"]
                status: ["ACTIVE"]
                updated_by: ["geetima@moengage.com"]
                search_text: "BT_non_personaliation"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchContentBlockListResponse'
              example:
                data:
                  - id: "61dd90a4cdfd67a8d48ef681"
                    name: "BT_non_personaliation"
                    label: "BT_non_personaliation"
                    description: "BT_non_personaliation"
                    content_type: "TEXT"
                    status: "ACTIVE"
                    created_by: "geetima@moengage.com"
                    created_at: "2022-01-11T14:13:56.063000"
                    updated_by: "geetima@moengage.com"
                    updated_at: "2022-01-11T14:15:31.254000"
                    tag_ids: ["6141c7ec9b4cbd0b57c872e5", "61409d091202397cc82f8356"]
                    team_ids: ["0"]
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                title: "Invalid Field Value"
                description: "app_key - Some of the field values are invalid: app_key : None"
                code: "nGpUNpDQ"
        '5XX':
          description: Failure. Server issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                title: "Internal Server Error"
                description: "An unexpected error occurred on the server."
                code: "SRV_ERR_123"

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:
    ErrorResponse:
      type: object
      properties:
        title:
          type: string
          example: "Invalid Field Value"
        description:
          type: string
          example: "app_key - Some of the field values are invalid: app_key : None"
        code:
          type: string
          example: "nGpUNpDQ"
    CreateContentBlockRequest:
      title: Create Content Block Attribute Mapping
      type: object
      required:
        - name
        - label
        - raw_content
        - content_type
        - created_by
        - content_block_used
      properties:
        name:
          type: string
          description: Name of the content block
        label:
          type: string
          description: Label to uniquely identify your content block
        status:
          type: string
          enum: [ACTIVE, DRAFT]
          description: Shows the status of the content block
        raw_content:
          type: string
          description: Content of the content block
        content_type:
          type: string
          enum: [HTML, TEXT]
          description: Type of the content block - HTML/ Plain Text
        description:
          type: string
          description: Description of the content block
        created_by:
          type: string
          format: email
          description: Email id of the user who is creating the content block
        tag_ids:
          type: array
          items:
            type: string
          description: Tags associated with the content block
        team_ids:
          type: array
          items:
            type: string
          description: >
            Teams for which the content block should be available. Passing team id is mandatory if you are using multiple teams.

            <Note>For more information, refer to [Teams](/user-guide/settings/account/team-management/teams-in-moengage).</Note>
        content_block_used:
          type: array
          items:
            type: string
          description: >
            In case, you are using nested content blocks, provide the names of the other content blocks used in this content block.

            <Note>If you are not using nested content blocks, you can pass this as an empty array: `content_block_used : []`</Note>
        images_used:
          type: array
          items:
            type: string
            format: uri
          description: Images used in content block
        source:
          type: string
          enum: [ENGAGE, INFORM]
          description: >
            Communication type for the content block. Supported values are:

            * `ENGAGE`: Creates a content block for use in Engage campaigns.

            * `INFORM`: Creates a content block for use in Inform alerts.

            <Note>You cannot change the communication type after the content block is created.</Note>
    UpdateContentBlockRequest:
      title: Update Content Block Attribute Mapping
      type: object
      required:
        - id
        - name
        - status
        - raw_content
        - updated_by
        - content_block_used
      properties:
        id:
          type: string
          description: ID of the content block that you want to update
        name:
          type: string
          description: Name of the content block
        status:
          type: string
          enum: [ACTIVE, DRAFT]
          description: Status of the content block - DRAFT/ACTIVE
        raw_content:
          type: string
          description: Content of the content block
        description:
          type: string
          description: Description of the content block
        updated_by:
          type: string
          format: email
          description: Email id of the user who is updating the content block
        tag_ids:
          type: array
          items:
            type: string
          description: Tags associated to the content block
        team_ids:
          type: array
          items:
            type: string
          description: >
            Teams for which the content block should be available. Passing team id is mandatory if you are using multiple Teams.

            <Note>For more information, refer to [Teams](/user-guide/settings/account/team-management/teams-in-moengage).</Note>
        content_block_used:
          type: array
          items:
            type: string
          description: >
            In case, you are using nested content blocks, provide the names of the other content blocks used in this content block.

            <Note>If you are not using nested content blocks, you can pass this as an empty array: `content_block_used : []`</Note>
        images_used:
          type: array
          items:
            type: string
            format: uri
          description: Images used in content block
    GetByIdsRequest:
      type: object
      required:
        - ids
      properties:
        ids:
          type: array
          items:
            type: string
          description: Comma-separated list of the content block ids
        is_raw_content_required:
          type: boolean
          description: >
            Boolean Flag used to control whether we need to show raw content or not.

            * `True`: Returns Non-Personalized content which was given during creation.
            * `False`: Does not return Personalized content
          default: false
    SearchContentBlockRequest:
      type: object
      properties:
        filters:
          type: object
          description: |
            A set of filters to apply to the search.
            <Note>You can send empty filters if you want all the content blocks: `{ "filters" : {} }`</Note>
          properties:
            content_type:
              type: array
              items:
                type: string
                enum: [HTML, TEXT]
              description: Type of the content block - HTML/Text
            team_ids:
              type: array
              items:
                type: string
              description: >
                Name of the teams for which the content block is enabled. This is only applicable to the accounts where Teams is enabled. For more information, refer to [Teams](/user-guide/settings/account/team-management/teams-in-moengage).
            tag_ids:
              type: array
              items:
                type: string
              description: Ids of the tags
            status:
              type: array
              items:
                type: string
                enum: [ACTIVE, ARCHIVED]
              description: Status of the content block
            updated_by:
              type: array
              items:
                type: string
                format: email
              description: Email id of the user who updated the content block
            search_text:
              type: string
              description: You can use this to search content block by content block name
    SearchResponseContentBlock:
      type: object
      description: Attribute Mapping for Search Response
      properties:
        id:
          type: string
          description: Content block id that was passed in the request
        name:
          type: string
          description: Name of the content block
        description:
          type: string
          description: Description of the content block
        content_type:
          type: string
          description: Type of the content block - HTML/Text
        content:
          type: string
          description: Content of the content block
        created_by:
          type: string
          description: Email id of the user who created the content block
        created_at:
          type: string
          description: Date Time of the content block creation
        updated_by:
          type: string
          description: Email id of the user who updates the content block
        updated_at:
          type: string
          description: Date Time of the content block update
        tag_ids:
          type: array
          items:
            type: string
          description: Tags associated with the content block
        team_ids:
          type: array
          items:
            type: string
          description: >
            Name of the teams for which the content block is enabled. This is only applicable to the accounts where Teams is enabled. For more information, refer to [Teams](/user-guide/settings/account/team-management/teams-in-moengage).
    GetByIdsResponseContentBlock:
      type: object
      description: Attribute Mapping for Get Specific Content Blocks Response
      properties:
        id:
          type: string
          description: Content block id that was passed in the request
        name:
          type: string
          description: Name of the content block
        description:
          type: string
          description: Description of the content block
        label:
          type: string
          description: Label of the content block
        content_type:
          type: string
          description: Type of the content block - HTML/Text
        content:
          type: string
          description: Content of the content block
        raw_content:
          type: string
          description: Raw content of the content block. This is returned when is_raw_content_required=true is passed in the request.
        created_by:
          type: string
          description: Email id of the user who created the content block
        status:
          type: string
          description: Shows the status of the content block
        created_at:
          type: string
          description: Date Time of the content block creation
        updated_by:
          type: string
          description: Email id of the user who updates the content block
        updated_at:
          type: string
          description: Date Time of the content block update
        tag_ids:
          type: array
          items:
            type: string
          description: Tags associated with the content block
        team_ids:
          type: array
          items:
            type: string
          description: >
            Name of the teams for which the content block is enabled. This is only applicable to the accounts where Teams is enabled. For more information, refer to [Teams](/user-guide/settings/account/team-management/teams-in-moengage).
        images_used:
          type: array
          items:
            type: string
          description: Images used in content block
    SearchContentBlockListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SearchResponseContentBlock'
    GetByIdsListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GetByIdsResponseContentBlock'