curl --request PATCH \
--url https://api-{dc}.moengage.com/v5/subscription-preferences \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'MOE-APPKEY: <moe-appkey>' \
--data '
{
"user_identifier_type": "email",
"user_identifier_value": "[email protected]",
"channel": "email",
"is_globally_unsubscribed": false,
"categories": {
"promotional": false,
"newsletter": true
},
"event_attributes": {
"source": "preference_center",
"campaign_ref": "spring_sale"
}
}
'{
"response_id": "resp_e474cbaf-2178-4e3a-816e-7575e1dc639b",
"type": "subscription_preference",
"data": {
"message": "Your request has been accepted and is being processed."
}
}Update Subscription Preferences (V5)
Partially updates a user’s subscription preferences. The update is processed asynchronously by a separate worker, under the same SLA already communicated for this API; a successful call returns 202 Accepted, not the updated resource.
categories is a sparse map — only the categories present in the request are changed; any category omitted is left unchanged. is_globally_unsubscribed is required on every call precisely because it has no neutral default: true unsubscribes the user from every category on the channel (and categories is ignored), while false clears any existing global unsubscribe.
curl --request PATCH \
--url https://api-{dc}.moengage.com/v5/subscription-preferences \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'MOE-APPKEY: <moe-appkey>' \
--data '
{
"user_identifier_type": "email",
"user_identifier_value": "[email protected]",
"channel": "email",
"is_globally_unsubscribed": false,
"categories": {
"promotional": false,
"newsletter": true
},
"event_attributes": {
"source": "preference_center",
"campaign_ref": "spring_sale"
}
}
'{
"response_id": "resp_e474cbaf-2178-4e3a-816e-7575e1dc639b",
"type": "subscription_preference",
"data": {
"message": "Your request has been accepted and is being processed."
}
}Rate Limit
The rate limit is 100 RPM and 360k per day.Authorizations
Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'.
- Username: Your MoEngage app key.
- Password: Your MoEngage API secret.
Transitional note: This route currently accepts Basic Auth only. Bearer token support (Authorization: Bearer <token>) is planned but not yet active here — Bearer requests return 401 until the APISIX gateway fronts this route.
For more information on authentication and getting your credentials, refer here.
Headers
This is the project ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at Settings > Account > Portfolio > Project ID. Note: This parameter is mandatory for workspaces with the Portfolio feature enabled.
Body
The identifier of the user to update and the preference changes to apply.
Response
This response is returned when the request has been accepted and queued for asynchronous processing. The update is applied by a separate worker under SLA; this response does not confirm the update has been applied yet — poll Get Subscription Preferences to check the applied state.