openapi: 3.0.3
info:
  title: MoEngage Subscription Categories 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."

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

  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

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

    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. 
            
            When `unsubscribe_all` is **true**, the user is unsubscribed from all the categories, irrespective of the categories marked as true in the category JSON object.
      example:
        unsubscribe_all: true
        categories:
          Promotional: true
          Transactional: false
          Special Offers: true
          Product Updates: true
          New arrivals: false
          Recommendations: true
          Newsletter: true

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

    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

    SuccessResponse:
      type: object
      properties:
        message:
          type: string
          description: A brief description of the request status in the case of success.

    ErrorResponse:
      type: object
      properties:
        title:
          type: string
          description: The error type.
        description:
          type: string
          description: The error description.

  responses:
    # 400 Bad Request is defined inline in operations to handle specific schema differences (GET vs PUT/POST)

    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"

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

    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"

security:
  - basicAuth: []