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.'
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.
security:
- basicAuth: []
paths:
/emails/v1.0/bulk-resubscribe:
post:
tags:
- Resubscribe
summary: Bulk Resubscribe Users
description: |
This API resubscribes users who have previously unsubscribed on the MoEngage platform and an external email vendor platform simultaneously. This API resets the unsubscribe flag to “false” for users on MoEngage and makes a call to an External Service Provider (ESP) like SendGrid to remove the email addresses (associated with the unsubscribed users) from their suppression list.
operationId: bulkResubscribeUsers
x-mint:
content: |
<Note>
#### Supported ESPs
The Resubscription API currently supports only **SendGrid**.
</Note>
#### Rate Limit
The rate limit is **10 RPM** (requests per minute). The allowed volume is **14.4K** requests per day, with a maximum payload size of **100** recipient email addresses per request.
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: List of recipients to resubscribe and ESP preference.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ResubscribeRequest'
example:
recipients:
- jane@domain.com
- mike@example.com
- john.doe@example.com
update_esp: true
esp: SENDGRID
request_id: '636b77e6e2cf83277195fb60'
responses:
'202':
description: The request has been successfully submitted for asynchronous processing.
content:
application/json:
schema:
$ref: '#/components/schemas/ResubscribeSuccessResponse'
example:
message: The request is submitted successfully.
response_id: SrTuWVlPsq
'400':
description: Bad Request. Returned for issues like missing mandatory fields (e.g., `recipients`), invalid format, too many recipients (>100), or invalid ESP settings.
content:
application/json:
schema:
$ref: '#/components/schemas/ResubscribeError400Response'
examples:
missingRecipients:
summary: Missing recipients field
value:
response_id: wkskLzEMwM
error:
message: Request_Body is mandatory. Kindly add request_body and the desired fields in the API payload.
err_code: BadRequest
missingRequestId:
summary: Missing request_id field
value:
response_id: jLcIFgNqiF
error:
message: request_id - Field is required but value is None
err_code: InvalidFieldValue
tooManyRecipients:
summary: Too many recipients (>100)
value:
response_id: ofVaFGNZeU
error:
message: Payload limit is set to 100
err_code: BadRequest
invalidRecipientFormat:
summary: Invalid email format in recipients
value:
response_id: CNjLIXzCxP
error:
message: Please provide input in a valid email address format (example@domain.com) as part of 'Recipients'.
err_code: InvalidInput
emptyRecipients:
summary: Empty recipients array
value:
response_id: VkJTiAOgxt
error:
message: Add at least one email address as part of the 'Recipients'
err_code: InvalidInput
invalidEspSettings:
summary: Invalid Email Connector Settings
description: Occurs if the configured ESP settings are incorrect or the ESP is not SendGrid when `update_esp` is true.
value:
response_id: GENERATED_ID
error:
message: Valid email settings not present
err_code: InvalidSettings # FIXME: Confirm actual error code
'401':
description: Authorization Failure. Returned for issues like `MOE-APPKEY` header mismatch with Basic Auth username, missing Basic Auth credentials, or invalid authentication type.
content:
application/json:
schema:
$ref: '#/components/schemas/ResubscribeError401Response'
examples:
headerMismatch:
summary: MOE-APPKEY mismatch
value:
response_id: YNJhkZzfqt
error:
message: MOE_APPKEY doesn't match the Username (APP_KEY) used in Basic Auth authorization.
err_code: HeaderMismatch
missingPassword:
summary: Missing password in Basic Auth
value:
response_id: dKzDpSIiCG
error:
message: Password (APP_SECRET) is missing in the Basic Auth authorization.
err_code: AuthenticationMissing
'405':
description: Method Not Allowed. Returned when a method other than POST is used (e.g., GET).
content:
application/json:
schema:
$ref: '#/components/schemas/ResubscribeError405Response'
example:
response_id: GudkCOBkHT
error:
message: This API only supports the POST method. Kindly update the method and retry again.
err_code: MethodNotAllowed
'415':
description: Unsupported Media Type. Returned when the `Content-Type` header is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ResubscribeError415Response'
example:
response_id: quUXnIinLK
error:
message: The header 'Content-Type' is missing. Kindly provide the header 'Content-Type' and set it as 'application/json'
err_code: HeaderMissing
'429':
description: Rate Limit Breach. The request rate has exceeded the limit of 10 RPM.
content:
application/json:
schema:
$ref: '#/components/schemas/ResubscribeError429Response'
example:
response_id: quUXnIinLK
error:
message: Rate limit exceeded
err_code: TooManyRequests
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ResubscribeError500Response'
example:
response_id: quUXnIinLK
error:
message: Please Contact Moengage Team
err_code: INTERNAL_SERVER_ERROR
/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:
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).
schemas:
# Resubscribe Schemas
ResubscribeRequest:
type: object
required:
- recipients
- esp
- request_id
properties:
recipients:
type: string
description: 'This field contains the email ids of the users who have resubscribed.
**Note:** If an email address matches multiple profiles, all the profiles will be marked as resubscribed on the MoEngage dashboard (the unsubscribe flag will be set to false for the user).'
example: ["john@example.com", "mike@example.com"]
customer_id:
type: string
description: 'This field denotes the unique identifier used to identify a user in MoEngage. Note that devices can be created for existing users only.'
esp:
type: string
description: 'This field contains information about the Email Service Provider (esp) whose suppression list needs to be updated. For example, “esp”: “SENDGRID” would imply that the email address of the customers who have resubscribed to your brand need to be removed from SendGrid’s suppression list.'
update_esp:
type: boolean
description: 'This field’s default value is false when it is not sent in the request payload. MoEngage calls the ESP to remove the email addresses from their email suppression list when this field is true.'
request_id:
type: string
description: 'This field contains the value of the identifier for the request.'
ResubscribeSuccessResponse:
type: object
description: Success response body for the Bulk Resubscribe API (202 Accepted).
properties:
message:
type: string
description: This field contains a brief description of the request status.
example: The request is submitted successfully.
response_id:
type: string
description: This field contains the unique identifier for the response and is present in the response only when the request is successful.
example: SrTuWVlPsq
ResubscribeError400Response:
type: object
description: This response is returned when the `recipients` field is not present in the request body (400 Bad Request).
properties:
response_id:
type: string
description: Unique identifier for the response.
error:
type: object
description: Contains the error details.
properties:
message:
type: string
description: A brief description of the error.
err_code:
type: string
description: The error code for the unsuccessful request.
ResubscribeError401Response:
type: object
description: This response is returned when the authorization fails due to invalid credentials or setup (401 Authorization Failure).
properties:
response_id:
type: string
description: Unique identifier for the response.
error:
type: object
description: Contains the error details.
properties:
message:
type: string
description: A brief description of the error.
err_code:
type: string
description: The error code for the unsuccessful request.
ResubscribeError405Response:
type: object
description: This response is returned when the wrong HTTP method is used for the API (405 Method Not Allowed).
properties:
response_id:
type: string
description: Unique identifier for the response.
error:
type: object
description: Contains the error details.
properties:
message:
type: string
description: A brief description of the error.
err_code:
type: string
description: The error code for the unsuccessful request.
ResubscribeError415Response:
type: object
description: This response is returned when the Content-Type header is missing or unsupported (415 Unsupported Media Type).
properties:
response_id:
type: string
description: Unique identifier for the response.
error:
type: object
description: Contains the error details.
properties:
message:
type: string
description: A brief description of the error.
err_code:
type: string
description: The error code for the unsuccessful request.
ResubscribeError429Response:
type: object
description: This response is returned when the number of requests has exceeded the rate limit (429 Rate Limit Breach).
properties:
response_id:
type: string
description: Unique identifier for the response.
error:
type: object
description: Contains the error details.
properties:
message:
type: string
description: A brief description of the error.
err_code:
type: string
description: The error code for the unsuccessful request.
ResubscribeError500Response:
type: object
description: This response is returned when the system runs into an unexpected error (500 Internal Server Error).
properties:
response_id:
type: string
description: Unique identifier for the response.
error:
type: object
description: Contains the error details.
properties:
message:
type: string
description: A brief description of the error.
err_code:
type: string
description: The error code for the unsuccessful request.
# Opt-in Management Schemas
OptinRequest:
type: object
description: The main wrapper object for the user preferences payload.
required:
- user_preferences
properties:
user_preferences:
$ref: '#/components/schemas/UserPreferences'
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
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 <customer_id>..."
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 t
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/moengage/refs/heads/main/openapi/moengage-email-subscription-openapi.yml