How to configure Mail Catcher

Mail Catcher catches, logs and monitors every email your Joomla site sends — from the site, the administrator, the API and CLI commands. This guide covers installation and each part of the component.

• Installation
• Dashboard
• Mails list
• Reading a caught email
• Interception: log only and redirect
• Automatic clean up
• Unread counter on the dashboard
• Permissions

Installation

Download and install the Mail Catcher package using the Joomla Extension Installer, just like any other Joomla extension.

The package installs the component and three plugins, all of which are enabled automatically:

After installation you can access Mail Catcher in the Joomla back-end via the menu Components → Mail Catcher.

Dashboard

The first page you see is the Dashboard, which shows a quick overview and statistics: total mails sent, total failed, average per day, and a chart over the period you select (today, this month, last month, last 3 months, last 6 months, this year). The chart type — line, bar, horizontal bar or radar — is set in Options.

To view the list of logged emails, click the Mails button on the left side of the navigation bar.

Mails list

The Mails list shows every caught email with its sent date, sender, recipients, subject, mailer, sending status, referer, IP and ID. Unread mails are highlighted, and mails that were held back carry an Intercepted badge next to their recipients. Any files attached to a mail are listed under its subject and can be downloaded from there.

Mail Catcher records the following information for each email:

• Sent date
• Sent from email address and name
• Recipients, Cc and Bcc
• Subject
• Email content, both text and HTML
• Attachments
• Sending status: successful or failed
• Delivery status: delivered or intercepted
• Mailer: PHP Mail, SMTP or Sendmail
• Referer: where the email was sent from (component, controller)
• IP address of the user who triggered the sending

Use the search box to find mails by subject, message body, sender or IP address. A search term containing @ is matched against the recipients, Cc, Bcc and sender instead, and id:123 jumps straight to one mail. The filters narrow the list by:

• Sent status — succeeded or failed
• Intercepted — delivered or intercepted
• Read status — read or unread
• Mailer — only the mailers actually present in your log are listed
• From and To — a date range; either end can be used on its own

Select one or more mails with the checkboxes, then use the toolbar:

• Mark as read / Mark as unread — change the read status of the selected mails
• Resend — send the selected mails again
• Delete — permanently remove the selected mails, including their stored attachment files

NOTE Resend follows the interception mode configured at the time of resending. If the mode is Log only, a resent mail is logged again but still not delivered.

Reading a caught email

Click the link in the Message column — "View as HTML", or the beginning of the text for a plain mail — to open the full message in a new window. Opening a mail marks it as read.

The window starts with the sender, recipients, Cc, Bcc and sent date, and shows the error message returned by the mail server if the send failed. Below that are two tabs:

• Message — the email as the recipient would see it. HTML mail is rendered in a sandboxed frame, so a caught email can never run scripts in your administrator session.
• Headers — the raw MIME header exactly as it was sent, useful for checking From, Reply-To, Content-Type, encoding or custom headers.

The Download .eml button exports the complete raw message, which you can open in Thunderbird, Outlook or Apple Mail, or forward to a mail deliverability service for analysis. The same download is available per row in the Mails list, next to the message link.

NOTE Mails logged by very old versions of Mail Catcher, before raw MIME data was stored, cannot be exported. The download button is hidden for those rows.

Interception: log only and redirect

By default Mail Catcher logs mail and delivers it as usual. On a staging, development or cloned site that is rarely what you want, as real customers would receive test emails. Go to Components → Mail Catcher → Options → Interception to change that.

In redirect mode, set Redirect address to the address that should receive everything. Separate multiple addresses with a comma. If no valid address is given, mails are logged only. The original To, Cc and Bcc are still recorded, so the log always shows who the mail was really meant for.

Mails that were not delivered are marked Intercepted in the list and can be isolated with the Intercepted filter.

NOTE The mode applies to every email the site sends, including Joomla core mail and third party extensions. To deliver a held mail for real, switch the mode back to Log and send, then use Resend.

Automatic clean up

A busy site can log a lot of mail. The Task - Mail Catcher plugin adds a routine to the Joomla Task Scheduler that deletes old caught mails for you, together with their attachment files.

Go to System → Scheduled Tasks → New, choose Mail Catcher - Purge caught mails, give the task a title and a schedule (daily is a sensible starting point), then set the rules:

Both rules can be combined: an age of 30 with a count of 5000 keeps the last 30 days, but never more than 5000 mails. If both are 0 the task does nothing. Each run reports how many mails were deleted in the task log.

NOTE No task is created for you on installation, and the Joomla Task Scheduler needs a working trigger — a cron job (lazy scheduling is enabled by default and runs tasks on site visits).

Unread counter on the dashboard

The Quick Icon - Mail Catcher plugin puts a tile showing the number of unread caught mails on an administrator dashboard, so new or failed mail is visible without opening the component. Clicking the tile opens the Mails list already filtered to unread.

The plugin's Dashboard panel option chooses which panel the tile appears on: Third party (default), Site, System or Notifications.

Permissions

Access to Mail Catcher is controlled by the standard Joomla permissions in Options → Permissions. Caught mails contain the full body of every email your site sends, including password reset links and personal data, so grant access only to groups that need it.

Deleting mails requires the Delete permission.

NOTE If you have any questions, you can always contact us via our support ticket system which can be found under the top menu Support → Tickets.