Download the PHP package rudisang/laravel-mailbox without Composer

Laravel Mailbox

Laravel Mailbox is a Laravel-native local mail workbench. It captures the exact prepared RFC 822/MIME stream your application hands to the mail transport, preserves the delivery envelope and original recipient data, and gives you a private mailbox plus assertions against the final rendered result—without a daemon, Docker, or a cloud account.

The promise is a trustworthy view of the email Laravel actually generated: canonical MIME, envelope truth, secure previews, final-output assertions, and deterministic diagnostics.

[!IMPORTANT] There is no Gmail, Outlook, or Apple Mail rendering emulation. Laravel Mailbox does not promise pixel-identical rendering in any named email client.

Never enable Laravel Mailbox in production. The environment guard refuses production even if it is added to the configured environment list, and the transport throws instead of silently capturing.

At a glance:

Requirements

Laravel Mailbox requires PHP 8.2+ and supports Laravel 12 and 13. Laravel 12 (PHP 8.2–8.5) now receives security fixes only; Laravel 13 (PHP 8.3–8.5) is the actively maintained release. The package tracks the Symfony mailer/mime/html-sanitizer components each Laravel major ships with (Symfony 7.2 on Laravel 12, 7.4/8.x on Laravel 13), so your installed Symfony version always matches what Laravel itself requires. Development uses Orchestra Testbench 10/11 and Pest 4/5 — running the package's own test suite needs PHP 8.3+, even though the package installs and runs on PHP 8.2.

• PHP 8.2 or newer
• Laravel 12+
• The DOM, Fileinfo, Mbstring, PDO, PDO SQLite, and XMLWriter PHP extensions

Installation

Install the package as a development dependency:

Select the package's local transport in your application's .env file:

Package discovery registers the transport and its routes — there is nothing else to configure. Open the mailbox in your browser at your app's URL plus /_mailbox:

Then send yourself an example message straight from Tinker — paste this as-is (a small HTML order email with a plaintext fallback):

Refresh /_mailbox and the message is there — rendered HTML preview, plaintext fallback, exact raw MIME, headers and diagnostics included. Every mail your app sends from now on lands in the same place.

The package adds mail.mailers.local only when that mailer name is not already configured. Run php artisan mailbox:doctor if the UI is unavailable or messages are not captured.

To customize the defaults, publish the configuration:

What gets captured

Each successful transport handoff stores:

• the exact prepared raw message stream as raw.eml; this is the authoritative final MIME output;
• the delivery envelope sender and recipients;
• the original structured From, To, Cc, Bcc, and Reply-To fields, including Bcc before Symfony removes it from the transmitted header block;
• the subject, HTML and text alternatives, MIME tree, inline CID resources, and attachments;
• bounded Laravel execution context, test namespace, and parse status. Versioned diagnostics are derived deterministically from the capture when requested.

Arbitrary Symfony RawMessage instances are still captured as raw bytes with envelope metadata, but structured extraction is marked unsupported. The package does not implement an ad-hoc MIME parser.

The mailbox UI

The server-rendered inbox has search, unread and attachment filters, read state, delete and clear actions, and responsive two-pane navigation. A message detail view provides these tabs:

• HTML
• Text
• Headers
• Envelope
• MIME
• Raw
• Attachments
• Links
• Diagnostics

HTML previews can be switched between Phone (375 px), Tablet (768 px), and Desktop (100%) widths. The theme cycles through system, light, and dark and is remembered locally. The Message-ID in the message header is shortened to fit and copies its full value when clicked. Links and forms remain usable without JavaScript; live updates, notifications, fragment navigation, shortcuts, tabs, viewport presets, and theme switching are progressive enhancements.

Notifications

The mailbox can raise a browser notification when new mail is captured, so the tab does not have to stay in front. Notifications are off until you turn them on with the bell in the toolbar. The browser then asks for permission once, and the choice is remembered per browser; the same bell turns them off again. Each notification shows the subject and sender, and clicking it brings the mailbox forward and opens that message. While the mailbox tab is already in front only the in-page toast is shown.

Browsers only allow notifications on secure pages. localhost and 127.0.0.1 count as secure, so the Testbench workbench and most local servers work over plain HTTP. A site such as http://shop.test does not; open it over HTTPS instead (herd secure on Laravel Herd). If notifications were blocked in the browser, or the page is not secure, the bell explains what to change.

Keyboard shortcuts

Security model

Laravel Mailbox is a development tool, not a production observability service.

• Capture and routes are allowed only in the configured local and testing environments by default. MAILBOX_ENABLED=false can force the package off; no setting can force it on in production.
• Disallowed routes return 404 and the transport throws MailboxDisabledException. If the application defines a viewMailbox gate, the package also requires that gate to allow access.
• Email HTML is rendered in a separate opaque-origin iframe with an empty-token sandbox. Active markup and author-controlled resource/navigation attributes are removed, and a restrictive CSP blocks scripts, connections, forms, frames, objects, fonts, and remote resources.
• CSS is contained, not sanitized. Author CSS can affect the sandboxed preview visually, but its network fetches are blocked by the preview CSP and it cannot enter the mailbox page DOM.
• Inline display is limited to allowlisted raster images whose bytes match the detected type. Other attachments are served as application/octet-stream downloads with hardened filenames and nosniff.
• Link destinations are shown as text. Only canonical http, https, and mailto links receive an Open action, and opening one always requires a deliberate click.
• Capture and browsing do not proxy remote images or check links and do not make network requests on behalf of a message.

Captures contain secrets: bodies, addresses, subjects, attachments, links, and tokens may all be sensitive. Keep the storage private and use php artisan mailbox:clear or php artisan mailbox:prune to remove captures you no longer need.

