Bulk Update Subscription Preferences API

Bulk Update Preferences API helps you update the users' subscription preferences in batch mode.

API Endpoint

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

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 bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

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

  1. Navigate to Settings -> Account -> APIs.
  2. Click Generate Key in the Data tile in the API Keys section, and click Save.
  3. Use the App ID as the username and the Data API Key as the password to generate the authentication header.

Old UI

  1. Navigate to Settings -> APIs -> DATA API Settings.
  2. Click Generate Key.
  3. Click Save on the Data APIs settings section. 
  4. Use the DATA API ID as the username and the DATA API KEY as the password to generate the authentication header.

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 following navigation on the Dashboard:

Revamped UI: Settings -> Account -> APIs -> App 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.

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.

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

200 400 401 409 429 500
Success Response
{
    "message": "Your request has been processed"
}

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.
Was this article helpful?
0 out of 0 found this helpful

How can we improve this article?