Get Subscription Preferences API

This API is used to get the subscription category preferences for a specific customer on your custom landing page.

API Endpoint

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

1. 1. Navigate to Settings > APIs > DATA API Settings
  2. Copy the DATA API ID and DATA API KEY
  3. 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 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": "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 APP KEY and API SECRET need to be picked up from the DATA API Settings in MoEngage Dashboard, and a Basic Authorization header needs to be created and set in the header. Navigation: Settings -> API -> General Settings -> DATA API section. For more information, refer to Authentication.

Response Parameters

Key

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: {{DATA API 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

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