Open-Source Testing · spatie

laravel-mail-preview

Laravel Mail Preview is a lightweight PHP package that intercepts emails during development and displays them in a web browser or email client via local file storage. It provides an overlay notification when emails are sent and includes testing utilities to assert on email content without relying on Laravel's Mail::fake.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/spatie/laravel-mail-preview

1.3k

GitHub stars

Forks

PHP

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	spatie/laravel-mail-preview
Owner	spatie
Primary language	PHP
License	MIT — OSI-approved
Stars	1.3k
Forks	82
Open issues	0
Latest release	6.2.3 (2026-05-21)
Last updated	2026-05-21
Source	https://github.com/spatie/laravel-mail-preview

What laravel-mail-preview is

A custom Laravel mail transport driver that captures MIME messages (Swift_Mime_SimpleMessage) to disk as .html and .eml files, pairs with HTTP middleware to inject an overlay into web responses, and exposes a SentMails facade for test assertions against rendered email bodies. Configuration via env-gated storage paths and lifetime policies.

Quickstart

Get the laravel-mail-preview source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/spatie/laravel-mail-preview.git2cd laravel-mail-preview3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Local Development Email Verification

Preview transactional emails (password resets, invoices, order confirmations) in a real HTML/client context during development without sending to external services or staging mailboxes.

Automated Email Content Testing

Write test suites that assert on email subject, recipient, and body content without mocking the mail system, ensuring actual rendered output matches expectations before production.

QA Email Design Review

Allow non-technical team members to inspect email rendering in their browser or email client immediately after triggering code paths, accelerating feedback cycles on copy, links, and styling.

Implementation considerations

Requires explicit middleware registration in app/Http/Kernel.php and route macro addition to routes/web.php; no auto-discovery reduces risk of accidental production exposure.
Storage path must exist and be writable; 60-second default lifetime requires periodic cleanup or manual directory purging to avoid disk space exhaustion in long-running local environments.
Config enables/disables preview via APP_DEBUG flag; ensure .env is correctly set per environment to prevent accidental enablement in staging or production builds.
SentMails facade requires the package service provider to be registered; works only within Laravel test context, not in production request cycle.
Supports both HTML rendering and EML format; ensure mail templates include all inline styles or image data URIs for full fidelity in browser preview.

When to avoid it — and what to weigh

Production Environments — Package is explicitly designed for non-production use. Enabling in production will store plaintext copies of all sent emails on disk, creating data retention and privacy risks.
High-Volume Email Systems — Disk I/O overhead and 60-second default file retention may degrade performance under heavy concurrent mail sending; production SMTP or queue-based solutions are required for scale.
Sensitive Email Content — Unencrypted HTML and EML files stored in local storage_path expose email bodies (credentials, PII) if filesystem access is compromised. Not suitable for HIPAA, PCI-DSS, or similar compliance contexts.
Multi-Tenant SaaS — No built-in tenant isolation; all emails are dumped to a single storage directory by default, risking cross-tenant data leakage if multiple applications share a server.

License & commercial use

Licensed under MIT. Permissive OSI-approved license permitting commercial use, modification, and distribution with attribution and liability waiver.

MIT license permits commercial use without restriction. However, the package is development-only and unsuitable for production email handling. If bundled into a commercial product, ensure documentation and defaults prevent production deployment. No license fee or commercial support tier evident from repo data.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

Stores email bodies (including headers, recipient lists, and content) in plaintext on disk. Access controls depend on OS filesystem permissions; no encryption at rest. Disable in any environment where unauthorized disk access is plausible. Confirm storage_path is outside web root to prevent direct URL access. File lifetime should be tuned based on local development practices to avoid accumulating sensitive records.

Alternatives to consider

Laravel Mail::fake with custom assertions

Built into Laravel; requires mocking but avoids disk I/O. Trade-off: does not render actual email templates, only captures sent events.

MailHog or Mailtrap SMTP

Standalone SMTP servers that intercept and display emails in a web UI. More powerful UI, cross-language support, but adds external service dependency.

Symfony MailerLogger or debug:mailer

Symfony ecosystem equivalent; lower-level logging without overlay. Suitable if migrating off Laravel or if simpler file inspection is sufficient.

Software development agency

Build on laravel-mail-preview with DEV.co software developers

Our experienced Laravel developers can set up robust email testing infrastructure, optimize your mail pipeline, and ensure email content quality across your application.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

laravel-http-logger laravel-server-monitor jest-preview

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing Web App Development API Development Talk to DEV.co

laravel-mail-preview FAQ

Can I use this in production?

No. The package is explicitly for non-production local development. It stores unencrypted emails on disk and will degrade performance under load. Use a production SMTP or email service.

How long are preview files retained?

By default, 60 seconds (configurable via maximum_lifetime_in_seconds). After that, files are cleaned up automatically when the preview UI is accessed. Manual cleanup may be needed if the application is not used frequently.

Does this work with queued mail?

Yes. The package intercepts at the transport level, so queued jobs that send mail are captured. Middleware-based overlay display works in any web request context.

Can I customize the preview URL or styling?

Yes. The config file controls storage_path, lifetime, popup timeout, and filename format. The preview overlay and mail views can be published and customized.

Work with a software development agency

DEV.co helps companies turn open-source tools like laravel-mail-preview into production software. Our software development services cover the full lifecycle — architecture, web development, integration, and maintenance — delivered by software developers and web developers who ship. Engage our software development agency to implement or customize it for your open-source testing stack.

Need Help Integrating Email Testing into Your Laravel Workflow?

Our experienced Laravel developers can set up robust email testing infrastructure, optimize your mail pipeline, and ensure email content quality across your application.

Talk to DEV.co Schedule a Consultation