Update Subscription Preferences API

Update Preferences API helps update the subscription preferences for custom landing pages.

API Endpoint

PUT 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 Base64_ENCODED_WORKSPACEID_APIKEY=="}

The username and password details can be obtained from the MoEngage Dashboard. If you're using the API for the first time, follow these steps:

Navigate to Settings -> Account -> APIs.
Copy the following details:
- Username: Under Workspace ID (earlier app id), click the copy icon to copy the username.
- Password: In 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 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. This 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.
moe_event_id	Optional	String	This is used to update the unsubscribe event when the user chooses the unsubscribe all option.

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 at Settings -> Account -> APIs -> Workspace ID (earlier app id).

Authorization

{"Authorization: Basic Base64_ENCODED_APPKEY_APIKEY=="}

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

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 was unsuccessful and contains the error type.
description	This field is present in the response body only when the request was 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, moe_event_id, and categories 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 PUT 'https://api-{{0X}}.moengage.com/v1/category-subscription/user-preferences?user_id={{user_id}}&cid={{cid}}&moe_event_id={{moe_event_id}}' \
--header 'Content-Type: application/json' \
--header 'MOE-APPKEY: {{DATA Workspace ID}}' \
--header 'Authorization: Basic Base64_ENCODED_APPKEY_APIKEY==' \
--data-raw '{
    "unsubscribe_all": true,
    "categories": {
    	"Promotional": true,
        "Transactional": false,
        "Special Offers": true,
        "Product Updates": true,
        "New arrivals": false,
        "Recommendations": true,
        "Newsletter": true
    }
}'

Sample Response

Success Response
{
    "message": "Success"
}

Sample Response for Bad Request
{ 
    title="Internal App Key", 
    description="Valid App-Key required to process" 
}

Sample Response for Authorization Errors
{
    "title": "Header required",
    "description": "MOE-APPKEY missing in Header"
}

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.