Download the PHP package phattarachai/mail-log-laravel without Composer

Mail Log

Self-hosted outbound mail logger for Laravel. Captures every Mail::send(...) + Notification mail-channel call, groups identical sends together by Mailable class + Eloquent model, and exposes the result at a /mail-log dashboard. Ships its own Tailwind UI — no Filament, no Livewire-from-the-package, no npm install in the host.

What it gives you

• One row per template, not per send. Sending OrderShippedMail($order) to ten recipients lands as one group with sent_count=10 + ten event rows. Different Order → different group.
• A /mail-log dashboard styled like Laravel Horizon / Pulse: list of groups (last-sent first), per-group detail page with body preview (sandboxed <iframe srcdoc>, sized to the mail), Sends table with per-recipient outcomes, attachments, "Test send" modal. No third-party requests: system fonts, inlined CSS + JS.
• Per-mailable opt-in via a single trait — drop HasMailLog into a Mailable, return the originating model from mailLogModel(), return $this->withMailLog(new Headers()) from headers(). That's the whole integration surface.
• Every send settles. A send whose transport throws becomes FAILED with the exception message, whether it was a queued Mailable, a queued Notification, or a synchronous Mail::send(). A scheduled mail-log:settle-stale catches the rest (see Failed and stale sends).
• Secrets stay out of the preview. Reset tokens, signed-URL signatures and verify hashes in the stored body are masked as [redacted].
• Several models per send. Besides the primary model that groups the mail, a send can relate to any number of models (a customer, a shipment). Filter the dashboard by any of them.
• Resend from the dashboard. Mailables that opt in can be rendered again with current data and sent to the original recipients or another address.
• Nothing internal reaches the recipient. The trait's X-Mail-* headers are removed before the message is sent; each send is matched by its Message-ID, which is stored for later bounce matching.
• First-class retention. MailLogGroup implements Prunable; php artisan model:prune (daily via scheduler) cascades old groups + their events.

Install

mail-log:install is idempotent. It publishes the package config, the Spatie laravel-medialibrary migration (auto-detected when the media table is missing), and the package's own migrations, then offers to run php artisan migrate. It writes three env keys (MAIL_LOG_ENABLED, MAIL_LOG_RETENTION_DAYS, MAIL_LOG_UI_PATH) only when absent, and prints the snippets you need to paste into AppServiceProvider::boot(), a Mailable, and the scheduler.

Re-run safely. Pass --dry-run to print intended changes without writing.

After install, paste the auth gate snippet:

The default policy blocks /mail-log unless APP_DEBUG=true — loud, safe failure until you opt in.

Per-Mailable opt-in

Drop the trait into a Mailable and tell it what model originated the send:

Now every Mail::to($recipient)->send(new OrderShippedMail($order)) to ANY recipient lands in the same group; sending the same Mailable for a different Order creates a separate group.

Trait hooks

All return safe defaults — override only what you need.

Group / event model

Two tables in lock-step:

The body shown on the show page is the first send in the group — per-recipient body variation (signed URLs, magic-login tokens, personalized greetings) is NOT captured per row. The package favors fingerprint stability over body fidelity, and per-event body storage is not planned.

Recipients on the dashboard are the distinct to, cc and bcc addresses across every send in the group, in the order they were first mailed (oldest send first; within a send, to before cc before bcc). The index shows the first one plus a +N more count, so the primary recipient of the first send leads.

Sends counts every event in the group, Pending included. sent_count / failed_count only count settled outcomes.

Redacted bodies

Mail sent without the trait goes through the raw fallback path, and its body carries one recipient's secret: Laravel's ResetPassword and VerifyEmail notifications, magic-login links, any signed URL. The group stores the first send's body, so by default the listener masks these before saving:

• query values of token, signature, expires, _token, code, hash, otp (raw & or HTML-escaped &)
• the token in /password/reset/{token} and /reset-password/{token}
• the hash in /email/verify/{id}/{hash} and /verify-email/{id}/{hash}

Each becomes [redacted]. Add your own patterns under redact.patterns in config/mail-log.php (pattern => replacement), or set MAIL_LOG_REDACT_BODIES=false to store bodies verbatim. Rows stored before v0.3.0 keep their original body until they are deleted or pruned.

Model deep links

Implement MailLogLinkable on a model a Mailable returns from mailLogModel(), and the dashboard's Model column (index) and Model row (group page) link back into your app:

Models without the contract render as Order#42.

Several models per send

mailLogModel() is the primary model: it decides the group. Return further models from mailLogModels() and each send records them too:

