---
title: Track Messages
url: https://docs.kaltura.com/docs/events-collaboration/messaging-api/messaging-track-messages
---

## Track Messages

### 8.1 List Bulk Messages

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

#### Filter Fields

| Field | Type | Description |
|-------|------|-------------|
| `idIn` | string[] | Filter by bulk message IDs |
| `bulkIdIn` | string[] | Filter by external bulk IDs |
| `templateIdIn` | string[] | Filter by template IDs |
| `appGuidIn` | string[] | Filter by App Registry GUIDs |
| `sessionIn` | string[] | Filter by session labels |
| `statusIn` | string[] | Filter by bulk status (`sending`, `completed`, `failed`) |
| `receiverTypeIn` | string[] | Filter by receiver type (`user`, `group`) |
| `typeIn` | string[] | Filter by message type (`email`) |
| `groupIds` | string[] | Filter by group IDs |
| `userIds` | string[] | Filter by user IDs |
| `createdAtGreaterThanOrEqual` | string | ISO 8601 minimum creation date |
| `createdAtLessThanOrEqual` | string | ISO 8601 maximum creation date |
| `updatedAtGreaterThanOrEqual` | string | ISO 8601 minimum update date |
| `updatedAtLessThanOrEqual` | string | ISO 8601 maximum update date |

**Response:** `{objects: [...], totalCount: N}`

### 8.2 List Messages Grouped by Session

Group bulk messages by their `session` label for campaign-level views:

```bash
curl -X POST "$KALTURA_MESSAGING_URL/message/listGroupedBySession" \
  -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 |
|-------|------|-------------|
| `sessionIn` | string[] | Filter by session labels |
| `templateIdIn` | string[] | Filter by template IDs |
| `appGuidIn` | string[] | Filter by app GUIDs |
| `statusIn` | string[] | Filter by status |
| `adminTags` | string | Filter by admin tags substring |
| `excludeAdminTags` | string | Exclude by admin tags |
| `templateAdminTags` | string[] | Filter by template admin tags |
| `excludeTemplateAdminTags` | string[] | Exclude by template admin tags |
| `createdAtGreaterThanOrEqual` | string | ISO 8601 min date |
| `updatedAtGreaterThanOrEqual` | string | ISO 8601 min date |

### 8.3 Message Statistics

Get delivery statistics for a specific bulk message or session:

```bash
# Stats by bulk ID
curl -X POST "$KALTURA_MESSAGING_URL/message/stats" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d "{\"bulkId\": \"$BULK_ID\"}"

# Stats by session
curl -X POST "$KALTURA_MESSAGING_URL/message/stats" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d "{\"session\": \"invitation-batch-2025-q4\"}"
```

| Field | Type | Description |
|-------|------|-------------|
| `bulkId` | string | Bulk message external ID |
| `session` | string | Session label |

The response contains uppercase status keys with counts (e.g., `{"DELIVERED": 450, "BOUNCE": 3, "OPEN": 320}`).

### 8.4 Discrete Message Details

Track individual recipient delivery status:

```bash
curl -X POST "$KALTURA_MESSAGING_URL/message/listDiscreteAggregateMessages" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "sessionIn": ["invitation-batch-2025-q4"],
      "statusIn": ["bounce", "error"]
    },
    "pager": {"offset": 0, "limit": 50}
  }'
```

#### Filter Fields

| Field | Type | Description |
|-------|------|-------------|
| `appGuidIn` | string[] | Filter by app GUIDs |
| `userId` | string | Filter by specific user ID |
| `sessionIn` | string[] | Filter by session labels |
| `statusIn` | string[] | Filter by discrete status |