---
title: Manage Email Templates
url: https://docs.kaltura.com/docs/events-collaboration/messaging-api/messaging-manage-email-templates
---

## Manage Email Templates

### 5.1 Create a Template

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

```json
{
  "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](/docs/events-collaboration/app-registry-api/app-registry-overview)) |
| `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`.

```bash
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 &lt;KS&gt;
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Template ID |

```bash
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 &lt;KS&gt;
```

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

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

```bash
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 &lt;KS&gt;
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Template ID to delete |

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