Manage Email Templates - Messaging

Manage Email Templates

5.1 Create a Template

POST /api/v1/email-template/add
Content-Type: application/json
Authorization: Bearer <KS>

{
  "appGuid": "app-guid-from-registry",
  "name": "Event Invitation",
  "subject": "You're invited to {eventName}",
  "body": "<html><body><p>Hi {recipient.firstName},</p><p>Join us at {eventName}!</p><p><a href='{joinLink}'>Register</a></p></body></html>",
  "toAttributePath": "{recipient.email}",
  "msgParamsMap": {
    "recipient": {"type": "User"},
    "eventName": {"type": "String"},
    "joinLink": {"type": "MagicLink"}
  },
  "unsubscribeGroups": ["event-invitations"]
}

Field	Type	Required	Description
appGuid	string	Yes	App Registry GUID (see App Registry API)
name	string	Yes	Template name
subject	string	Yes	Email subject (supports token references)
body	string	Yes	Email HTML body (supports token references)
toAttributePath	string	Yes	Token expression for recipient email
msgParamsMap	object	Yes	Token definitions (name → {type} mapping)
description	string	No	Template description
from	string	No	Sender email address
fromName	string	No	Sender display name
cc	string	No	CC email address
bcc	string	No	BCC email address
unsubscribeGroups	string[]	No	Unsubscribe group IDs
status	string	No	Defaults to "enabled"
adminTags	string	No	Comma-separated filter tags
customHeaders	object	No	Custom email headers

Response: Full template object with generated id.

curl -X POST "$KALTURA_MESSAGING_URL/email-template/add" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "appGuid": "'$APP_GUID'",
    "name": "Event Invitation",
    "subject": "Join us at {eventName}",
    "body": "<p>Hi {recipient.firstName}, you are invited to {eventName}.</p>",
    "toAttributePath": "{recipient.email}",
    "msgParamsMap": {
      "recipient": {"type": "User"},
      "eventName": {"type": "String"}
    }
  }'

Save the id from the response as TEMPLATE_ID.

5.2 Get a Template

POST /api/v1/email-template/get
Content-Type: application/json
Authorization: Bearer <KS>

Field	Type	Required	Description
id	string	Yes	Template ID

curl -X POST "$KALTURA_MESSAGING_URL/email-template/get" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d "{\"id\": \"$TEMPLATE_ID\"}"

Response: Full template object (see section 3 for field definitions).

5.3 Update a Template

POST /api/v1/email-template/update
Content-Type: application/json
Authorization: Bearer <KS>

Field	Type	Required	Description
id	string	Yes	Template ID to update
name	string	No	Updated name
subject	string	No	Updated subject
body	string	No	Updated HTML body
description	string	No	Updated description
from	string	No	Updated sender email
fromName	string	No	Updated sender display name
cc	string	No	Updated CC address
bcc	string	No	Updated BCC address
msgParamsMap	object	No	Updated token definitions
unsubscribeGroups	string[]	No	Updated unsubscribe group IDs
status	string	No	enabled, disabled, or deleted
adminTags	string	No	Updated admin tags
customHeaders	object	No	Updated custom headers

curl -X POST "$KALTURA_MESSAGING_URL/email-template/update" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"$TEMPLATE_ID\",
    \"subject\": \"Updated: Join us at {eventName}\",
    \"description\": \"Updated event invitation template\"
  }"

Fields not included remain unchanged. The version increments on each update.

Response: Full updated template object with incremented version.

5.4 List Templates

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

Filter Fields

Field	Type	Description
idIn	string[]	Filter by template IDs
appGuidIn	string[]	Filter by App Registry GUIDs
name	string	Filter by name substring
nameEq	string	Filter by exact name match
subject	string	Filter by subject substring
status	string	enabled, disabled, or deleted
adminTags	string	Filter by admin tags substring
adminTagsAll	string	Match templates with all specified tags
excludeAdminTags	string	Exclude templates with these tags
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

Pager

Field	Type	Default	Description
offset	integer	0	Records to skip
limit	integer	30	Max records to return

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

5.5 Delete a Template

POST /api/v1/email-template/delete
Content-Type: application/json
Authorization: Bearer <KS>

Field	Type	Required	Description
id	string	Yes	Template ID to delete

curl -X POST "$KALTURA_MESSAGING_URL/email-template/delete" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d "{\"id\": \"$TEMPLATE_ID\"}"

Sets the template status to deleted. The template is excluded from list results filtered by status: "enabled".