Email Optin Management API

Early Access

This is an Early Access feature. To enable it for your account, contact your CSM or raise a support ticket.

Overview

The Email Optin Management API enables you to update the users' opt-in status in MoEngage after they submit the second confirmation through MoEngage consent-seeking emails.

API Endpoint

Method: PUT

https://api-{{0X}}.moengage.com/v1/opt-in-management/user-preferences

The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage maintains different data centres for different clients. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping here.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username: password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization: Basic Base64_ENCODED_APPKEY_APIKEY=="}

You can obtain the username and password details from the MoEngage dashboard.

On the left navigation menu in the MoEngage dashboard, go to Settings > Account > APIs.
Copy the following details:
1. Username: Under Workspace ID (earlier app id), click the copy icon to copy the username.
2. Password: On the API keys section, click the copy icon in the Data tile to copy the API key.
Use these details to authenticate the API requests.

Request Headers

Key

Required

Sample Values

Description

Content-Type

Required

{"Content-Type": "application/json"}

Set the Content-Type header to application/json.

Authorization

Required

{"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"}

This authentication parameter, used for access control, must be included in the request. For more information on generating the authentication header, refer to Authentication.

MOE-APPKEY

Required

{“MOE-APPKEY”: “Workspace ID”}

This is the workspace ID (earlier APP ID) of your MoEngage workspace. You must pass the MOE-APPKEY in the request. You can find your MoEngage Workspace ID in the MoEngage dashboard:

Settings -> Account -> APIs -> Workspace ID (earlier app id)

For more information, refer to Authentication.

Request Body

{
  "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"
  }
}

Key	Data Type	Required	Description
user_preferences	JSON Object	Required	This field contains the preferences of the user. For more information, refer to User Preferences.

User Preferences

The following user preferences are tracked for the Email Optin Management API in MoEngage.

Key	Data Type	Required	Description
customer_id	String	Optional, if email_id is passed.	This field denotes the unique identifier used to identify a user in MoEngage. Note: 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.
email_id	String	Optional, if customer_id is passed.	This field denotes the email ID of the user. Note: 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.
categories	JSON Object	Optional	This field denotes the categories in your dashboard. The values of each category will be true or false based on whether the end-user subscribed to it or not. For example: "category_1": true (this user is subscribed to category_1) "category_2": false (this user is not subscribed to category_2) Note: You can pass this information if you track opt-in at the category level. If the API request has categories passed that are not active and defined in MoEngage, the entire request will not be processed.
opt_in_status	String	Required	This field denotes the opt-in status of the user. Supported values are: DOUBLE_OPTED_IN OPTED_OUT OPT_IN_PENDING 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.
channel	String	Required	This field denotes the channel that you are using. Example: email.

info

Information

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

Response Body

Status

Key

Data Type

Description

Success

message

String

This field denotes the success message.

Failure

code

String

Each error codes are unique and serve as a shorthand representation for the type of error, providing a quick reference that can be used to diagnose, troubleshoot, and address the problem based on a predefined set of error conditions.

message

String

This field contains the message that denotes the type of error.

details

JSON Object

This field contains error details.

Key	Data Type	Description
target	String	This field denotes the field where the error occurred.
message	String	This field denotes the details of the error message.

Refer to the Sample Response section for examples.

Response Codes

Status Code	Request State	Description
200	Success	This response is returned when the request is processed successfully.
400	Bad Request	This response is returned when the required parameters are missing from the request, attributes are not found, or incorrect values are passed.
401	Unauthorized	This response is returned when the request does not have valid authentication credentials.
403	Forbidden	This response is returned when the Email Opt-in Management feature is not enabled for the workspace.
429	Too Many Requests	Too Many requests, there won't be any response body for this.
500	Internal Server Error	This response is returned when the system runs into an unexpected error.

Sample Response

{
    "message": "Your request has been processed successfully"
}

{
    "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."
        }
    }
}
--------------------------------------------------------------------------------
{
    "error": {
        "code": "400 Bad Request",
        "message": "Request Data is invalid",
        "details": {
            "target": "['customerid']",
            "message": "Extra key passed in the request"
        }
    }
}
--------------------------------------------------------------------------------
{
    "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' (case-insensitive). Please provide the correct 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."
        }
    }
}
--------------------------------------------------------------------------------
{
    "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."
        }
    }
}
--------------------------------------------------------------------------------
{
    "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."
        }
    }
}
--------------------------------------------------------------------------------
{
    "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."
        }
    }
}
--------------------------------------------------------------------------------
{
    "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."
        }
    }
}
--------------------------------------------------------------------------------
{
    "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."
          }
       }
}
--------------------------------------------------------------------------------
{
    "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."
        }
    }
}
--------------------------------------------------------------------------------
{
    "message": "Sentry check failed"
}

