Laravel Mail Preview Laravel Package

Getting Started

1. Install the package: composer require spatie/laravel-mail-preview
2. Configure the mail driver in config/mail.php: set the transport for your mailer (e.g., smtp) to 'preview'
3. Register the middleware in app/Http/Kernel.php: add \Spatie\MailPreview\Http\Middleware\AddMailPreviewOverlayToResponse::class to the web group
4. Add the route macro: include Route::mailPreview(); in routes/web.php
5. Trigger a test email — send any Laravel mail while APP_DEBUG=true, and the overlay link will appear at the bottom-right of your screen

Implementation Patterns

• Local development only: Use the preview driver exclusively in non-production environments (e.g., via .env (MAIL_MAILER=preview) or conditional config loading)
• Automated testing: Replace Mail::fake() with SentMails::fake() in feature tests to assert mail content (e.g., SentMails::assertLastContains('Dear John'))
• Customize overlay UX: Adjust popup_timeout_in_seconds and show_link_to_preview in the published config to control how long the preview overlay stays visible
• Debug HTML emails: Open generated .html files directly in a browser to test responsiveness and rendering — the inline comment at the top contains full metadata
• Theming & reuse: Publish views (vendor:publish --tag=mail-preview-views) to modify the preview layout, overlay styling, or integrate with your app’s design system

Gotchas and Tips

• Lifetime management: Emails are auto-deleted after maximum_lifetime_in_seconds (default: 60s) — increase this if debugging long workflows or during slow CI runs
• Filename collisions: File names use timestamps with microseconds ('filename_date_format' => 'u'); if generating emails rapidly, consider increasing precision or adding UUIDs in custom event listeners
• No preview in console commands: The overlay only appears in web responses — use SentMails assertions or check storage/email-previews manually when sending from Artisan commands or jobs
• Middleware order matters: Ensure the overlay middleware runs after the response is fully rendered (e.g., before SendResponseWithoutFlashes but after ShareErrorsFromSession)
• Testing gotcha: SentMails::fake() must be called before triggering the action (like Mail::to()->send()), otherwise sent emails won’t be captured
• Mail spoofing support: The driver works with mail or smtp transports, but not log — log won’t store previews or trigger events