MoEngage Opt-in Management API

openapi: 3.2.0
info:
  title: MoEngage Email Subscription Management Opt-in Management API
  description: 'APIs for managing user email resubscription and opt-in status.

    This suite of APIs allows you to update the email subscription and opt-in preferences for your users directly within the MoEngage platform, and optionally synchronize resubscription status with an external Email Service Provider (ESP).

    '
  version: '1.0'
servers:
- url: https://api-{dc}.moengage.com
  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: Opt-in Management
  description: Update user email opt-in status and category preferences in MoEngage.
paths:
  /v1.0/opt-in-management/user-preferences:
    put:
      tags:
      - Opt-in Management
      summary: Update User Email Opt-in Preferences
      description: 'This API updates a user''s overall email opt-in status and/or category-level subscription preferences within MoEngage. This API is typically used after a user submits the second confirmation through MoEngage consent-seeking emails (Double Opt-in).

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

          The rate limit is **1000 RPM** (requests per minute) and **360K** requests per day.


          <Note>

          If you use PII Tokenization for your emails, ensure you pass the user ID when calling the Email Opt-in Management API. MoEngage uses this user ID to locate the user and update their opt-in status. Passing the email ID is ineffective in this case, as MoEngage does not store it.


          If you use PII Encryption to send emails, ensure you pass either the user ID or the decrypted email ID. MoEngage uses this information to locate the associated user and update their opt-in status, or to update the opt-in status of all users having that email ID.

          </Note>

          '
      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:
        description: The request body contains the user's email preference details encapsulated in a `user_preferences` object.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OptinRequest'
            example:
              user_preferences:
                customer_id: ID_uid
                email_id: john@example.com
                categories:
                  category_1: true
                  category_2: false
                opt_in_status: DOUBLE_OPTED_IN
                channel: email
      responses:
        '200':
          description: The request has been processed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptinSuccessResponse'
              example:
                message: Your request has been processed successfully
        '400':
          description: Bad Request. Returned when required parameters are missing, incorrect data types are used, invalid values are passed (e.g., invalid `opt_in_status`), or the user is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptinError400Response'
              examples:
                invalidDataType:
                  summary: Invalid Data Type
                  value:
                    error:
                      code: 400 Bad Request
                      message: Request Data is invalid.
                      details:
                        target: customer_id
                        message: 'Wrong data type was used for <customer_id> - Value must be of type (<class ''str''>,), passed type: <class ''bool''> : False.'
                invalidOptInStatus:
                  summary: Invalid Opt-in Status Value
                  value:
                    error:
                      code: 400 Bad Request
                      message: Request Data is invalid
                      details:
                        target: opt_in_status
                        message: Opt-In status can only be 'DOUBLE_OPTED_IN' or 'OPTED_OUT' or 'OPT_IN_PENDING' (case-insensitive). Please provide the correct value.
                missingIdOrEmail:
                  summary: Missing customer_id or email_id
                  value:
                    error:
                      code: 400 Bad Request
                      message: Request Data is invalid
                      details:
                        target: customer_id or email_id
                        message: Either customer_id or email_id is mandatory. Please provide at least one of them.
                userNotFound:
                  summary: User Not Found
                  value:
                    error:
                      code: 400 Bad Request
                      message: Request Data is invalid
                      details:
                        target: customer_id or email_id
                        message: No users found with the provided customer_id or email_id. Please check the same.
                invalidCategory:
                  summary: Invalid or Inactive Category
                  value:
                    error:
                      code: 400 Bad Request
                      message: Request Data is invalid
                      details:
                        target: categories
                        message: Categories A, B, C are either invalid or not active in the Workspace. Please check the categories in the request.
                extraKey:
                  summary: Extra Key Passed in Request
                  value:
                    error:
                      code: 400 Bad Request
                      message: Request Data is invalid
                      details:
                        target: '[''customerid'']'
                        message: Extra key passed in the request
                invalidChannel:
                  summary: Invalid Channel Value
                  value:
                    error:
                      code: 400 Bad Request
                      message: Request Data is invalid
                      details:
                        target: channel
                        message: Channel can only be ['email'] (case-insensitive). Please provide the correct channel.
                customerIdMandatory:
                  summary: customer_id Mandatory (Unsubscribe On Email Disabled)
                  value:
                    error:
                      code: 400 Bad Request
                      message: Request Data is invalid
                      details:
                        target: customer_id
                        message: customer_id is mandatory when unsubscribe on email is not enabled.
                noActiveCategories:
                  summary: No Active Categories in Workspace
                  value:
                    error:
                      code: 400 Bad Request
                      message: Request Data is invalid
                      details:
                        target: categories
                        message: There are no active categories found. Please remove the categories from the request data or setup the subscription categories in MoEngage Email settings.
                allCategoriesInvalid:
                  summary: All Provided Categories Invalid or Inactive
                  value:
                    error:
                      code: 400 Bad Request
                      message: Request Data is invalid
                      details:
                        target: categories
                        message: All provided categories are either invalid or not active in the Workspace. Please check the categories in the request.
                sentryCheckFailed:
                  summary: Sentry Check Failed
                  value:
                    message: Sentry check failed
        '401':
          description: Unauthorized. Authentication failed (e.g., missing Authorization header, wrong Workspace ID, or wrong Data API Key).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptinError401Response'
              examples:
                missingAuthHeader:
                  summary: Missing Authorization Header
                  value:
                    error:
                      code: 401 Unauthorized
                      message: Authentication failed.
                      details:
                        target: Authorization Header
                        message: Authorization header is missing
                wrongDataKey:
                  summary: Wrong Data API Key
                  value:
                    error:
                      code: 401 Unauthorized
                      message: Authentication failed
                      details:
                        target: Data key
                        message: Data API key is wrong. Please provide correct Data API Key as password.
        '403':
          description: Forbidden. Returned when the Email Opt-in Management feature is not enabled for the workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptinError403Response'
              example:
                error:
                  code: 403 Forbidden
                  message: Feature not enabled
                  details:
                    target: Email Opt-in Management
                    message: Email Opt-in Management feature not enabled for the workspace. Please reach out to MoEngage to get it enabled.
        '429':
          description: Too Many Requests. The request rate has exceeded the limit of 1000 RPM or 360K per day.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptinError429Response'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptinError500Response'
              example:
                error:
                  code: 500 Internal Server Error
                  message: Something went wrong, Please contact MoEngage Team.
