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

## Send Messages

### 6.1 Send to Individual Users

```
POST /api/v1/message/send
Content-Type: application/json
Authorization: Bearer <KS>
```

```json
{
  "receiverType": "user",
  "userIds": ["user1@example.com", "user2@example.com"],
  "appGuid": "app-guid-from-registry",
  "templateId": "template-id",
  "type": "email",
  "msgParams": {
    "recipient": {"type": "User", "value": "Message.userId"},
    "eventName": {"type": "String", "value": "Annual Conference 2025"},
    "joinLink": {
      "type": "MagicLink",
      "value": {
        "baseURL": "https://events.example.com/join",
        "expiry": 48,
        "privileges": "actionslimit:2"
      }
    }
  },
  "session": "invitation-batch-2025-q4"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `receiverType` | string | Yes | `"user"` or `"group"` |
| `userIds` | string[] | If user | Kaltura user IDs (email-based) |
| `groupIds` | string[] | If group | Group IDs to send to |
| `appGuid` | string | Yes | App Registry GUID |
| `templateId` | string | Yes | Email template ID |
| `type` | string | Yes | `"email"` |
| `msgParams` | object | Yes | Token values — name → `{type, value}` |
| `session` | string | No | Grouping label for tracking (e.g., `"weekly-digest"`) |
| `adminTags` | string | No | Comma-separated tags |
| `attachments` | array | No | Email attachments (see section 6.3) |
| `customHeaders` | object | No | Custom email headers (overrides template headers) |

The `msgParams` map provides runtime values for each token defined in the template's `msgParamsMap`. For `User` type tokens, set `value` to `"Message.userId"` to auto-resolve from each recipient's Kaltura profile.

**Response example:**

```json
{
  "id": "6621a3f0b2c4d5e6f7890abc",
  "bulkId": "bulk_6621a3f0",
  "partnerId": 123456,
  "appGuid": "app-guid-from-registry",
  "templateId": "template-id",
  "type": "email",
  "receiverType": "user",
  "status": "sending",
  "session": "invitation-batch-2025-q4",
  "createdAt": "2026-04-09T12:00:00.000Z",
  "updatedAt": "2026-04-09T12:00:00.000Z"
}
```

The response returns a bulk message object. The `id` is the internal message ID and `bulkId` is the external tracking identifier used with `message/stats` and `message/list`. The `status` starts as `"sending"` and transitions through the lifecycle described in section 7.

```bash
curl -X POST "$KALTURA_MESSAGING_URL/message/send" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverType": "user",
    "userIds": ["attendee@example.com"],
    "appGuid": "'$APP_GUID'",
    "templateId": "'$TEMPLATE_ID'",
    "type": "email",
    "msgParams": {
      "recipient": {"type": "User", "value": "Message.userId"},
      "eventName": {"type": "String", "value": "Q4 Town Hall"}
    }
  }'
```

### 6.2 Send to Groups

Set `receiverType` to `"group"` and provide `groupIds` instead of `userIds`:

```bash
curl -X POST "$KALTURA_MESSAGING_URL/message/send" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverType": "group",
    "groupIds": ["all-employees"],
    "appGuid": "'$APP_GUID'",
    "templateId": "'$TEMPLATE_ID'",
    "type": "email",
    "msgParams": {
      "recipient": {"type": "User", "value": "Message.userId"},
      "eventName": {"type": "String", "value": "Company All-Hands"}
    }
  }'
```

### 6.3 Attachments

Include file attachments with Base64-encoded content:

```json
{
  "attachments": [
    {
      "fileName": "agenda.pdf",
      "content": "JVBERi0xLjQKJcfs...",
      "mimeType": "application/pdf",
      "disposition": "attachment"
    }
  ]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fileName` | string | Yes | Display name of the attachment |
| `content` | string | Yes | Base64-encoded file content |
| `mimeType` | string | Yes | MIME type (e.g., `application/pdf`, `text/calendar`) |
| `disposition` | string | Yes | `"attachment"` or `"inline"` |
| `contentId` | string | No | Content ID for inline images referenced in HTML |