Mail Log by asign

• Screenshots
• Requirements
• Installation
• Usage
  • Mail preview for designers
  • Retention
• Configuration
  • Redaction
• Gotchas
• Translations
• AI agents
• Testing
• Changelog
• License

A read-only log of every message your Laravel application sends, inside a Filament 5 panel. It answers "did the customer get the email, and what did it say?" without a third-party service: each message is followed from the queue to the transport (queued, sending, sent, failed), stored with its recipients, headers, bodies and attachment names, and shown in a sandboxed preview.

Secrets never reach the table: signed-link signatures, tokens, password-reset URLs and "Password: ..." lines are redacted before the copy is stored.

#Screenshots

Every message with its status (queued, sent or failed), recipient, subject and type:

A failed message keeps the transport error, the recipients and the timeline:

Signed-link signatures and reset tokens are replaced before the copy is stored:

The HTML tab renders the stored body in a sandboxed frame (no scripts, remote images off until you ask):

Dark mode:

#Requirements

• PHP 8.3+
• Laravel 12 or 13
• Filament 5

#Installation

composer require asignua/filament-mail-log

Register the plugin on your panel:

use Asignua\FilamentMailLog\MailLogPlugin;

$panel->plugin(MailLogPlugin::make());

Publish and run the migration (the table name and connection come from the config, so decide before migrating):

php artisan vendor:publish --tag=filament-mail-log-migrations
php artisan migrate

Access is closed until you open it. A stored mail can hold a one-time code or a private conversation, so with no setup nobody sees the log. Either define the gate ability:

Gate::define('viewMailLog', fn (User $user): bool => $user->isAdmin());

or pass a callback to the plugin (it wins over the gate):

MailLogPlugin::make()->authorize(fn (): bool => auth()->user()?->isAdmin() === true);

#Usage

Logging starts as soon as the package is installed; no code changes. Every Mail::send(), queued mailable and mail notification is recorded.

The list filters by status, type, recipient (To/Cc/Bcc), period and text in the body. The view page has Details, HTML (sandboxed iframe), Plain text and Headers tabs.

#Mail preview for designers

Register the messages and the page appears (same access rule as the log):

MailLogPlugin::make()
    ->previews([
        'Welcome' => fn () => new WelcomeMail(User::factory()->make()),
        'Invoice' => InvoiceMail::class,           // built by the container
    ])
    ->previewLocales(['en', 'uk']);                // default: app locale + fallback

Only registered keys can be rendered. The locale is switched for the render and restored afterwards.

#Retention

mail-log:prune deletes records older than retention_days (default 90, 0 = keep forever) in small chunks and marks sending rows nobody confirmed for stale_after_minutes as failed. It is scheduled daily at 03:40; set MAIL_LOG_SCHEDULE=false to schedule it yourself.

#Configuration

Fluent setters on MailLogPlugin: authorize(), resource(), previews(), previewPage(), previewLocales(), navigationGroup(), navigationSort(), navigationIcon().

Everything else is in the config (php artisan vendor:publish --tag=filament-mail-log-config):

#Redaction

Applied to the bodies, the subject, the header values and the error text:

• redaction.query_parameters: the value of signature, token, code, api_key, ... in any URL becomes [REDACTED] (also inside HTML, where & separates parameters).
• redaction.path_prefixes: /reset-password/{token} becomes /reset-password/[REDACTED] (also verify-email, magic-link, invitation, ...). Every segment after the prefix is removed, so /email/verify/{id}/{hash} becomes /email/verify/[REDACTED]; the query string is handled by query_parameters.
• redaction.credential_labels: Password: hunter2 keeps the label and drops the value.
• redaction.patterns: your own regexes (the whole match is replaced). Add the u flag (~…~iu) to anything that touches non-ASCII text: without it \b and /i do not see UTF-8 letters. The built-in rules and credential_labels (en, uk/ru, de, pl, es) are already UTF-8 safe.

It fails closed: a pattern that breaks at run time (PCRE backtrack limit, an invalid regex) replaces the whole text with [redaction failed]. Add the parameters of your own signed links to the list; the defaults can not know them.

#Gotchas

• A mail is missing from the log. The log lives in the process that sends: a message built with a custom transport that bypasses Illuminate\Mail\Mailer (raw Symfony mailer) fires no events. Check MAIL_LOG_ENABLED and that the migration ran: a missing table is swallowed on purpose, because the log must never stop the mail (look for filament-mail-log: could not record in your log).
• A row stays sending. The transport threw outside a queue job and the process was killed, or a worker was killed by its timeout. mail-log:prune fails such rows after stale_after_minutes.
• The recipient sees an X-Mail-Log-Id header. It is how MessageSending is tied to MessageSent (Symfony clones the message). It is a random ULID and carries nothing; rename it with the header config.
• Stored mail is still personal data. Redaction removes secrets, not names or order contents. Use body.store=false or a short retention_days where that matters.
• Mail sent inside a DB transaction keeps its log row. With connection = null the log is written on a separate connection that clones the default one (isolate_connection), so a rollback does not erase the record of a mail that already left. In-memory SQLite stays on the default connection. Side effect: a host test wrapped in a transaction does not roll the log rows back.
• A message cancelled by another MessageSending listener (one that returns false) is logged as failed with the text "cancelled by a listener, the transport threw an exception, or the process ended", because the log row is written before the other listeners run.
• Supported databases: MySQL / MariaDB, PostgreSQL and SQLite (recipient and body searches use LIKE ... ESCAPE, JSON columns are cast to text on PostgreSQL).
• Queue correlation uses the queue connection together with the job id; a job that finishes without sending closes its queued row as failed, and a job that will be retried keeps it for the next attempt.
• Attachment sizes are read only from string and file bodies; a stream attachment is never read (that would consume it), so its size stays empty.
• The preview blocks remote images. Opening a message must not fire its open-tracking pixels (that would mark it as opened and leak the admin's IP), so the policy allows data: images only. The "Load remote images" button on the message page switches to preview.csp_remote_images for that view.
• Search finds nothing in the body. The body is a long text column, so it has its own filter (not the global search); it uses LIKE, there is no full-text index.

#Translations

The interface ships in English and Ukrainian (other locales fall back to English) under the filament-mail-log::filament-mail-log namespace. A test keeps every language in step with the English keys. Override a string by publishing the translations (--tag=filament-mail-log-translations) and editing the copy in lang/vendor/filament-mail-log.

#AI agents

The package ships Laravel Boost guidelines (resources/boost/guidelines/core.blade.php) so a coding agent wires it up correctly.

#Testing

composer install
vendor/bin/phpunit
vendor/bin/phpstan analyse --memory-limit=1G
vendor/bin/pint --test

#Changelog

See CHANGELOG.md.

#License

The MIT License (MIT). See LICENSE.md.