Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Email Templates

Email Templates in Kinesis API provide a powerful system for creating, managing, and version-controlling reusable email content. They allow you to define HTML email templates with dynamic variables, preview them in real-time, and maintain a complete history of changes.

Understanding Email Templates

Email templates in Kinesis API are sophisticated structures that include:

  • Template Content: HTML-based email body with full formatting support
  • Metadata: Name, purpose, and subject line for organizational clarity
  • Default Variables: Predefined placeholders that can be dynamically replaced when sending emails
  • Preview System: Real-time rendering with light/dark mode support
  • Content History: Full versioning and restoration capabilities for change tracking
  • Access Control: Role-based permissions to ensure only authorized users can modify templates

Email templates serve as centralized, reusable email content that can be integrated into your application’s communication workflows, ensuring consistency and allowing non-technical team members to manage email content.

Accessing Email Templates

The Email Templates page can be accessed by navigating to /web/email in your browser after logging in.

Email Templates Page

All users can view email templates, but only ROOT and ADMIN users can create, edit, or delete them.

Email Templates List Interface

The Email Templates interface includes:

  • A filterable, paginated list of all email templates
  • Template cards showing key information
  • Action buttons for various operations
  • A creation button for ROOT and ADMIN users

Each email template card displays:

  • Template name
  • Purpose/description
  • Subject line
  • Preview of the email body (truncated)
  • Action buttons (view, edit, delete)

Filtering Email Templates

To find specific email templates:

  1. Use the filter input at the top of the template list
  2. Type any part of the template name, purpose, subject, or body
  3. The list will automatically filter to show matching templates

Pagination

For systems with many email templates:

  1. Navigate between pages using the pagination controls
  2. The page displays up to 20 templates at a time by default
  3. Click page number buttons to jump to a specific page
  4. Use arrow buttons to move sequentially through pages

Creating a New Email Template

ROOT and ADMIN users can create new email templates:

  1. Click the “Create New Email Template” button on the email templates page
  2. You’ll be taken to the creation page (/web/email/create)

Create Email Template

Template Creation Interface

The creation page is divided into several sections:

1. Email Body (HTML) Editor

A full-featured HTML editor where you can write your email content:

  • Plain text input with syntax highlighting support
  • Real-time preview of rendered HTML
  • Direct HTML markup input for advanced formatting
  • Support for inline styles and semantic HTML

Tips for writing email HTML:

  • Use inline styles rather than external CSS for better email client compatibility
  • Keep layouts simple and table-based for maximum compatibility
  • Test across different email clients when possible
  • Use absolute URLs for images and links

2. Rendered Email Body (Preview)

A live preview pane that shows how your email will look:

  • Real-time rendering as you type
  • Toggle between light and dark modes using the theme button
  • Preview updates automatically with each change
  • Isolated iframe rendering for accurate display

This preview helps you see exactly how your email will appear to recipients, allowing you to catch formatting issues before deployment.

3. Properties

Essential metadata for organizing and identifying your template:

  • Name: A unique identifier for the template (e.g., welcome_email, password_reset)

    • Must be unique across all email templates
    • Use descriptive, lowercase names with underscores
    • No spaces or special characters

  • Purpose: A human-readable description of what the email is for (e.g., “Welcome new users to the platform”)

    • Helps team members understand the template’s use case
    • Searchable in the filter interface

  • Subject: The email subject line that recipients will see

    • Can include variable placeholders (e.g., “Welcome, {user_name}!”)
    • Should be concise and descriptive
    • Can be dynamically populated when sending

  • Deletable: Checkbox indicating whether this template can be deleted

    • Check this box for templates that may become obsolete
    • Uncheck for critical system templates that should be preserved
    • Only affects whether the delete button is available in the UI

4. Default Variables