components:
  schemas:
    UserPreferences:
      type: object
      description: 'Contains the user''s opt-in preferences. Must contain either `customer_id` or `email_id`.

        '
      required:
      - opt_in_status
      - channel
      properties:
        customer_id:
          type: string
          description: "Unique identifier for the user in MoEngage. Optional, if `email_id` is passed.\n\nTo avoid error, make sure you pass either `customer_id` or `email_id`.\nIf you are passing `customer_id`, `email_id` is not mandatory. \nIf you pass only `customer_id`, MoEngage finds the user with this `customer_id` and updates the opt-in status accordingly.\nGenerally, when `email_id` is passed, MoEngage finds all users with this `email_id` and updates the opt-in status accordingly. But if you don't want all the users with this `email_id` to be updated, you can contact the MoEngage team.\n`customer_id` is mandatory if you don't want to pass the opt-in status update to all users with the same email ID.\n"
          example: ID_uid
        email_id:
          type: string
          format: email
          description: 'Email ID of the user. Optional if `customer_id` is provided.


            If only `email_id` is provided, all users with this email may be updated (contact MoEngage support to configure behavior).


            To avoid error, make sure you pass `customer_id` or `email_id`.

            If you are passing `email_id`, `customer_id` is not mandatory.

            If you pass only `email_id`, MoEngage finds all the users with this `email_id` and updates the opt-in status accordingly.

            You can also pass both `customer_id` and `email_id`. In this case, `email_id` is given the highest priority, and MoEngage finds all users with this `email_id` and updates the opt-in status accordingly.

            You can contact the MoEngage team if you don''t want to update the opt-in status of all users with the same email ID.

            '
          example: john@example.com
        categories:
          type: object
          description: 'Subscription status for defined categories in your dashboard.


            Keys are category names, values are boolean (`true`=subscribed). If even one category is invalid/inactive, the entire request will fail.


            **Note**: If this is passed and all category values are `false`, the overall `opt_in_status` will be overridden to **OPTED_OUT** even if `DOUBLE_OPTED_IN` is passed.

            '
          additionalProperties:
            type: boolean
          example:
            category_1: true
            category_2: false
        opt_in_status:
          type: string
          description: 'The user''s overall email opt-in status.


            Note:

            This field is case-insensitive, but ensure that you follow the same format as in the example.

            You can pass both `categories` and `opt_in_status`. In this case, if all category values are `false` and `opt_in_status` is `DOUBLE_OPTED_IN`, MoEngage gives high priority to category-level information and the opt-in status is updated as `OPTED_OUT`.

            '
          enum:
          - DOUBLE_OPTED_IN
          - OPTED_OUT
          - OPT_IN_PENDING
          example: DOUBLE_OPTED_IN
        channel:
          type: string
          description: The channel for which the opt-in status applies. Currently, only **email** is supported.
          enum:
          - email
          example: email
    OptinError429Response:
      description: There is no response body for this error.
    OptinError400Response:
      type: object
      description: This response is returned when the required parameters are missing from the request, attributes are not found, or incorrect values are passed.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: The HTTP status code and text (e.g., '400 Bad Request').
              example: 400 Bad Request
            message:
              type: string
              description: A brief message denoting the type of error.
              example: Request Data is invalid.
            details:
              type: object
              description: Contains granular error information including the target field and a detailed error message.
              properties:
                target:
                  type: string
                  description: The field where the error occurred (e.g., `customer_id`).
                  example: customer_id
                message:
                  type: string
                  description: The details of the error message.
                  example: Wrong data type was used for <customer_id>...
    OptinError500Response:
      type: object
      description: Error response body for Internal Server Error (500).
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: 500 Internal Server Error
            message:
              type: string
              example: Something went wrong, Please contact MoEngage Team.
    OptinSuccessResponse:
      type: object
      description: Success response body for the Opt-in Management API (200 OK).
      properties:
        message:
          type: string
          description: The success message denoting the request was processed successfully.
          example: Your request has been processed successfully
    OptinRequest:
      type: object
      description: The main wrapper object for the user preferences payload.
      required:
      - user_preferences
      properties:
        user_preferences:
          $ref: '#/components/schemas/UserPreferences'
    OptinError403Response:
      type: object
      description: This response is returned when the Email Opt-in Management feature is not enabled for the workspace.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: The HTTP status code and text (e.g., '403 Forbidden').
              example: 403 Forbidden
            message:
              type: string
              description: A brief message denoting the type of error.
              example: Feature not enabled for workspace.
            details:
              type: object
              description: Contains granular error information including the target field and a detailed error message.
              properties:
                target:
                  type: string
                  description: The resource or feature that is forbidden.
                  example: Email Opt-in Management
                message:
                  type: string
                  description: The details of the error message.
                  example: Access to the Email Opt-in Management API is forbidden. Please enable the feature in your workspace settings.
    OptinError401Response:
      type: object
      description: This response is returned when the request does not have valid authentication credentials.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: The HTTP status code and text (e.g., '401 Unauthorized').
              example: 401 Unauthorized
            message:
              type: string
              description: A brief message denoting the type of error.
              example: Invalid API Key provided.
            details:
              type: object
              description: Contains granular error information including the target field and a detailed error message.
              properties:
                target:
                  type: string
                  description: The authentication scheme or header.
                  example: Authorization Header
                message:
                  type: string
                  description: The details of the error message.
                  example: Authentication failed due to missing or invalid credentials.
  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).

        '