JoomHelpDesk includes a full email system with two main capabilities:
- Outgoing email notifications -- Automatic emails sent to users and support handlers when ticket events occur (creation, replies, closure, forwarding, etc.).
- Email-to-ticket (incoming email) -- Incoming emails are checked from POP3 or IMAP mailboxes and converted into new tickets or ticket replies.
All email configuration is performed in the Joomla administrator backend under Components > JoomHelpDesk. The relevant sections are:
| Area | Location |
|---|---|
| Email Sending Settings | General Settings > Email Sending Settings |
| Notification Triggers | Support Settings > Emails tab |
| Email Templates | Components > JoomHelpDesk > Email Templates |
| Email Accounts (incoming) | Components > JoomHelpDesk > Email Accounts |
| Email Log | Components > JoomHelpDesk > Email Log |
Email Sending Configuration
JoomHelpDesk can send emails using either the Joomla global mail configuration or its own independent mail settings. This is configured under General Settings > Email Sending Settings.
Using Joomla Default Settings vs. Overriding
By default, JoomHelpDesk uses the mail settings defined in Joomla Global Configuration > Server > Mail Settings. This means whatever mailer, SMTP host, and credentials Joomla uses for system emails are also used by JoomHelpDesk.
To use separate mail settings specifically for JoomHelpDesk, enable the Override Joomla Email Settings option (email_send_override). When enabled, additional fields appear allowing you to define an independent mail configuration.
Mailer Type
When overriding Joomla settings, choose one of three mailer types (email_send_mailer):
- PHP Mail -- Uses PHP's built-in
mail()function. Requires no additional server configuration but depends on the server's local mail setup. This is the default fallback. - Sendmail -- Uses the Sendmail binary on the server. Configure the path to the Sendmail executable with the Sendmail Path setting (
email_send_sendmail_path). - SMTP -- Connects to an external SMTP server. This is the recommended option for production sites, as it provides the most reliable delivery and allows use of third-party email services (Gmail, Amazon SES, Mailgun, etc.).
SMTP Configuration
When the mailer type is set to SMTP, configure the following:
| Setting | Key | Description |
|---|---|---|
| SMTP Host | email_send_smtp_host |
The hostname or IP address of the SMTP server (e.g., smtp.gmail.com, smtp.office365.com). |
| SMTP Port | email_send_smtp_port |
The port number. Common values: 25 (unencrypted), 465 (SSL), 587 (TLS/STARTTLS). |
| SMTP Security | email_send_smtp_security |
Encryption method: None, SSL, or TLS. Use SSL for port 465 or TLS for port 587. |
| SMTP Authentication | email_send_smtp_auth |
Enable if the SMTP server requires a username and password (most do). |
| SMTP Username | email_send_smtp_username |
The login username for the SMTP server. |
| SMTP Password | email_send_smtp_password |
The login password for the SMTP server. |
From Address and Name
These settings control the sender information on outgoing emails:
- From Email (
email_send_from_email) -- The email address that appears as the sender when the override is active. - From Name (
email_send_from_name) -- The display name that appears as the sender when the override is active.
When the override is not active, JoomHelpDesk falls back to the Joomla global "From Email" and "From Name" settings. These can still be further overridden at the support level (see the section on notification settings below).
Test Email
After configuring your email settings, use the Send Test Email button to verify that JoomHelpDesk can successfully send emails. This sends a test message to confirm that the mailer, SMTP connection, authentication, and from address are all working correctly.
If the test email fails, check the Email Log (see Troubleshooting below) for details on the error.
Multiple Recipient Handling
The Email Send Multiple setting (email_send_multiple) controls how JoomHelpDesk handles emails that have more than one recipient:
| Option | Behavior |
|---|---|
Separate Emails (multi) |
Sends a separate individual email to each recipient. This is the default and recommended setting. It allows per-recipient personalization (for example, each recipient can receive an auto-login link specific to their account). |
Single To (to) |
Sends one email with all recipients in the To field. All recipients can see each other's email addresses. |
BCC (bcc) |
Sends one email with all recipients in the BCC field. Recipients cannot see each other's addresses, but per-recipient personalization (such as login codes) is not available. |
Note: When templates contain the {login_code} placeholder, JoomHelpDesk automatically switches to separate emails mode so that each recipient receives their own unique login code.
Email Notification Settings
Notification triggers and addressing options are configured under Support Settings > Emails tab. These settings control when emails are sent and who receives them.
Email Addresses
| Setting | Key | Description |
|---|---|---|
| Unassigned Ticket Email | support_email_unassigned |
Email address(es) that receive notifications for tickets with no assigned handler. Comma-separated for multiple addresses. |
| CC All Handler Emails | support_email_admincc |
An email address that is copied on all handler notification emails (e.g., a shared mailbox or manager). |
| From Address | support_email_from_address |
Overrides the from address on support emails specifically (takes priority over both Joomla and General Settings from addresses). |
| From Name | support_email_from_name |
Overrides the from name on support emails specifically. |
| Site Name Override | support_email_site_name |
Overrides the website title used in email templates (the {websitetitle} placeholder). |
The from address resolution order is:
- Support Settings from address (
support_email_from_address) if set. - General Settings override from address (
email_send_from_email) if the override is active. - Joomla Global Configuration from address.
Notification Triggers
Each trigger can be enabled or disabled independently:
| Trigger | Key | Who Is Notified | When It Fires |
|---|---|---|---|
| Email user on ticket create | support_email_on_create |
Ticket creator (user) | A user submits a new ticket |
| Email handler on ticket create | support_email_handler_on_create |
Assigned handler / admins | A user submits a new ticket |
| Email handler on pending | support_email_handler_on_pending |
Handlers / admins | A new email-to-ticket is pending approval |
| Email user on handler reply | support_email_on_reply |
Ticket creator (user) | A handler replies to a ticket |
| Email handler on user reply | support_email_handler_on_reply |
Assigned handler / admins | A user replies to a ticket |
| Email handler on forward | support_email_handler_on_forward |
New handler (and old handler) | A ticket is forwarded/reassigned to a different handler, product, or department |
| Email handler on private note | support_email_handler_on_private |
Handlers / admins | A private note is added to a ticket |
| Email user on close | support_email_on_close |
Ticket creator (user) | A handler closes a ticket |
There is also a No Dropdown option for close notifications (support_email_on_close_no_dropdown) which controls whether the close notification bypasses dropdown selection.
Email All Admins
The Email All Admins option (support_email_all_admins) sends handler notification emails to all support handlers, not just the assigned handler. This is useful for small teams where every handler should be aware of all ticket activity.
When enabled, three sub-options become available:
| Sub-option | Key | Description |
|---|---|---|
| Only Unassigned | support_email_all_admins_only_unassigned |
Only email all admins when the ticket has no assigned handler. Once a handler is assigned, only that handler receives notifications. |
| Ignore Auto-assigned | support_email_all_admins_ignore_auto |
Exclude handlers who were auto-assigned from the "all admins" list. |
| Can View Only | support_email_all_admins_can_view |
Only email admins who have permission to view the ticket (based on product, department, and category access). |
Attachments in Emails
| Setting | Key | Description |
|---|---|---|
| Attach files to user emails | support_email_file_user |
When enabled, files attached to ticket replies are included as email attachments in user notifications. Does not apply to the initial ticket creation email. |
| Attach files to handler emails | support_email_file_handler |
When enabled, files attached to ticket replies are included as email attachments in handler notifications. |
Note: Attachments are subject to a cumulative 20 MB size limit per email. Files exceeding this limit are skipped and noted in the Email Log.
Additional Options
| Setting | Key | Description |
|---|---|---|
| BCC Handler | support_email_bcc_handler |
BCC the ticket handler(s) on emails sent to the user, so handlers see what the user received. |
| Send Empty Handler Emails | support_email_send_empty_handler |
Whether to send handler notification emails even when there are no handler recipients (for logging purposes). |
Email Link Configuration
JoomHelpDesk includes ticket links in notification emails. Different links can be configured for different recipient types, allowing you to control where each type of user is directed:
| Setting | Key | Description |
|---|---|---|
| Unregistered Users Link | support_email_link_unreg |
The URL format used for ticket links sent to unregistered (guest) users. |
| Registered Users Link | support_email_link_reg |
The URL format used for ticket links sent to registered users. |
| Admin/Handler Link | support_email_link_admin |
The URL format used for ticket links sent to handlers/admins. |
| Pending Ticket Link | support_email_link_pending |
The URL format used for pending ticket approval links. |
The Remove Domain from Email Links option (support_email_no_domain) strips the domain portion from generated links, producing relative URLs instead of absolute URLs. This can be useful in certain proxy or subdomain configurations.
Email Templates
Managing Templates
Navigate to Administrator > Components > JoomHelpDesk > Email Templates to view and edit all email templates.
The template list displays the following columns:
| Column | Description |
|---|---|
| Template | The internal template identifier (e.g., email_on_create, email_on_reply). |
| Description | A human-readable description of when the template is used. |
| Subject | The current email subject line for the template. |
| Is HTML | Whether the template sends HTML or plain-text emails. |
Editing a Template
Click a template name to open the editor. Each template has the following fields:
- Template -- The internal identifier (read-only).
- Description -- A description of when the template is used (read-only).
- Is HTML -- Checkbox to toggle between HTML and plain-text mode. When HTML is enabled, a rich-text editor is provided for the template body. When disabled, a plain textarea is shown.
- Subject -- The email subject line. Supports placeholders (see below).
- Template Body -- The email body content. Supports placeholders and conditional logic.
- Help -- Contextual help showing which placeholders are available for the specific template type.
Multi-language Support
Email templates support translation into multiple languages. When multiple languages are installed in Joomla, the template editor shows translation fields for each language. The correct language version of a template is selected automatically based on:
- The ticket's language setting (if available and matches the recipient).
- The recipient user's Joomla language preference.
- The default template content as a fallback.
Template Types
JoomHelpDesk includes templates for each notification event:
| Template ID | Purpose |
|---|---|
email_on_create |
Confirmation sent to registered users when they create a ticket |
email_on_create_unreg |
Confirmation sent to unregistered users when they create a ticket |
email_on_reply |
Notification sent to the user when a handler replies |
email_on_close |
Notification sent to the user when a ticket is closed |
email_on_autoclose |
Notification sent to the user when a ticket is automatically closed |
email_handler_on_create |
Notification sent to handlers when a user creates a ticket |
email_handler_on_reply |
Notification sent to handlers when a user replies |
email_handler_on_forward |
Notification sent to handlers when a ticket is forwarded/reassigned |
email_handler_on_private |
Notification sent to handlers when a private note is added |
email_handler_on_pending |
Notification sent to handlers when an email-to-ticket is pending approval |
email_unreg_passwords |
Sends ticket reference and password list to unregistered users |
comment |
Comment notification email |
messagerow |
Sub-template used to format individual messages within the message history |
Available Placeholders
Placeholders use the {placeholder_name} syntax in both the subject and body of templates.
Ticket Information:
| Placeholder | Description |
|---|---|
{ticket_id} |
The numeric ticket ID |
{ref} or {reference} |
The ticket reference code |
{subject} |
The ticket subject/title (may include a link in HTML templates) |
{subject_text} |
The ticket subject/title as plain text |
{body} |
The message body content |
{status} |
The current ticket status |
{status_text} |
The ticket status as plain text |
{priority} |
The ticket priority |
{priority_text} |
The ticket priority as plain text |
{product} |
The product name |
{product_desc} |
The product description (plain text) |
{product_desc_html} |
The product description (HTML) |
{department} |
The department name |
{department_desc} |
The department description (plain text) |
{department_desc_html} |
The department description (HTML) |
{category} |
The category name |
{opened} |
The date/time the ticket was opened |
{closed} |
The date/time the ticket was closed |
{lastactivity} |
The date/time of last activity on the ticket |
{password} |
The ticket password (for unregistered user tickets) |
{haspassword} |
Whether the system uses ticket passwords (1 or 0) |
{source} |
How the ticket was created (web, email, etc.) |
User Information:
| Placeholder | Description |
|---|---|
{user_name} or {name} |
The ticket creator's name |
{user_username} or {username} |
The ticket creator's username |
{user_email} or {email} |
The ticket creator's email address |
{user_names} |
Comma-separated list of all users associated with the ticket (including CC users) |
Handler Information:
| Placeholder | Description |
|---|---|
{handler_name} or {handlername} |
The assigned handler's name |
{handler_username} or {handlerusername} |
The assigned handler's username |
{handler_email} or {handleremail} |
The assigned handler's email address |
Sender Information (the person who triggered the email):
| Placeholder | Description |
|---|---|
{sender_name} |
Name of the person who performed the action |
{sender_email} |
Email of the person who performed the action |
{sender_username} |
Username of the person who performed the action |
Recipient Information:
| Placeholder | Description |
|---|---|
{to_name} |
Name of the email recipient |
{to_email} |
Email of the recipient |
{to_username} |
Username of the recipient |
Links:
| Placeholder | Description |
|---|---|
{ticket_link} |
Link to view the ticket (appropriate for the recipient type) |
{admin_link} |
Link to the ticket in the admin/handler view |
{email_pending_link} |
Link to approve a pending email-to-ticket |
{login_code} |
Auto-login code for the recipient (only works in separate emails mode) |
Custom Fields:
| Placeholder | Description |
|---|---|
{custom_ID} |
Value of the custom field with the given numeric ID (e.g., {custom_5}) |
{custom_ALIAS} |
Value of the custom field with the given alias (e.g., {custom_order_number}) |
{custom_ID_name} |
The display name/label of the custom field |
{custom} |
All custom field values combined |
Date/Time:
| Placeholder | Description |
|---|---|
{date} |
Current date (Y-m-d format) |
{time} |
Current time (H:i:s format) |
{current_date} |
Current date in the site's long date format |
{current_time} |
Current time in the site's short time format |
{current_datetime} |
Current date and time in the site's long datetime format |
Other:
| Placeholder | Description |
|---|---|
{websitetitle} |
The website/site name |
{messagehistory} |
Full message history for the ticket (formatted using the messagerow template) |
{last_poster} |
Name of the last person who posted on the ticket |
{last_poster_username} |
Username of the last poster |
{rating_raw} |
Numeric rating value |
{groups} |
User group names the ticket creator belongs to |
{passlist} |
List of ticket references and passwords (used in the email_unreg_passwords template) |
{time_taken} |
Formatted time spent on the ticket |
Language Strings:
Use %LANGUAGE_KEY% syntax (with percent signs) to insert translated language strings into templates.
Conditional Logic
Templates support conditional blocks using the following syntax:
{if,variable_name}
Content shown when variable has a value
{endif}
You can also test for specific values:
{if,variable_name,"value"}
Content shown when variable equals "value"
{endif}
And negative comparisons:
{if,variable_name,"value",not}
Content shown when variable does NOT equal "value"
{endif}
Conditional blocks can be nested.
Per-Product Templates
Email templates apply globally across all products. To customize email content per product, use conditional logic within templates:
{if,product,"Product A"}
Custom content for Product A tickets.
{endif}
{if,product,"Product B"}
Different content for Product B tickets.
{endif}
Email-to-Ticket (Email Accounts)
JoomHelpDesk can monitor email inboxes and automatically create tickets or add replies from incoming emails. This is configured under Administrator > Components > JoomHelpDesk > Email Accounts.
Prerequisites
- Your server must have the PHP IMAP extension (
php_imap) enabled. The Email Accounts page displays a warning if this extension is not available. Even POP3 accounts require the IMAP extension, as PHP's IMAP functions handle both protocols. - A cron job must be configured to periodically check for new emails (see Cron Configuration below).
Creating an Email Account
Click New in the toolbar to create a new email account. The following fields are available:
Connection Settings:
| Field | Description |
|---|---|
| Account Name | A descriptive name for this account (e.g., "Support Inbox"). |
| Server Address | The mail server hostname (e.g., imap.gmail.com, mail.example.com). |
| Server Type | IMAP (strongly recommended) or POP3. POP3 is provided only for compatibility and can cause email loop issues. Always use IMAP when possible. |
| Port | The mail server port. Common values: 993 (IMAP SSL), 143 (IMAP), 995 (POP3 SSL), 110 (POP3). |
| Username | The login username for the mail account. |
| Password | The login password for the mail account. |
| Use SSL | Enable for SSL-encrypted connections (typically port 993 for IMAP or 995 for POP3). |
| Use TLS | Enable for TLS-encrypted connections. |
| Validate Server Certificate | Options: Automatic, Yes, No, or Do not specify. Set to "No" if you encounter certificate validation errors with self-signed certificates. |
| Connect String Override | Advanced: A custom IMAP connection string. Only use this if you have specific connection requirements and know the correct format. |
Import Settings:
| Field | Description |
|---|---|
| Check Interval (minutes) | How often the cron job should check this account for new emails. |
| Allow Tickets From | Registered Users Only -- Only emails from addresses matching registered Joomla users create tickets. Everyone -- Emails from any address can create tickets (unregistered user tickets). |
| Allow Responses from Any Address | When enabled, replies to existing tickets are accepted from any email address, not just the original ticket creator. |
| Only Import Replies to Tickets | When enabled, no new tickets are created from incoming emails. Only replies to existing tickets are imported. |
| Confirm New Tickets | None -- Tickets created via email are immediately active. All -- All email tickets require admin approval. Only Unregistered -- Only tickets from unregistered users require approval. |
| After Importing an Email | What happens to the email on the server after it is processed: Delete or Mark as Read. For POP3 accounts, the behavior is always delete. |
| Closed Ticket Replies | Controls what happens when a reply is received for a closed ticket: Ignore the reply, Reopen the ticket, or Create a new ticket. |
| Import Emails as HTML | When enabled, the HTML content of incoming emails is preserved. Warning: Enabling this can expose your site to security issues. JoomBoost strongly recommends leaving this disabled. If enabled, you must also enable the corresponding option in the support settings. |
Ticket Defaults:
When a new ticket is created from an incoming email, these defaults are applied:
| Field | Description |
|---|---|
| Product | The default product for tickets created from this account. |
| Department | The default department. |
| Category | The default category. |
| Priority | The default priority. |
| Handler | The default handler assigned to new tickets. |
This is useful when you have separate email accounts for different products or departments -- each account can route tickets to the correct destination automatically.
Filtering:
| Field | Description |
|---|---|
| Limit to Received Address | Only process emails sent to specific addresses. Enter one address per line. Leave blank to process all emails in the inbox. |
| Ignore Sender Address | Ignore emails from specific sender addresses. Enter one address per line. Leave blank to accept from all senders. |
| Ignore Subject | Ignore emails with specific subject lines. Enter one subject per line. Useful for filtering auto-reply and bounce messages. |
| Allow from Joomla Address | When enabled, emails sent from the Joomla site's own from address are accepted. Usually disabled to prevent email loops. |
How Email-to-Ticket Works
- The cron job runs at the configured interval and connects to each published email account.
- New/unread emails are downloaded and parsed.
- The system checks if the email is a reply to an existing ticket (by matching the subject line reference code or tracking headers).
- If it is a reply, the message is added to the existing ticket. If the ticket is closed, the Closed Ticket Replies setting determines the behavior.
- If it is a new email, a new ticket is created with the configured defaults (product, department, category, priority, handler).
- The original email is deleted or marked as read on the server (depending on settings).
- Notification emails are sent to the appropriate handlers according to the notification trigger settings.
Email Trimming
When someone replies to an email, the original message is typically quoted below the reply. JoomHelpDesk includes an email trimming system that strips the quoted content to keep ticket replies clean.
The trimming rules are defined in XML files located in: components/com_joomhelpdesk/plugins/emailcheck/trim/
The default core.xml file handles common email clients. You can create additional XML files in this folder with custom trimming rules. The Email Accounts page includes a link to the Email Trimming Test tool, which lets you paste an email body and verify that your trimming rules work correctly.
Cron Configuration
Email checking requires a cron job that periodically calls the JoomHelpDesk cron URL. The Email Accounts list page displays the cron URL at the top of the page.
The cron URL format is:
https://yoursite.com/index.php?option=com_joomhelpdesk&view=cron
Configure a system cron job (or a Joomla scheduled task) to request this URL at regular intervals. A typical interval is every 5 minutes.
Example crontab entry (Linux):
*/5 * * * * wget -q -O /dev/null "https://yoursite.com/index.php?option=com_joomhelpdesk&view=cron"
From the Email Accounts list, you can also:
- Validate Account -- Test the connection to the mail server to verify credentials and connectivity.
- Run Cron Now -- Manually trigger an email check for a specific account without waiting for the cron schedule.
Troubleshooting Email Issues
Test Email Feature
The Send Test Email button in General Settings > Email Sending Settings is the first step when diagnosing email problems. If the test email fails, the issue is in your mail server configuration rather than in JoomHelpDesk's notification logic.
Email Log
Navigate to Administrator > Components > JoomHelpDesk > Email Log to view a detailed log of all emails sent and received by JoomHelpDesk.
The Email Log displays:
| Column | Description |
|---|---|
| Received | When the email event was first recorded. |
| Subject | The email subject line, including the template identifier. |
| Status | The current processing status. |
| Sender | The sender of the email (for incoming emails). |
| Last Seen | When the email was last processed. |
| Log | Detailed log information (click to view). |
The log can be filtered by account, date range, and status. Each log entry includes the full email body, recipient list, template used, and the reason each recipient was included (e.g., "Ticket Admin ID", "All admins setting", "CC all setting", "CCd on ticket").
Common Issues
SMTP Connection Failures:
- Verify the SMTP host, port, and security settings match your email provider's requirements.
- Ensure your server's firewall allows outbound connections on the configured port (25, 465, or 587).
- Try different SSL/TLS settings. Some providers require TLS on port 587, while others require SSL on port 465.
Authentication Failures:
- Double-check the SMTP username and password.
- Some providers (e.g., Gmail) require app-specific passwords when two-factor authentication is enabled.
- Some providers require you to enable "less secure app access" or generate an application-specific password.
Emails Not Being Received:
- Check the Email Log for entries. If entries exist, the email was sent by JoomHelpDesk but may be blocked by the recipient's spam filter.
- Verify the from address is a valid, existing email address. Many mail servers reject emails from non-existent senders.
- Check that notification triggers are enabled in Support Settings > Emails tab.
- Ensure the ticket has an assigned handler (or that the unassigned email address is configured).
Email-to-Ticket Not Working:
- Verify the PHP IMAP extension is installed and enabled on your server.
- Use the Validate Account button on the Email Accounts list to test connectivity.
- Check that the cron job is running. Use the Run Cron Now button to test manually.
- Check the Email Log for incoming email processing errors.
- Verify that the "Allow Tickets From" setting matches your use case (registered only vs. everyone).
Email Loops:
- If JoomHelpDesk sends a notification to an email address that is also monitored as an Email Account, a loop can occur. Use the Ignore Sender Address field on the Email Account to exclude your helpdesk's own from address.
- Disable the Allow from Joomla Address option on email accounts.
- Use IMAP instead of POP3, as IMAP has better support for tracking which emails have been processed.
Attachment Size Issues:
- JoomHelpDesk limits email attachments to a cumulative 20 MB per email. Files exceeding this limit are silently skipped. The Email Log notes which files were skipped due to size restrictions.
Recipient Limit:
- JoomHelpDesk limits each email to a maximum of 15 recipient addresses. If more recipients are needed, review your "Email All Admins" configuration and consider using a mailing list address instead.