Weave Code
Laravel Mail Preview Laravel Package
spatie/laravel-mail-preview
A Laravel mail transport that previews sent mail locally. Swap your mailer's transport to 'preview' and a small overlay appears whenever a mail is sent, linking to the rendered message. Add the middleware to the web group to enable it. Handy for testing emails in local environments.
A mail driver to quickly preview mail
Frequently asked questions about Laravel Mail Preview
- How do I install spatie/laravel-mail-preview in a Laravel app?
- Install it with composer require spatie/laravel-mail-preview. Then set the transport of your local mailer to preview in config/mail.php, add Spatie\MailPreview\Http\Middleware\AddMailPreviewOverlayToResponse to the web middleware group, and register the preview route with the Route::mailPreview() macro. Publish the config and views if you want to customise the overlay, and add storage/email-previews to your .gitignore. Setup takes a few minutes plus a test email.
- What does the preview mail transport actually do?
- The package registers a custom preview transport with Laravel's MailManager, so any mail sent through a mailer configured with transport preview is rendered, written to disk as an .eml file, and announced by a small overlay containing a link to open it. Nothing leaves your machine and no SMTP server is involved. For queued mailables the preview is captured when the queue worker actually sends the message, not when it is enqueued, so run a worker locally if you rely on queues.
- Does spatie/laravel-mail-preview support Laravel 12 and 13?
- The changelog currently tops out at 6.1.0, which added Laravel 11 support, and the README's future-dated release claim should not be read as a compatibility guarantee. Verify Laravel 12 and 13 support, plus PHP 8.3 and 8.4, against the repository before you commit. Because it works through the standard Mailer and Mailable APIs, the risk is version drift rather than deep code coupling. Pin the major that matches your Laravel version and add it to your upgrade runbook.
- Is it safe to use laravel-mail-preview in production?
- No, it is a development tool and should not be enabled in production. Its enabled setting defaults to APP_DEBUG, so it self-disables when debug mode is off, but that is a configuration guard rather than a hard technical one. On a shared staging host with APP_DEBUG=true, anyone who finds the preview route could read real mail bodies, including password reset tokens and invoices. Gate the route or explicitly set enabled to false in every non-local environment.
- How do I protect the mail preview route from unauthenticated access?
- The Route::mailPreview() macro registers a public path and the README does not require authentication, so protection is your responsibility. Wrap the route in auth or a Gate, restrict it by environment, or only register it in local from a service provider. Combined with the enabled config, this keeps mail contents off shared and staging hosts. If you cannot guarantee the environment, do not enable the overlay middleware outside local.
- How does SentMails compare to Mail::fake for testing emails?
- SentMails lets you assert on the rendered content of a sent mail, including subject, from, to, cc, bcc and body substrings, which Mail::fake cannot do because it never renders the message. The two are mutually exclusive for content assertions, so pick one approach per test suite instead of mixing them. SentMails requires the preview transport to be active, and you should confirm its state stays isolated when tests run in parallel. Check that the assertion API covers the fields your tests actually need before building a suite around it.
- Can I use laravel-mail-preview alongside Mailpit, Mailhog or Mailtrap?
- Yes, it complements those tools rather than replacing them. Mailpit, Mailhog and Mailtrap give you a shared inbox UI over real SMTP, while this package adds the in-page overlay, an .eml artifact on disk, and rendered-mail assertions for tests. Many teams keep Mailpit for browsing inboxes and switch to the preview transport when they want the overlay or SentMails. Choose based on whether you need an inbox UI or in-app previews plus content assertions.
- Why is the mail preview overlay not showing on JSON or streamed responses?
- The overlay is injected by the AddMailPreviewOverlayToResponse middleware, which runs on every response in the group where you register it. That can interfere with JSON, streamed and binary responses, so confirm the package skips non-HTML content types in your version and test API endpoints after enabling it. If you hit problems, register the middleware only on the HTML routes that need it. Validating the skip logic is one of the specific risks worth tracking before rollout.
- Where are previewed emails stored and how long are they kept?
- Previewed mails are written as .eml files under storage/email-previews, so that directory must exist and be writable in local and CI containers. Cleanup is governed by maximum_lifetime_in_seconds, which defaults to 60 seconds and is often too aggressive for comfortable local use, so raise it in the published config. Publish and diff config/mail-preview.php on upgrades to catch changed defaults such as filename_date_format. Add the storage directory to .gitignore so artifacts stay out of version control.
- How do I migrate from themsaid/laravel-mail-preview to spatie/laravel-mail-preview?
- The package ships an UPGRADING guide covering the move from themsaid/laravel-mail-preview: swap the namespace and rename the route macro. The work is small and mechanical, and budgeting roughly half a day including validation is realistic rather than a sprint. Publish the new config and compare it against your old one instead of copying files across. For fresh adoption, a plain composer require plus the three config touches is all you need.
Weaver
How can I help you explore Laravel packages today?