Bulk Update Preferences API helps you update the users' subscription preferences in batch mode.
API Endpoint
POST https://api-0X.moengage.com/v1/category-subscription/user-preferences
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
All Subscription Categories API requests will be authenticated through Basic Authentication.
To generate the Basic Authentication header:
-
-
- Navigate to Settings > APIs > DATA API Settings
- Copy the DATA API ID and DATA API KEY
- Generate the Authentication Header String
Basic Authentication encodes a 'username:password' using base64 and prepends it with the string 'Basic '. To generate the Auth header:
-
-
- Add a colon after the user name (DATA API ID) and concatenate it with the password (DATA API KEY).
- Encode the concatenated string using base64 encoding.
- Pass the encoded string in the HTTP authorization header as follows: {"Authorization":" Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}
-
-
-
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": "APP ID"} |
This is your MoEngage account's APP ID that has to be passed along with the request. You can find your MoEngage APP ID in the MoEngage Dashboard API Settings. Navigation: Settings -> API -> General Settings -> DATA API section. For more information, refer to Authentication. Note: You can also fetch the APP ID from the following navigation: Settings -> App -> General Settings. |
Authorization |
{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="} |
This is the authentication parameter for access control and needs to be passed along with the request. The APPKEY and API SECRET need to be picked up from the Inform API Settings in MoEngage Dashboard, and a Basic Authorization header needs to be created and set in the header. For more information, refer to Authentication. |
Request Body
Key | Type | Value | Description |
---|---|---|---|
channel |
Mandatory |
String |
This field contains the name of the channel. Allowed values - "channel": "email" |
data |
Mandatory |
JSON Array |
[dataobject, dataobject..] Data object - data: [ { "customer_id": "johndoe1", "categories": { "CategoryA": true, "Category B": false, "Category C": true, "Category D": true, "Category E": false }, "unsubscribe_all": true } , { "customer_id": "Test2", "categories": { "Category A": false, "Category B": false, "Category C": true, "Category D": false, "Category E": false }, "unsubscribe_all": false } ] Only those categories whose values are sent in the request get updated. If any category is not passed in the request, its status remains unchanged. We recommend you send all the categories in the request. For more information about the fields in the request, refer to the Data Object in the Request. |
Data Object
The data object contains the subscription preferences of the users. It contains the following fields:
-
-
- customer_id
This string contains the unique identifier denoting the customer for whom you are updating the subscription preferences. This is the ID on the user profile page. - categories
This is a JSON Object that contains the subscription preferences of the customer. - unsubscribe_all
This field contains information about whether or not a customer has unsubscribed from all categories. When unsubscirbe_all is true, the user is unsubscribed from all the categories, irrespective of the categories marked as true in the category JSON object. The Unsubscribe user property in the User Profile gets updated to true.
- customer_id
-
Response Parameters
Key | Description |
---|---|
message |
This field contains a brief description of the request status in the case of success. |
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 are missing from the request or when the provided parameters are invalid. |
400 |
Payload Limit Exceeded |
This response is returned when the payload size has exceeded the limit set. |
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 POST 'https://api-{{0X}}.moengage.com/v1/category-subscription/user-preferences' \
--header 'Content-Type: application/json' \
--header 'MOE-APPKEY: {{DATA API ID}}' \
--header 'Authorization: Basic e3tEQVRBIEFQSSBJRH19Ont7REFUQSBBUEkgS0VZfX0=' \
--data-raw '{
"channel": "email",
"user_preferences": [
{
"customer_id": "john@example.com",
"categories": {
"Promotional": false,
"Transactional": false,
"Special Offers": true
},
"unsubscribe_all": false
},
{
"customer_id": "mike@example.com",
"categories": {
"Transactional": true,
"Promotional": false,
"Special Offers": true
},
"unsubscribe_all": false
},
{
"customer_id": "doe@example.com",
"categories": {
"Product Updates": true,
"New arrivals": false,
"Recommendations": true
},
"unsubscribe_all": false
}
]
}'
Sample Response
Success Response
{
"message": "Your request has been processed"
}
Sample Response for Bad Requests
{
title="Categories Required",
description="Categories Preferences Required"
}
Sample Response for Requests that have exceeded the Payload Limit
{
title="Payload Limit Exceeded",
description="Payload limit is set to 50"
}
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
What is the batch size for the bulk update?
The maximum batch size is 50.