This API is used to get the subscription category preferences for a specific customer on your custom landing page.
API Endpoint
Each customer is hosted on a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping page.
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=="}
The username and password details can be obtained from the MoEngage Dashboard. We've revamped the settings UI in the Dashboard. If you're using the API for the first time, follow these steps for the revamped and old UIs:
Revamped UI
- Navigate to Settings -> Account -> APIs.
- Click Generate Key in the Data tile in the API Keys section, and click Save.
- Use the Workspace ID as the username and the Data API Key as the password to generate the authentication header.
Old UI
- Navigate to Settings -> APIs -> DATA API Settings.
- Click Generate Key.
- Click Save on the Data APIs settings section.
- Use the DATA API ID as the username and the DATA API KEY as the password to generate the authentication header.
Request Parameters
Key | Type | Value | Description |
---|---|---|---|
user_id |
Mandatory |
String |
This is the MoEngage ID that uniquely identifies the customer for whom the subscription preferences are being updated. MoEngage ID is encrypted using 16 bits DES and is encoded in the URL of the landing page. The same can be fetched from the URL of the landing page. |
cid |
Mandatory |
String |
This is the campaign id of the email campaign. This field contains the information about the email campaign received by the customer from where they have navigated to the subscription preferences page to update their preferences. The campaign ID is encrypted using 16 bits DES and is encoded in the URL of the landing page. The same can be fetched from the URL of the landing page. |
Request Headers
Key | Sample Values | Description |
---|---|---|
Content-Type |
application/json |
Set the Content-Type header to application/json for using the Bulk Update Preferences API. |
MOE-APPKEY |
{"MOE-APPKEY": "Workspace ID"} |
This is your MoEngage account's APP ID that has to be passed along with the request. You can find your MoEngage Workspace ID in the following navigation on the Dashboard: Revamped UI: Settings -> Account -> APIs -> Workspace ID Old UI: Settings -> API -> General Settings -> DATA API |
Authorization |
{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="} |
This authentication parameter, used for access control, must be passed along with the request. To generate the authentication header, refer to Authentication. |
Response Parameters
Key | Description |
---|---|
Categories |
This field contains the subscription preferences of the customer for all the categories. This is returned in case the request is processed successfully. For example, the response could be as below for a customer: { "categories": { "Promotions": true, "Updates": false, "Recommendations": true, "Newsletter": false } } category_name is the category name that is unique for every category in MoEngage. For more information, refer to Subscription Categories. You will have to map category names to display names on custom landing pages. |
title |
This field is present in the response body only when the request is unsuccessful and contains the error type. |
description |
This field is present in the response body only when the request is unsuccessful and contains the error description. |
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 APP KEY, user_id, cid, and moe_event_id are missing from the request or when the provided params are invalid. |
401 |
Authorization Failure |
This response is returned when the authorization fails due to incorrect values for the APP KEY/ HTTP Auth Header. |
409 |
API SECRET not configured |
This response is returned when the authorization fails due to the APP SECRET key not being set on the Dashboard. |
429 |
Rate Limit Breach |
This response is returned when the number of requests per minute has exceeded the rate limit. |
5xx |
Internal Server Error |
This response is returned when the system runs into an unexpected error. |
Rate Limit
The rate limit is 100 RPM and 360k per day.
Sample cURL Request
curl --location -g --request GET 'https://api-{{0X}}.moengage.com/v1/category-subscription/user-preferences?user_id={{user_id}}&cid={{cid}}' \
--header 'Content-Type: application/json' \
--header 'MOE-APPKEY: {{Workspace ID}}' \
--header 'Authorization: Basic e3tEQVRBIEFQSSBJRH19Ont7REFUQSBBUEkgS0VZfX0='
Sample Response
Success Response
{
"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
}
}
Sample Response for Bad Requests
{
"message": "Invalid Params Received"
}
Sample Response for Authorization Errors
{
title: "Authentication required",
description: "No identity information found."
}
Sample Response for Authorization Errors
{
title: "Header required",
description: "MOE-APPKEY missing in Header"
}
Sample Response for Rate Limit Breach{
title="Rate-Limit Reached",
description="Exceeded rate limit for this url"
}
Sample Response for Unknown Errors
{
title="Internal Error",
description="Please Contact Moengage Team"
}
Postman Collections
We have made it easy for you to test the APIs. Click here to view it in Postman.
FAQs
-
How do we fetch the parameters to be passed in the request?
The user_id (MoEngage ID) and the cid (Campaign ID) fields should be fetched from the landing page URL.