MoEngage Subscription Preferences API

openapi: 3.2.0
info:
  title: MoEngage Subscription Categories Subscription Preferences API
  description: 'Enables you to fetch and update email subscription preferences on your MoEngage dashboard.


    This API provides endpoints for:

    * **Get Preferences**: Fetches subscription preferences for a specific user.

    * **Update Preferences**: Updates preferences for a specific user (e.g., from a landing page).

    * **Bulk Update Preferences**: Updates preferences for a batch of users.


    Authentication is handled via Basic Auth (Workspace ID as username, Data API Key as password) and the `MOE-APPKEY` header.

    '
  version: '1.0'
servers:
- url: https://api-{dc}.moengage.com/v1
  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: []
tags:
- name: Subscription Preferences
  description: Manage user email subscription preferences.
paths:
  /category-subscription/user-preferences:
    get:
      tags:
      - Subscription Preferences
      summary: Get Subscription Preferences
      operationId: getSubscriptionPreferences
      description: 'This API fetches the subscription category preferences information for a specific user based on the encrypted User ID and Campaign ID found in the landing page URL.

        '
      x-mint:
        content: '#### Rate Limit

          The rate limit is 100 RPM and 360k per day.

          '
      parameters:
      - $ref: '#/components/parameters/AppKeyHeader'
      - name: user_id
        in: query
        required: true
        description: "This is the MoEngage ID that uniquely identifies the customer for whom the subscription preferences are being updated. \n\n**Note:** MoEngage ID is encrypted using 16 bits DES and is encoded in the URL of the landing page. It must be sent as-is (encrypted).\n"
        schema:
          type: string
      - name: cid
        in: query
        required: true
        description: 'This is the campaign id of the email campaign. This field contains the information about the email campaign received by the customer.


          **Note:** The campaign ID is encrypted using 16-bit DES and is encoded within the landing page URL. You must fetch the encrypted `<campaign Id>` from the URL and send it directly to MoEngage; it is not necessary to perform any decryption.

          '
        schema:
          type: string
      responses:
        '200':
          description: Success. This response is returned when the request is processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  categories:
                    $ref: '#/components/schemas/SubscriptionCategories'
              example:
                categories:
                  Promotional: true
                  Product Update: true
                  Newsletter: true
                  Conferences and Events: true
                  Special Offers: true
                  Recommended Music: true
                  New Music: true
                  Playlist Updates: false
                  Concert Notifications: true
                  Artist Updates: true
                  test: true
        '400':
          description: Bad Request. Returned when parameters are missing or invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Invalid Params Received
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Subscription Preferences
      summary: Update Subscription Preferences
      operationId: updateSubscriptionPreferences
      description: 'This API updates the subscription category preferences for a specific user who navigates from an email. This endpoint requires the encrypted IDs obtained from the email link.

        '
      x-mint:
        content: '#### Rate Limit

          The rate limit is 100 RPM and 360k per day.

          '
      parameters:
      - $ref: '#/components/parameters/AppKeyHeader'
      - name: user_id
        in: query
        required: true
        description: 'This is the MoEngage ID that uniquely identifies the customer. Encrypted using 16 bits DES and encoded in the URL of the landing page.

          '
        schema:
          type: string
      - name: cid
        in: query
        required: true
        description: 'The campaign ID of the email campaign. Encrypted using 16 bits DES and encoded in the URL of the landing page.

          '
        schema:
          type: string
      - name: moe_event_id
        in: query
        required: false
        description: This is used to update the unsubscribe event when the user chooses the 'unsubscribe all' option.
        schema:
          type: string
      requestBody:
        required: true
        description: The user's updated preferences.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePreferencesRequest'
      responses:
        '200':
          description: Success. This response is returned when the request is processed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                message: Success
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                title: Internal App Key
                description: Valid App-Key required to process
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Subscription Preferences
      summary: Bulk Update Subscription Preferences
      operationId: bulkUpdateSubscriptionPreferences
      description: 'This API updates subscription category preferences in bulk. You can use this API to update the user preferences to MoEngage in large volumes.

        '
      x-mint:
        content: '#### Rate Limit

          The rate limit is 100 RPM and 360k per day.

          '
      parameters:
      - $ref: '#/components/parameters/AppKeyHeader'
      requestBody:
        required: true
        description: A list of preference updates for multiple users.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpdatePreferencesRequest'
      responses:
        '200':
          description: Your request has been processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                message: Your request has been processed
        '400':
          description: Bad Request. Returned when payload limit exceeded or categories missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                categories_required:
                  summary: Categories Required
                  value:
                    title: Categories Required
                    description: Categories Preferences Required
                payload_limit:
                  summary: Payload Limit Exceeded
                  value:
                    title: Payload Limit Exceeded
                    description: Payload limit is set to 50
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        title:
          type: string
          description: The error type.
        description:
          type: string
          description: The error description.
    UserPreferenceEntry:
      type: object
      required:
      - customer_id
      - categories
      - unsubscribe_all
      properties:
        customer_id:
          type: string
          description: The unique identifier denoting the customer (ID on the user profile page) for whom you are updating the subscription preferences.
          example: john@example.com
        categories:
          $ref: '#/components/schemas/SubscriptionCategories'
        unsubscribe_all:
          type: boolean
          description: Set to **true** to unsubscribe the user from all categories.
    SuccessResponse:
      type: object
      properties:
        message:
          type: string
          description: A brief description of the request status in the case of success.
    BulkUpdatePreferencesRequest:
      type: object
      required:
      - channel
      - user_preferences
      properties:
        channel:
          type: string
          enum:
          - email
          description: 'This field contains the name of the channel. Allowed values - "channel": "email"'
          example: email
        user_preferences:
          type: array
          description: A list of user preference objects to update. Maximum 50 per request.
          maxItems: 50
          items:
            $ref: '#/components/schemas/UserPreferenceEntry'
      example:
        channel: email
        user_preferences:
        - customer_id: john@example.com
          categories:
            Promotional: false
            Transactional: false
            Special Offers: true
          unsubscribe_all: false
        - customer_id: mike@example.com
          categories:
            Transactional: true
            Promotional: false
            Special Offers: true
          unsubscribe_all: false
        - customer_id: doe@example.com
          categories:
            Product Updates: true
            New arrivals: false
            Recommendations: true
          unsubscribe_all: false
    UpdatePreferencesRequest:
      type: object
      required:
      - categories
      - unsubscribe_all
      properties:
        categories:
          $ref: '#/components/schemas/SubscriptionCategories'
          description: This field contains the details about the updated subscription preferences of the user.
        unsubscribe_all:
          type: boolean
          description: "This field contains information about whether or not a customer has unsubscribed from all categories. \n\nWhen `unsubscribe_all` is **true**, the user is unsubscribed from all the categories, irrespective of the categories marked as true in the category JSON object.\n"
      example:
        unsubscribe_all: true
        categories:
          Promotional: true
          Transactional: false
          Special Offers: true
          Product Updates: true
          New arrivals: false
          Recommendations: true
          Newsletter: true
    SubscriptionCategories:
      type: object
      description: 'A JSON Object that contains the subscription preferences of the customer.

        `category_name` is the unique category name in MoEngage.

        '
      additionalProperties:
        type: boolean
      example:
        Promotions: true
        Updates: false
        Recommendations: true
        Newsletter: false
  responses:
    Conflict:
      description: API SECRET not configured. Returned when the authorization fails due to the APP SECRET key not being set on the Dashboard.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            title: API SECRET not configured
            description: This response is returned when the authorization fails due to the APP SECRET key not being set on the Dashboard.
    Unauthorized:
      description: Authorization Failure. Returned when authorization fails due to incorrect APP KEY/HTTP Auth Header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            auth_required:
              summary: Auth Failure
              value:
                title: Authentication required
                description: No identity information found.
            missing_header:
              summary: Missing Header
              value:
                title: Header required
                description: MOE-APPKEY missing in Header
    TooManyRequests:
      description: Rate Limit Breach. The number of requests per minute has exceeded the limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            title: Rate-Limit Reached
            description: Exceeded rate limit for this url
    InternalServerError:
      description: Internal Server Error. Returned when the system runs into an unexpected error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            title: Internal Error
            description: Please Contact Moengage Team
  parameters:
    AppKeyHeader:
      name: MOE-APPKEY
      in: header
      required: true
      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)**.

        '
      schema:
        type: string
  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).

        '