Send Messages - Messaging

Send Messages

6.1 Send to Individual Users

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

{
  "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:

{
  "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.

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:

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:

{
  "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