• They are stored per send (mail_log_associations), so a group whose sends relate to different customers keeps them apart.
• They never change the fingerprint: the mail above still groups by Mailable + order.
• The group page lists every related model (linked through MailLogLinkable), and each send shows its own under the recipient.
• All mail → next to a model opens the index filtered to ?model=Type:id: every group whose primary model is that model, or that has a send related to it.

Resending

A Mailable opts in with mailLogResendable():

Each send of it then stores the Mailable itself: serialized the way a queued job is (models as identifiers, via SerializesModels) and encrypted with your APP_KEY. Resending restores it and renders it again, with the models' current data and fresh links, so it never replays the stored preview (which is the first send's, and redacted).

• Dashboard: ↻ Resend on a send in the Sends table. Keep the original recipients or enter up to 10 other addresses.
• CLI: php artisan mail-log:resend {send id} [[email protected] --to=…]. Without --to it goes to the original to, cc and bcc.

The resend is logged as a new send in the same group, marked ↻ resent, with resent_from_id pointing at the original. It goes out immediately, even for a ShouldQueue Mailable.

Things to know:

• Opt in only where resending is safe. Leave it off for mail that carries one-time secrets (login links, reset tokens) as constructor values; mail without the trait (Laravel's ResetPassword, VerifyEmail) can't be resent at all.
• A Mailable that sets its own recipients (in envelope() or build()) can only be resent to them. A resend that would reach any address you didn't choose is cancelled before it is sent, with an error.
• It can't be restored after the APP_KEY changes, the class is renamed or removed, or a model it holds is deleted; the dashboard says which.
• A Mailable holding a closure can't be serialized, and one larger than mail-log.resend.max_payload_bytes (64 KB) isn't stored; those sends show no Resend button.
• The route sits behind the same MailLog::auth() gate as the dashboard. Turn the feature off with MAIL_LOG_RESEND_ENABLED=false.

Outgoing headers and Message-ID

HasMailLog passes its metadata to the listener in X-Mail-* headers (class, model keys, fingerprint hints, the encrypted resend payload). The listener reads them and removes them before the message is handed to the transport, so recipients never see class names or record ids.

Each send is matched to its row by Message-ID: your own if the Mailable sets one (new Headers(messageId: …)), otherwise one the listener assigns. It's stored in mail_logs.message_id, which is what bounce notifications (DSNs) refer to.

Failed and stale sends

Every event starts Pending when Laravel fires MessageSending and becomes Sent on MessageSent. When the transport throws, the listener settles it as Failed with the exception message:

mail-log:settle-stale marks events still Pending after MAIL_LOG_PENDING_TIMEOUT_MINUTES (default 15) as Failed. Schedule it (see Scheduling); --minutes=N overrides the timeout for one run.

A send that another MessageSending listener cancels after Mail Log logged it also ends up Failed, since it was never delivered.

Config

See Boost skill reference.md walks every key.

Scheduling

Prune old groups daily and settle stale Pending sends every few minutes. In Laravel 12 / 13, in routes/console.php:

Or in bootstrap/app.php:

Events cascade-delete via FK when their parent group is pruned.

Dashboard language

The dashboard's labels, buttons and flash messages are in English. Dates are always in Thai format: day, Thai month abbreviation, two-digit Buddhist-era year and 24-hour time, e.g. 19 พ.ค. 69 · 15:07 for 19 May 2026, 15:07. The format is not configurable yet.

Requirements

• PHP ^8.4
• Laravel ^12 or ^13
• spatie/laravel-medialibrary ^11
• SQLite, PostgreSQL or MySQL / MariaDB (CI runs the suite on all three)

Credits

Built by Phattarachai Chaimongkol. Same shipping pattern as Laravel Horizon and Pulse — pre-built CSS + JS committed to dist/, inlined into the layout via MailLog::css() / MailLog::js() helpers, no host-side npm install required.

License

MIT. See LICENSE.

ผู้พัฒนา

พัฒนาและดูแลโดย บริษัท ภัทรชัย อาร์ทิซาน จำกัด (Phattarachai Artisan) บริษัทที่ปรึกษาและพัฒนาเว็บ ที่เรียนรู้และแบ่งปันกับชุมชน Laravel แพ็กเกจนี้แบ่งปันให้ชุมชนนำไปใช้และต่อยอดได้อย่างอิสระ

ดูแพ็กเกจอื่นของเราได้ที่ phattarachai.dev/open-source และติดต่อเราได้ที่ phattarachai.dev