{
    "error": {
        "code": "401 Unauthorized",
        "message": "Authentication failed.",
        "details": {
            "target": "Authorization Header",
            "message": "Authorization header is missing"
        }
    }
}
--------------------------------------------------------------------------------
{
    "error": {
        "code": "401 Unauthorized",
        "message": "Authentication failed",
        "details": {
            "target": "Authorization Header",
            "message": "Invalid Authorization type or neither username nor password provided. Please use Basic Auth with correct username and password."
        }
    }
}
-------------------------------------------------------------------------------
 {
    "error": {
        "code": "401 Unauthorized",
        "message": "Authentication failed",
        "details": {
            "target": "Authorization Header",
            "message": "Workspace ID is missing or wrong. Please provide correct Workspace ID as username."
        }
    }
}
-------------------------------------------------------------------------------
 {
    "error": {
        "code": "401 Unauthorized",
        "message": "Authentication failed",
        "details": {
            "target": "Authorization Header",
            "message": "Data API key is missing or wrong. Please provide correct Data API Key as password."
        }
    }
}
-------------------------------------------------------------------------------
 {
    "error": {
        "code": "401 Unauthorized",
        "message": "Authentication failed",
        "details": {
            "target": "MOE-APPKEY",
            "message": "Workspace ID is missing in header. Please provide correct Workspace ID in header."
        }
    }
}
--------------------------------------------------------------------------------
{
    "error": {
        "code": "401 Unauthorized",
        "message": "Authentication failed",
        "details": {
            "target": "Header Mismatch",
            "message": "Workspace ID provided in header and username is not matching. Please provide correct Workspace ID."
        }
    }
}
-------------------------------------------------------------------------------
 {
    "error": {
        "code": "401 Unauthorized",
        "message": "Authentication failed",
        "details": {
            "target": "Workspace ID",
            "message": "Workspace ID is wrong. Please provide correct Workspace ID as username."
        }
    }
}
--------------------------------------------------------------------------------
{
    "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."
        }
    }
}

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

{
     "error": {
        "code": "429 Too Many Requests"
    }
}

{
    "error": {
        "code": "500 Internal Server Error",
        "message": "Something went wrong, Please contact MoEngage Team."
    }
}

Rate Limit

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

Sample cURL Request

curl --location --globoff --request PUT 'https://api-{{0X}}.moengage.com/v1.0/opt-in-management/user-preferences' \
--header 'MOE-APPKEY: {{DATA API ID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic e3tEQVRBIEFQSSBJRH19Ont7REFUQSBBUEkgS0VZfX0=' \
--data-raw '{
	  "user_preferences": {
	    "customer_id": "ID_uid",
	    "email_id": "john@example.com",
	    "categories": {
	      "category_1": true,
	      "category_2": false
	    },
	    "opt_in_status": "DOUBLE_OPTED_IN/OPTED_OUT/OPT_IN_PENDING",
	    "channel": "email"
	  }
	}'

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

FAQs

arrow_drop_down If I track email ID across multiple user attributes, how will MoEngage identify the users to update the opt-in value when we pass the same through the Email Opt-in Management API?

The user attribute specified in the General Settings of email will be used to search for users matching the provided email ID.

arrow_drop_down What happens when both the email ID and the customer ID are passed?

Email ID is given higher priority, and MoEngage finds all users with the same email ID and updates them with the passed opt-in status value. However, if you have requested not to carry forward the opt-in status or unsubscribe information across profiles with the same email ID, MoEngage picks the customer_id and uses it to update the opt-in status.

arrow_drop_down What happens when there is more than one profile with the same Email ID? Does the Opt-in status carry forward to all such profiles?

Yes, they are carried forward by default. If User A and B have the same email ID and MoEngage received consent from A, both A and B are marked as double-opted in. This can always be controlled. To do so, contact the MoEngage team.

arrow_drop_down What happens if categories sent in the API payload are disabled or not present in the workspace?

If the API payload has even one category that is not active or present in your workspace, MoEngage throws an error and drops the request.

arrow_drop_down Is it mandatory to track Opt-in preferences at a category level?

No, it is not mandatory. If required, you can always track this at the global level.

arrow_drop_down How does this API work with API key rotation?

Suppose API key rotation is practiced, and the workspace has more than one active API key for a smoother transition. In that case, you can use any active API key associated with Email Double optin for authorization purposes.

arrow_drop_down How can I segment users whose opt-in status has been updated?

Whenever a user's opt-in status is updated using this API, the Resubscribe API, the Update Subscription Preference API, or via the end-user interaction, MoEngage raises an event called Email Optin Status Updated with the necessary information.

arrow_drop_down How do I update the opt-in status with PII Encryption or tokenization?

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.