Unsubscribe Management - Messaging

Unsubscribe Management

CAN-SPAM compliant unsubscribe management with group-based opt-out.

10.1 List Unsubscribe Groups

List all unsubscribe groups defined across your templates:

curl -X POST "$KALTURA_MESSAGING_URL/unsubscribe-groups/list" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{}'

Groups are defined in template unsubscribeGroups arrays. This endpoint returns all unique groups.

10.2 Check User Unsubscribe Status

Get the unsubscribe groups a specific user has opted out of (requires a user-scoped KS):

curl -X POST "$KALTURA_MESSAGING_URL/unsubscribe-users/userGroupsStatus" \
  -H "Authorization: Bearer $USER_KS" \
  -H "Content-Type: application/json" \
  -d '{}'

10.3 Sync User Unsubscribe Preferences

Subscribe or unsubscribe a user from specific groups:

curl -X POST "$KALTURA_MESSAGING_URL/unsubscribe-users/syncGroups" \
  -H "Authorization: Bearer $USER_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "unsubscribed": ["marketing-emails"],
    "subscribed": ["event-updates"]
  }'

Field	Type	Description
unsubscribed	string[]	Groups to unsubscribe from
subscribed	string[]	Groups to re-subscribe to

10.4 List Unsubscribed Users

List all users who have unsubscribed from groups:

curl -X POST "$KALTURA_MESSAGING_URL/unsubscribe-users/list" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {},
    "pager": {"offset": 0, "limit": 50}
  }'

10.5 Unsubscribe URI Configuration

Configure custom unsubscribe endpoints for specific applications.

Add an Unsubscribe URI

curl -X POST "$KALTURA_MESSAGING_URL/unsubscribe-uri/add" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "appGuid": "'$APP_GUID'",
    "uri": "https://events.example.com/unsubscribe"
  }'

Field	Type	Required	Description
appGuid	string	Yes	App Registry GUID
uri	string	Yes	Custom unsubscribe endpoint URL
status	string	No	Defaults to "enabled"

Get an Unsubscribe URI

Field	Type	Required	Description
id	string	Yes	Unsubscribe URI ID

curl -X POST "$KALTURA_MESSAGING_URL/unsubscribe-uri/get" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d "{\"id\": \"$URI_ID\"}"

Response: Full unsubscribe URI object with id, appGuid, uri, status, version.

Update an Unsubscribe URI

Field	Type	Required	Description
id	string	Yes	Unsubscribe URI ID to update
uri	string	No	Updated unsubscribe endpoint URL
status	string	No	enabled, disabled, or deleted

curl -X POST "$KALTURA_MESSAGING_URL/unsubscribe-uri/update" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d "{\"id\": \"$URI_ID\", \"uri\": \"https://events.example.com/unsubscribe-v2\"}"

Response: Updated unsubscribe URI object with incremented version.

Delete an Unsubscribe URI

Field	Type	Required	Description
id	string	Yes	Unsubscribe URI ID to delete

curl -X POST "$KALTURA_MESSAGING_URL/unsubscribe-uri/delete" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d "{\"id\": \"$URI_ID\"}"

Permanently deletes the unsubscribe URI. Subsequent get calls return a not-found error.

List Unsubscribe URIs

curl -X POST "$KALTURA_MESSAGING_URL/unsubscribe-uri/list" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"appGuidIn": ["'$APP_GUID'"]},
    "pager": {"offset": 0, "limit": 25}
  }'

Filter Fields

Field	Type	Description
idIn	string[]	Filter by URI IDs
appGuidIn	string[]	Filter by app GUIDs
uriIn	string[]	Filter by URI values
status	string	enabled, disabled, or deleted
createdAtGreaterThanOrEqual	string	ISO 8601 min date
updatedAtGreaterThanOrEqual	string	ISO 8601 min date