---
title: Unsubscribe Management
url: https://docs.kaltura.com/docs/events-collaboration/messaging-api/messaging-unsubscribe-management
---

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

```bash
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):

```bash
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:

```bash
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:

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

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

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

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

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

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