Dynamic placeholders that can be replaced with actual values when sending emails:

  • Click the “+” button to add a new variable

  • Each variable has:

    • Name: The placeholder identifier (e.g., user_name, reset_link)
    • Value: Default/example value shown in preview (e.g., “John Doe”, “https://example.com/reset”)

  • Variables can be referenced in the email body and subject using your chosen templating syntax

  • Default values help you preview how the email will look with actual data

  • Remove variables by clicking the red × button on each variable row

Example Usage:

<h1>Hello, {user_name}!</h1>
<p>Click here to reset your password:</p>
<a href="{reset_link}">Reset Password</a>

Creating the Template

  1. Fill in all required fields (name, purpose, subject, body)
  2. Add any default variables needed for your template
  3. Preview the rendered output to ensure it looks correct
  4. Toggle the theme to check both light and dark mode rendering
  5. Click the “Create” button to save the template

The system will:

  1. Create the email template record
  2. Associate all default variables with the template
  3. Redirect you to the template view page upon success

Viewing Email Templates

To view the details of an email template:

  1. Click on the template name or the “View” button on the template card
  2. You’ll be taken to the template view page (/web/email/view?id=[template_id])

View Email Template

The view page displays:

  • All template metadata (name, purpose, subject)
  • The complete HTML body with live preview
  • All default variables with their names and values
  • Theme toggle for preview (light/dark mode)
  • Deletable status
  • Action buttons (edit, delete) for authorized users

Read-Only Display

All users can view email templates, but the interface is read-only for non-admin users:

  • Input fields are disabled or hidden
  • Edit and delete buttons are not shown
  • Preview is still functional for reviewing the template appearance

Editing Email Templates

ROOT and ADMIN users can edit existing email templates:

  1. From the template view page, click “Edit Email Template”
  2. Or click the “Edit” button (pencil icon) on the template card
  3. You’ll be taken to the edit page (/web/email/edit?id=[template_id])

Edit Email Template

Editing Interface

The edit page includes all the same sections as the create page:

  • HTML editor with the current email body
  • Live preview pane
  • Editable properties (name, purpose, subject, deletable)
  • Default variables management (add, edit, remove)
  • Additional content history section (see below)

Making Changes

  1. Modify any fields you want to update
  2. Add, edit, or remove default variables as needed
  3. Preview your changes in real-time
  4. Click “Update” to save your changes

The system will:

  1. Validate all fields against constraints
  2. Create a content history entry for audit purposes
  3. Update the template with new values
  4. Update all associated default variables

Content History

Email templates include a built-in versioning system that tracks all changes. The Content History section shows:

  • Timestamp: When each change was made
  • User: Who made the change (based on user ID)
  • Snapshot: The complete state of the template at that point in time
  • Restore Button: Ability to revert to any previous version

Restoring from History

To restore a previous version:

  1. Navigate to the edit page
  2. Scroll to the Content History section
  3. Click “Restore” on the version you want to revert to
  4. Confirm the restoration in the modal
  5. The template will be updated to match that historical state

📝 Note: Restoring from history creates a new content history entry, so you never lose the ability to undo changes.

Deleting Email Templates

ROOT and ADMIN users can delete email templates that are marked as deletable:

  1. Click the “Delete” button (trash icon) on the template card or view page
  2. Confirm the deletion in the modal that appears

⚠️ Warning: Deleting an email template permanently removes it and all associated default variables and content history. This action cannot be undone. Only templates marked as “deletable” can be removed.

System Templates

Templates marked as not deletable (checkbox unchecked during creation):

  • Cannot be deleted through the UI
  • Are considered critical system templates
  • Should be used for essential communication workflows
  • Can still be edited by ROOT and ADMIN users

This protection ensures that critical email templates (like password resets, account verification, etc.) are not accidentally removed.

Default Variables Management

Default variables allow email templates to be dynamic and reusable across different contexts.

Variable Structure

Each variable consists of:

  • Name: The identifier used in the template (e.g., {user_name})
  • Value: Default or example value (e.g., “John Doe”)

Adding Variables

  1. Click the “+” button in the Default Variables section
  2. Enter the variable name (typically lowercase with underscores)
  3. Enter a default/example value for preview purposes
  4. The variable can now be referenced in your email body or subject

Editing Variables

  1. Click in the name or value field of an existing variable
  2. Modify the text
  3. Click “Update” to save changes

Removing Variables

  1. Click the red × button next to the variable you want to remove
  2. The variable will be removed from the list
  3. Click “Update” to save changes

💡 Tip: Keep variable names descriptive and consistent across templates. Use a naming convention like user_name, account_email, reset_link for clarity.

Using Email Templates in Your Application

While the web interface provides management capabilities, email templates are designed to be used programmatically via the API:

  1. Fetch Template: Retrieve the template by ID or name
  2. Populate Variables: Replace placeholders with actual values
  3. Send Email: Use your email service to deliver the rendered content

The default variables serve as documentation for what data your application needs to provide when using each template.

User Permissions

Access to email template management is controlled by user roles:

RoleView TemplatesCreate TemplatesEdit TemplatesDelete Templates
ROOT✓✓✓✓
ADMIN✓✓✓✓
AUTHOR✓✗✗✗
VIEWER✓✗✗✗

🔒 Security Note: Only ROOT and ADMIN users can create, edit, or delete email templates. This ensures that communication workflows remain under the control of system administrators while allowing all team members to view templates for reference.

Email Template Lifecycle

Email templates typically follow this lifecycle:

  1. Creation: A ROOT or ADMIN user creates the template with initial content
  2. Testing: The template is tested with various variable values and in different email clients
  3. Production: The template is used in the application’s email workflows
  4. Maintenance: Updates are made over time, tracked in content history
  5. Deprecation: If no longer needed and marked deletable, the template can be removed

Best Practices

HTML Email Design

  • Keep it simple: Complex layouts may not render consistently across email clients
  • Use tables: Table-based layouts have the best email client compatibility
  • Inline styles: External stylesheets often don’t work in emails
  • Test thoroughly: Different email clients render HTML differently
  • Mobile-first: Many users read emails on mobile devices

Variable Management

  • Document variables: Use the purpose field to explain what variables are needed
  • Provide examples: Default values help developers understand expected data format
  • Be consistent: Use the same variable names across similar templates
  • Validate in code: Ensure your application validates required variables before sending

Content Management

  • Use descriptive names: Template names should clearly indicate their purpose
  • Keep purpose updated: Document any changes to the template’s use case
  • Review regularly: Periodically audit templates to remove unused ones
  • Test after changes: Always preview templates after editing
  • Leverage history: Use content history to track changes and revert if needed

Troubleshooting

Template Not Rendering Correctly

  • Check the HTML for syntax errors
  • Ensure all tags are properly closed
  • Use inline styles instead of CSS classes
  • Test the preview in both light and dark modes

Variables Not Showing in Preview

  • Verify the variable syntax matches your templating engine
  • Check that default values are set for all variables
  • Ensure variables are properly referenced in the HTML body

Cannot Delete Template

  • Verify the template is marked as “deletable”
  • Confirm you have ROOT or ADMIN role permissions
  • Check if the template is being used in active workflows