> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Update User Email Opt-in Preferences
> 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).
#### Rate Limit
The rate limit is **1000 RPM** (requests per minute) and **360K** requests per day.
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.
## OpenAPI
````yaml /api/email-subscription/email-subscription.yaml put /v1.0/opt-in-management/user-preferences
openapi: 3.0.3
info:
title: MoEngage Email Subscription Management APIs
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: Resubscribe
description: >-
Resubscribe users who previously unsubscribed, and optionally update the
ESP suppression list.
- 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
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 - Value
must be of type (,), passed type: : 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:
OptinRequest:
type: object
description: The main wrapper object for the user preferences payload.
required:
- user_preferences
properties:
user_preferences:
$ref: '#/components/schemas/UserPreferences'
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
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 ...
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.
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.
OptinError429Response:
description: There is no response body for this error.
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.
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.
To avoid error, make sure you pass either `customer_id` or
`email_id`.
If you are passing `customer_id`, `email_id` is not mandatory.
If you pass only `customer_id`, MoEngage finds the user with this
`customer_id` and updates the opt-in status accordingly.
Generally, 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.
`customer_id` is mandatory if you don't want to pass the opt-in
status update to all users with the same email ID.
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
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).
````