Email templates control the content and formatting of every notification email that JoomHelpDesk sends. When a ticket is created, replied to, closed, or forwarded, the system looks up the matching template, fills in placeholder variables with real ticket data, and sends the result to the appropriate recipients.
This guide covers all 13 built-in templates, every available placeholder variable, the translation system, and practical tips for customizing your helpdesk emails.
Table of Contents
- Overview
- Accessing Email Templates
- Template List
- Editing a Template
- Available Placeholder Variables
- Conditional Logic in Templates
- Multi-Language Email Templates
- Email Settings That Affect Templates
- HTML Email Formatting
- Tips and Best Practices
1. Overview
JoomHelpDesk uses a template-based email system. Each type of notification (ticket created, handler replied, ticket closed, etc.) has its own template stored in the database. Templates consist of:
- A subject line that can include placeholder variables
- A body that can be either HTML or plain text
- An HTML toggle to switch between rich and plain text formatting
- Optional translations for multi-language sites
When a notification is triggered, the system loads the matching template, replaces all {placeholder} variables with actual ticket data, and sends the email to the relevant users or handlers.
2. Accessing Email Templates
- Log in to the Joomla administrator panel
- Go to Components > JoomHelpDesk > Email Templates
The list view shows all available templates with these columns:
| Column | Description |
|---|---|
| Template | The internal template identifier (e.g., email_on_create). Click to edit. |
| Description | A human-readable explanation of when this template is used. |
| Subject | The current subject line for the email. |
| Is HTML | A tick or cross indicating whether the template sends HTML or plain text email. |
3. Template List
JoomHelpDesk includes 13 built-in email templates, organized into three categories.
Templates Sent to Users (Ticket Owners)
| Template ID | When It Is Sent |
|---|---|
email_on_create |
Sent to a registered user when they create a new ticket. Confirms the ticket was received and provides a link to view it. |
email_on_create_unreg |
Sent to an unregistered (guest) user when they create a new ticket. Similar to the above but includes the ticket password for access. |
email_on_reply |
Sent to the user when a handler replies to their ticket. |
email_on_close |
Sent to the user when a handler closes their ticket. |
email_on_autoclose |
Sent to the user when their ticket is automatically closed due to inactivity. |
email_unreg_passwords |
Sent to an unregistered user who requests a list of their tickets and access passwords. |
Templates Sent to Handlers (Admins/Staff)
| Template ID | When It Is Sent |
|---|---|
email_handler_on_create |
Sent to the assigned handler when a user creates a new ticket. Not sent if no handler is assigned. |
email_handler_on_pending |
Sent to handlers when a new ticket arrives via email and is awaiting approval before being imported. |
email_handler_on_reply |
Sent to handlers when a user replies to a ticket. |
email_handler_on_forward |
Sent to the new handler (and optionally the old handler) when a ticket is forwarded to a different handler, product, or department. |
email_handler_on_private |
Sent to CC'd handlers when someone adds a private/internal message to a ticket. |
Special Templates
| Template ID | Purpose |
|---|---|
comment |
Sent when a comment or testimonial is submitted on a knowledge base article, FAQ, or product. Can include moderation links. |
messagerow |
Not sent as a standalone email. This is a sub-template used to format individual messages when the {messagehistory} variable is included in other templates. It controls how each message in the conversation history appears. |
4. Editing a Template
Click any template name in the list to open the editor. The edit form contains the following fields:
Template (read-only)
The internal template identifier (e.g., email_on_reply). This cannot be changed.
Description (read-only)
A brief explanation of what triggers this email. This is for your reference only.
Is HTML
A checkbox that toggles between HTML and plain text mode:
- Checked: The body editor switches to the Joomla WYSIWYG editor (TinyMCE or your configured editor). The email is sent as HTML with full formatting support.
- Unchecked: The body editor switches to a plain textarea. The email is sent as plain text. Line breaks in plain text are preserved as-is.
Subject
The email subject line. You can include placeholder variables here. For example:
Re: [{reference}] {subject}
This produces a subject like: Re: [TK-00042] Cannot log in to my account
Template (Body)
The main content of the email. This is where you write the message body using placeholder variables to insert dynamic ticket data.
- In HTML mode, use the WYSIWYG editor to format text with bold, italic, links, tables, and other HTML elements.
- In plain text mode, use the textarea and rely on line breaks for formatting.
Help
At the bottom of the edit form, a help section displays the available placeholder variables for the template type you are editing. There are three help contexts:
- Support templates (most ticket-related templates) show ticket-related variables
- Comment template shows comment-specific variables
- Message row template shows message-specific variables
Translation
If your site has multiple languages installed, a translation panel appears allowing you to provide translated versions of the subject and body for each language. See Multi-Language Email Templates for details.
5. Available Placeholder Variables
Placeholder variables are written as {variable_name} in both the subject and body. When the email is sent, each placeholder is replaced with the actual value from the ticket.
Ticket Information
| Variable | Description |
|---|---|
{ticket_id} |
The numeric ticket ID in the database. |
{ref} or {reference} |
The ticket reference number (e.g., TK-00042). |
{subject} |
The ticket subject/title. In email context, this is replaced by the current message subject. |
{subject_text} |
The ticket subject as plain text (no HTML link wrapping). |
{body} |
The message body text of the current reply or ticket creation message. |
{status} |
The current ticket status name (e.g., "Open", "Closed"). |
{status_text} |
The ticket status as plain text (no color formatting). |
{status_color} |
The hex color assigned to the current status. |
{priority} |
The ticket priority name (e.g., "High", "Normal"). |
{priority_text} |
The ticket priority as plain text (no color formatting). |
{priority_color} |
The hex color assigned to the priority level. |
{source} |
The source of the ticket (e.g., web form, email). |
Product, Department, and Category
| Variable | Description |
|---|---|
{product} |
The product name associated with the ticket. |
{product_desc} |
The product description as plain text. |
{product_desc_html} |
The product description with HTML formatting preserved. |
{product_img} |
The URL to the product image, if one is set. |
{department} |
The department name associated with the ticket. |
{department_desc} |
The department description as plain text. |
{department_desc_html} |
The department description with HTML formatting preserved. |
{department_img} |
The URL to the department image, if one is set. |
{category} |
The ticket category name. |
Ticket User (Customer)
| Variable | Description |
|---|---|
{user_name} or {name} |
The full name of the ticket owner. For unregistered users, this shows the name they provided. |
{user_username} or {username} |
The Joomla username of the ticket owner. For unregistered users, shows "Unregistered". |
{user_email} or {email} |
The email address of the ticket owner. |
{user_names} |
A comma-separated list of all users associated with the ticket, including CC'd users. |
{user_id} |
The Joomla user ID of the ticket owner (0 for unregistered users). |
Ticket Handler (Staff/Admin)
| Variable | Description |
|---|---|
{handler_name} or {handlername} |
The name of the assigned handler. Shows "Unassigned" if no handler is set. |
{handler_username} or {handlerusername} |
The username of the assigned handler. |
{handler_email} or {handleremail} |
The email address of the assigned handler. |
{admin_id} |
The Joomla user ID of the assigned handler (0 if unassigned). |
Sender Information
These variables refer to whoever triggered the current email (the person who replied, closed, or forwarded the ticket):
| Variable | Description |
|---|---|
{sender_name} |
The name of the person who performed the action. |
{sender_email} |
The email address of the person who performed the action. |
{sender_username} |
The username of the person who performed the action. |
{sender_userid} |
The Joomla user ID of the sender. |
Recipient Information
These variables refer to the person currently receiving the email:
| Variable | Description |
|---|---|
{to_name} |
The name of the email recipient. Useful for personalized greetings like "Dear {to_name}". |
{to_email} |
The email address of the recipient. |
{to_username} |
The username of the recipient. |
{to_userid} |
The Joomla user ID of the recipient. |
Links
| Variable | Description |
|---|---|
{ticket_link} |
A direct URL to view the ticket on the frontend. For registered users, this links to the standard ticket view. For unregistered users, it includes the ticket password for automatic access. |
{admin_link} |
A direct URL to view the ticket in the admin/handler support panel. Used in handler-facing templates. |
{email_pending_link} |
A URL to the pending emails view in the admin panel. Used in the email_handler_on_pending template. |
Dates and Times
| Variable | Description |
|---|---|
{opened} |
The date and time when the ticket was created. |
{lastactivity} |
The date and time of the most recent activity on the ticket. |
{closed} |
The date and time when the ticket was closed (if applicable). |
{date} |
The current date (YYYY-MM-DD format). |
{time} |
The current time (HH:MM:SS format). |
{current_date} |
The current date in a localized long format. |
{current_time} |
The current time in a localized short format. |
{current_datetime} |
The current date and time in a localized long format. |
Additional Ticket Data
| Variable | Description |
|---|---|
{password} |
The ticket access password (for unregistered user tickets). |
{haspassword} |
Returns 1 if the system uses passwords for guest tickets, 0 otherwise. Useful in conditional blocks. |
{messagehistory} |
The full message history of the ticket, formatted using the messagerow sub-template. Each message shows the sender name, date, and body. |
{time_taken} |
The total time tracked on the ticket (if time tracking is enabled). |
{tags} |
A comma-separated list of tags assigned to the ticket. |
{groups} |
A comma-separated list of handler groups associated with the ticket. |
{attach_cnt} |
The number of file attachments on the ticket. |
{rating_raw} |
The numeric rating value if the ticket has been rated. |
{last_poster} |
The name of the person who posted the most recent message. |
{last_poster_username} |
The username of the most recent poster. |
{websitetitle} |
The name of your Joomla website. |
{login_code} |
An auto-login token appended to links so handlers can click through to tickets without logging in separately (when enabled in settings). This is processed per-recipient for security. |
Custom Field Variables
| Variable | Description |
|---|---|
{custom_ID} |
The value of a custom field, where ID is the numeric field ID (e.g., {custom_5}). |
{customID} |
Same as above, alternate syntax without underscore (e.g., {custom5}). |
{custom_ALIAS} |
The value of a custom field, where ALIAS is the field alias (e.g., {custom_order_number}). |
{custom_ID_name} |
The label/description of a custom field (e.g., {custom_5_name} might output "Order Number"). |
{custom} |
All custom field values concatenated together, with labels, for a summary display. |
Unregistered User Password List Variables
These apply only to the email_unreg_passwords template:
| Variable | Description |
|---|---|
{passlist} |
A formatted table (HTML) or list (plain text) of all the user's tickets with their subjects, last update dates, statuses, references, and passwords. |
Comment Template Variables
These apply only to the comment template:
| Variable | Description |
|---|---|
{title} |
The title of the comment notification. |
{article} |
The article/item title the comment was posted on. In HTML mode, this is a clickable link. |
{article_type} |
The type of content (e.g., "Product", "KB Article"). |
{name} |
The name of the commenter. |
{email} |
The email of the commenter. |
{website} |
The website URL provided by the commenter. |
{body} |
The comment body text. |
{moderated} |
Whether the comment requires moderation. |
{linkmod} |
A link to the moderation page for the comment. In HTML mode, this becomes a clickable link. |
{linkart} |
A link to the article where the comment was posted. In HTML mode, this becomes a clickable link. |
{customfields} |
All custom fields associated with the comment, formatted with labels and values. |
Message Row Template Variables
These apply only to the messagerow sub-template:
| Variable | Description |
|---|---|
{name} |
The name of the message author. |
{email} |
The email of the message author. |
{username} |
The username of the message author. |
{subject} |
The subject of the individual message. |
{posted} |
The date and time the message was posted. |
{body} |
The message body content. |
6. Conditional Logic in Templates
Templates support conditional blocks that show or hide content based on variable values. This allows you to create dynamic emails that adapt to the ticket context.
Basic If/Endif
Show content only when a variable has a value (is not empty or zero):
{if,department}
Department: {department}
{endif}
This only shows the department line if the ticket has a department assigned.
If with Value Comparison
Show content only when a variable equals a specific value:
{if,admin_id,0}
Your ticket has not yet been assigned to a handler.
{endif}
This shows the message only when admin_id is 0 (no handler assigned).
If with "Not Equal" Comparison
Show content when a variable does NOT equal a value, using the not operator:
{if,admin_id,0,not}
Your ticket has been assigned to {handler_name}.
{endif}
Nesting
Conditional blocks can be nested:
{if,department}
Department: {department}
{if,category}
Category: {category}
{endif}
{endif}
Legacy Syntax
Older templates may use {variable_start} and {variable_end} syntax. This is automatically converted to {if,variable} and {endif} at runtime. Both styles work, but the {if,...} syntax is recommended for new templates.
{haspassword_start}Your password is {password}.{haspassword_end}
Is equivalent to:
{if,haspassword}Your password is {password}.{endif}
Variable Truncation
You can truncate a variable to a maximum number of characters:
{subject,50,...}
This outputs the first 50 characters of the subject followed by "..." if it was truncated.
Setting Variables
You can define or override variables within a template:
{set,myvar,"Hello World"}
7. Multi-Language Email Templates
JoomHelpDesk automatically sends emails in the recipient's preferred language when your Joomla site has multiple languages installed.
How It Works
- When a notification is triggered, the system checks the recipient's Joomla user language preference.
- For ticket owners who are unregistered, the system uses the language the ticket was created in.
- If a translated version of the template exists for that language, it is used. Otherwise, the default template is sent.
Adding Translations
When editing a template, the translation interface appears if your site has multiple content languages installed:
- Open the email template editor
- Below the main subject and body fields, you will see a section for each installed language
- Enter the translated subject and body for each language
- Click Save
The translation data is stored as JSON in the template's translation field. Each language is identified by its tag (e.g., enGB, esES, frFR).
Translation of Dynamic Content
Template variables like {product}, {department}, {category}, {priority}, and {status} are also translated automatically. When the email is sent in a specific language, these values are looked up in their respective translation tables. This means the recipient sees product names, department names, and status labels in their own language, not just the template text.
8. Email Settings That Affect Templates
Several settings in JoomHelpDesk > Settings > Support Email control how and when templates are used. Understanding these settings helps you make the most of your templates.
From Address and Name
| Setting | Description |
|---|---|
| Email From Address | Override the sender address. Leave blank to use the Joomla default. |
| Email From Name | Override the sender name. Leave blank to use the Joomla default. |
| Override Site Name | Override the site name used in the {websitetitle} variable. |
Notification Toggles
Each template type can be enabled or disabled individually:
| Setting | Template It Controls |
|---|---|
| Email User on Ticket Create | email_on_create / email_on_create_unreg |
| Email Handler on Create | email_handler_on_create |
| Email Handler on Pending | email_handler_on_pending |
| Email User on Handler Reply | email_on_reply |
| Email Handler on User Reply | email_handler_on_reply |
| Email New Handler on Forward | email_handler_on_forward |
| Email Handlers on Private Message | email_handler_on_private |
| Email User on Close | email_on_close |
If a toggle is unchecked, that email is never sent regardless of the template content.
Recipient Controls
| Setting | Description |
|---|---|
| Unassigned Email Address | An email address that receives notifications for tickets with no handler assigned. |
| CC All Handler Emails | An additional email address that receives a copy of all handler notifications. |
| Email All Admins | When checked, all support admins receive handler notifications (not just the assigned handler). |
| Only Unassigned | Only email all admins when the ticket has no assigned handler. |
| BCC Handler on User Emails | When checked, the handler also receives a copy of emails sent to the user (reply, close notifications). |
Attachment Settings
| Setting | Description |
|---|---|
| Include Attachments for User | Attach uploaded files to emails sent to users (except on ticket creation). |
| Include Attachments for Handler | Attach uploaded files to emails sent to handlers. |
Attachments are capped at 20 MB total per email. Files exceeding this limit are skipped and logged.
Link Settings
These settings control how the {ticket_link}, {admin_link}, and {email_pending_link} variables are generated:
| Setting | Description |
|---|---|
| Unregistered User Link Itemid | A fixed Joomla menu Item ID to include in ticket links for guest users. Ensures proper routing. |
| Registered User Link Itemid | A fixed menu Item ID for registered user ticket links. |
| Admin Link Itemid | A fixed menu Item ID for handler/admin ticket links. |
| Pending Link Itemid | A fixed menu Item ID for the pending emails view link. |
| Exclude Domain from Links | When checked, generates relative URLs instead of absolute ones. |
9. HTML Email Formatting
Enabling HTML
Check the Is HTML checkbox on the template edit form to switch to HTML mode. The body editor changes to your Joomla WYSIWYG editor, giving you full control over formatting.
Recommended Practices for HTML Emails
Use inline styles. Most email clients strip <style> blocks and external CSS. Apply styles directly to elements:
<p style="font-family: Arial, sans-serif; font-size: 14px; color: #333;">
Dear {to_name},
</p>
Use tables for layout. While modern web pages use CSS Grid and Flexbox, email clients have inconsistent support for these. Simple table layouts remain the most reliable approach:
<table width="600" cellpadding="0" cellspacing="0" style="margin: 0 auto;">
<tr>
<td style="padding: 20px; background-color: #f5f5f5;">
<h2 style="margin: 0;">Ticket Update</h2>
</td>
</tr>
<tr>
<td style="padding: 20px;">
<p>Dear {to_name},</p>
<p>Your ticket <strong>[{reference}]</strong> has been updated.</p>
</td>
</tr>
</table>
Keep images absolute. If you include images, use full absolute URLs (e.g., https://yoursite.com/images/logo.png).
Test across clients. Gmail, Outlook, Apple Mail, and mobile clients all render HTML differently. Send test tickets and check the result in multiple clients.
Switching from HTML to Plain Text
If you uncheck Is HTML, the body is sent as plain text. The system automatically:
- Converts
<br />tags to newlines - Strips all remaining HTML tags
- Decodes HTML entities
If your template was previously HTML, you may need to reformat the body after switching to plain text.
10. Tips and Best Practices
Keep Subjects Informative
Include the ticket reference and subject in the email subject line so recipients can identify and thread emails:
Re: [{reference}] {subject}
This also helps email clients group related messages into conversations.
Use Conditional Blocks for Clean Output
Wrap optional fields in conditional blocks so empty values do not leave blank lines or orphaned labels:
{if,department}<p><i>Department:</i> {department}</p>{endif}
{if,category}<p><i>Category:</i> {category}</p>{endif}
{if,product}<p><i>Product:</i> {product}</p>{endif}
Differentiate User and Handler Templates
User-facing templates should be friendly, concise, and contain only information the customer needs. Handler-facing templates can include more technical detail such as the ticket source, custom field values, and internal links:
- User template: "Your ticket has been received. We will respond as soon as possible."
- Handler template: "A new ticket has been created by {user_name} ({user_username}). Product: {product}. Department: {department}."
Include Links for Quick Access
Always include {ticket_link} in user templates and {admin_link} in handler templates. This saves recipients from having to navigate to the helpdesk manually.
Test with Real Tickets
After editing a template, create a test ticket (or reply to an existing one) to verify the email looks correct. Check the email log at JoomHelpDesk > Cron Log for debugging information including the final rendered email content, recipient list, and any errors.
Custom Fields in Emails
To include a specific custom field, use its alias for readability:
<p>Order Number: {custom_order_number}</p>
Or use the numeric ID if the alias is not set:
<p>Order Number: {custom_5}</p>
You can also include the field label dynamically:
<p>{custom_5_name}: {custom_5}</p>
To include all custom fields at once, use {custom}, which outputs every field with its label.
Unregistered User Templates
The email_on_create_unreg template is critical for guest users since it contains their only means of accessing the ticket. Make sure {ticket_link} and (if passwords are enabled) {password} are prominently displayed.
Message History
Including {messagehistory} in a template embeds the full conversation history. This is helpful in reply notifications so the recipient can see context without clicking through. However, for tickets with long histories this can make emails very large. Consider whether your users benefit from seeing the full history or just the latest message via {body}.
The formatting of each message within the history is controlled by the messagerow template. Edit that template to change how individual messages appear in the conversation listing.
Email Send Mode
In JoomHelpDesk settings, the email send mode (email_send_multiple) controls how emails are delivered when there are multiple recipients:
- multi (default for templates using
{login_code}): Each recipient receives a separate email. This is required when auto-login codes are used, since each code is unique per user. - to: All recipients are listed in the To field of a single email.
- bcc: All recipients are added as BCC on a single email.
If your templates use {login_code}, the system automatically switches to individual sending for that email.