Usage

The plugin works out of the box. It logs every mail sent from October CMS, including mail sent from other plugins and from the queue.

The log lives in Settings -> Logs -> Mail Logs. Click a record to open its preview, which shows the message details and renders the original message body.

Settings

Settings -> Logs -> Mail Log Settings.

Prune period in days

Records older than this are deleted once a day by a scheduled task. The default is 30 days; 0 or empty keeps records forever. Logged messages hold the full mail body and the recipient IP address, so keeping them indefinitely should be a deliberate choice.

Important note: For scheduled tasks to operate correctly you must set up the scheduler: https://docs.octobercms.com/4.x/setup/scheduler.html

Track when user opens email

Adds an invisible image to every HTML message to record when it is opened. Enabled by default.

Open tracking is a best-effort signal: many mail clients block remote images, and privacy proxies fetch them without the recipient reading the message. When tracking is off, the open columns and the Opened filter disappear from the list.

Maximum message size in MB

Caps the copy of the message body kept in the log; the message itself always goes out whole. The default is 1 MB, 0 keeps every body in full. Templates that inline images as base64 write megabytes into the log on every send, which is what this limit is for.

A truncated message cannot be resent, and the preview says so.

Templates whose content is not stored

Messages built from the templates named here are logged with their recipients, subject and status, but without their content. Use it for mail carrying a secret, such as the password reset link. Such a message cannot be resent.

Store attachments

Keeps a copy of every attachment sent, so it can be downloaded from the preview and included in a resend. Disabled by default.

Copies are written outside the web root, under storage/app/uploads/protected, and can only be downloaded by users with the renatio.maillog.manage_logs.attachments permission; everyone else sees the file names as plain text. Files are stored only once the mail transport has accepted the message, and images embedded with cid: are not stored. Stored files are removed together with their log record, whether it is deleted, emptied or pruned.

Maximum attachment size in MB

Attachments larger than this are not stored; only their name stays in the log. The default is 10 MB, 0 stores everything. The whole attachment is read into memory to be measured, so a generous limit needs a matching PHP memory_limit.

Delivery status

Pending is not a transient state: the message is logged just before the transport runs and marked as sent right after, so a record that is still Pending after a few minutes should be treated as not sent. It stays Pending when:

• the process died between logging and sending — a fatal error, a PHP timeout, a killed queue worker;
• a MessageSending listener, or a mailer.prepareSend listener registered after the plugin, returned false and stopped the send;
• sending threw an exception the plugin could not attribute to the send, for example one wrapped in a custom exception without the original as previous;
• the application caught the exception without reporting it, so it never reached the exception handler where the plugin records failures. A caught exception passed to report() still marks the record as Failed.

The Pending filter lists such records.

Note: A queued mailable is logged again on every attempt, so a message that fails twice before finally being delivered leaves two failed rows plus one sent row.

Resend

The preview has a Resend button for users with the renatio.maillog.manage_logs.resend permission. It sends the stored body and subject to the original To, CC and BCC recipients, with the original reply-to address and the stored attachments where available, using the mail configuration currently in effect. The original sender is not reused.

The resent message is logged as a new record that links back to the original and names who resent it; the original lists every resend.

Filters

• Template - the mail template the message was built from
• Sent / Failed / Pending - delivery outcome
• Opened - opened at least once (hidden when open tracking is off)
• Created at - a date range

The From and Last Opened columns are hidden by default; turn them on with the list setup button.

Mail Activity dashboard widget

Add it on the dashboard with Add widget -> Mail Activity. It shows the total logged, sent, opened and failed messages for the last days days (7 by default). The figures are cached for one minute.

Export

The Export all button in the list toolbar, available with the renatio.maillog.manage_logs.export permission, exports the whole log to CSV, streamed in chunks so a large log does not exhaust memory. The rows checked and the filters set on the list have no effect on it.

Permissions

renatio.maillog.manage_logs is required to reach the list at all; the other permissions gate individual actions.

Upgrading To 2.0.0

The plugin requires October CMS 4.x. If you are still running October CMS 3, stay on the 1.x branch.

Upgrading To 2.0.6

The controller action previewEmail was renamed to preview_email. Update any code that extends the MailLogs controller or links to that action directly.

Upgrading To 2.1.0

• Run php artisan october:migrate.
• Grant the new utilities.mail_logs.resend permission to the roles that should be able to resend mail.
• If you serve a mirrored public folder, run php artisan october:mirror, or the Mail Activity widget renders unstyled.

Upgrading To 2.2.0

Attachment storage is off by default. To use it, enable Store attachments in the settings and grant the new utilities.mail_logs.attachments permission to the roles that should be able to download stored files.

Upgrading To 2.3.0

Run php artisan october:migrate.

Message bodies are now capped at 1 MB in the log. Set Maximum message size in MB to 0 to keep every body in full, as before.

Upgrading To 2.4.0

Run php artisan october:migrate.

Upgrading To 3.0.0

The plugin requires PHP 8.3 or newer; upgrade the runtime before running Composer.

The permission codes changed, so run php artisan october:migrate. The migration rewrites existing grants, so nobody loses access. The permissions also moved from the Utilities tab into their own Mail Logs tab.

If your own code calls hasAccess() or userHasAccess() with one of the old codes, update those calls.

Upgrading To 3.1.0

Run php artisan october:migrate.

A resend is now logged as a record linked to its original, carrying who resent it, and the original lists every resend. The resent_at column is dropped and the resent_by values held on originals are cleared, since earlier resends cannot be matched to their originals.