See the security policy for the complete threat-model summary and private reporting channel.

Testing

Laravel Mailbox tests the final output at the transport boundary instead of replacing mail delivery with Mail::fake().

Add InteractsWithMailbox to a Laravel test case. Pest users can register it directly:

$this->mailbox() and the guarded global mailbox() helper return the same MailboxTester. The helper throws a clear exception if the trait has not initialized the tester.

Queries and capture lifecycle

waitForCapture is intended for queued or cross-process delivery. It polls every 50 ms and advances its high-water sequence after each successful wait, so an earlier message does not satisfy a later wait.

Assertions and their fact sources

The distinction matters for Bcc: assertBcc checks the protected original recipient data, while assertRawHeaderMissing('Bcc') checks the final raw header block.

CapturedMessage also exposes the captured facts through methods: id, seq, messageId, subject, from, to, cc, bcc, replyTo, envelopeSender, envelopeRecipients, rawHeaders, header, headers, html, text, raw, parts, attachments, attachmentContent, tags, metadata, context, parseStatus, parseError, diagnostics, and links.

parts() and attachments() return stable Rudisang\Mailbox\Storage\PartRecord value objects. The transport throws MailboxDisabledException when capture is refused by the environment guard, MessageTooLargeException when the raw-message limit is exceeded, and CaptureFailedException when capture persistence fails.

Namespaces and real queue workers

The trait sets mail.default to local, keeps a non-empty configured mailbox.namespace (including MAILBOX_NAMESPACE) or creates a fresh ULID otherwise, purges the local mailer, and restores the previous configuration during teardown. Storage remains shared, so isolation works across processes rather than hiding messages in a process-private directory.

While the guard allows capture, the package adds mailbox_namespace to Laravel queue payloads. A worker adopts that namespace for the job and restores its previous namespace after the job finishes or fails. This supports workers that were already running when the test dispatched the job. For a worker started manually outside that propagation path, start both producer and worker with the same MAILBOX_NAMESPACE value.

Queue delivery is at-least-once. If a job is retried and hands the same message to the transport more than once, every capture is kept; Laravel Mailbox does not deduplicate attempts.

Snapshots and artifacts

The snapshot methods normalize only fields whose instability is understood:

• htmlSnapshot() rewrites every cid: occurrence to stable cid:part-{n} tokens;
• textSnapshot() returns the text body verbatim;
• headersSnapshot() replaces only Message-ID and Date values;
• mimeTreeSnapshot() renders a stable tree of types, dispositions, content IDs, filenames, and decoded sizes.

Raw MIME is never normalized. Multipart boundaries remain significant in raw and header output.

Artifacts can be saved explicitly:

diagnostics() and saveDiagnostics include a rules version, capture ID, namespace, and findings. JUnit output turns error-severity findings into failures for CI. saveFixture emits portable redacted JSON without Bcc or execution context. saveEml copies the unchanged non-empty raw message.

Queues

No special Mailable API is required: queued Mailables and Notifications use Laravel's normal mail path. The queue payload namespace propagation described above associates the eventual capture with the originating test, including a real long-running worker.

Use MAILBOX_NAMESPACE when coordinating independently launched producers and workers. The value is capture metadata and an isolation key, not an authentication boundary. At-least-once queue duplicates are intentionally kept so retry behaviour remains visible.

Configuration reference

All package settings live under mailbox.* in config/mailbox.php.

Changing .env does not change a cached configuration. Rebuild or clear Laravel's configuration cache after changing any MAILBOX_* value.

Commands

Storage and retention

The default private store is storage/framework/mailbox:

Opaque ULIDs—not attachment filenames—select files on disk. Directories are created with owner-only permissions where the operating system supports POSIX modes.

Retention is enforced opportunistically after captures and explicitly by mailbox:prune. The default policy removes messages older than seven days and keeps at most 1,000 messages or 250 MiB. mailbox:clear removes the entire capture set.

Troubleshooting

Start with:

• No messages appear: confirm the application environment is local or testing, MAILBOX_ENABLED is not false, and MAIL_MAILER=local. A named mailer can also be selected explicitly with Laravel's normal Mail::mailer('local') API.
• Environment changes have no effect: run php artisan config:clear, or rebuild with php artisan config:cache after changing .env.
• The doctor reports a mailer collision: an application-defined mail.mailers.local takes precedence. Rename it or configure its transport as local deliberately.
• The doctor reports failover or round-robin composition: remove the local transport from that mailer's mailers list. A development capture transport inside failover can accept mail instead of the intended delivery transport.
• The UI returns 403: the application defines a viewMailbox gate and the current user is not allowed.
• The UI returns 404 or sends throw: the fail-closed environment guard is refusing access. Do not bypass it for production.
• Storage looks inconsistent after a crash: run php artisan mailbox:doctor --repair, then inspect the reported findings.

Alternatives

Laravel Mailbox is complementary to SMTP-focused tools such as Mailpit and Mailtrap Local. Use those tools when you need an SMTP endpoint or their broader client workflow. Use Laravel Mailbox when you want an embedded Laravel transport, final-output assertions, envelope and original-Bcc facts, test namespaces, and queue-aware diagnostics without a separate service.

You can export any capture as .eml from the UI or with saveEml() and inspect it in another tool.

Changelog

See UPGRADE.md when moving between 0.x minors.

Contributing

See the contribution guide. Before opening a pull request, run:

Please report security issues through the private channel in the security policy, not in a public issue.

License

Laravel Mailbox is open-source software licensed under the MIT License.