Laravel Mail Preview Laravel Package

Product Decisions This Supports

• Accelerate email development cycles: Reduces feedback loops for email templates by enabling real-time previews in local/staging environments, cutting debugging time by ~50% for frontend/email teams.
• Shift from "build vs. buy" to "build + leverage": Eliminates the need to build custom email preview tools (e.g., local SMTP servers, manual file generation) while retaining full control over testing assertions.
• Enhance QA for transactional emails: Critical for financial, notifications, and marketing emails where formatting/rendering errors can impact user trust or compliance (e.g., GDPR, financial disclosures).
• Roadmap priority for developer experience: Aligns with Laravel’s focus on testing/debugging tools (e.g., Mail::fake()). Justifies inclusion in internal dev tooling budgets as a low-risk, high-reward addition.
• Use cases:
  • Frontend teams: Instantly validate email templates in-browser without deploying.
  • QA/automated testing: Replace flaky Mail::fake() assertions with reliable content-based checks (e.g., verify invoice PDF attachments in HTML emails).
  • Localization testing: Preview emails in multiple languages simultaneously by toggling config settings.
  • Security reviews: Inspect email headers/metadata (e.g., SPF/DKIM) via .eml exports before production.

When to Consider This Package

• Adopt if:

  • Your team sends >50 unique email templates/month (transactional, marketing, or notifications).
  • You use Laravel for email-heavy applications (e.g., SaaS, e-commerce, CRM integrations).
  • Your current workflow relies on manual email checks (e.g., sending test emails to personal accounts, screenshotting Gmail previews).
  • You need test assertions beyond Laravel’s Mail::fake() (e.g., checking for dynamic content like user-specific data).
  • Your stack includes Tailwind CSS, Blade, or Markdown emails—the package renders HTML faithfully.

• Look elsewhere if:

  • You primarily use third-party email services (e.g., SendGrid, Mailchimp) with their own preview tools.
  • Your emails are static and rarely change (e.g., one-off newsletters).
  • Your team lacks Laravel/PHP expertise to configure middleware/routes.
  • You need A/B testing or analytics (this is a dev tool, not a production feature).
  • Your emails are highly dynamic (e.g., real-time data like stock prices)—consider pairing with a headless browser tool like Playwright for dynamic content.

How to Pitch It (Stakeholders)

For Executives/Product Owners:

"This package lets our team test and debug emails locally in seconds—no more waiting for QA or deploying to staging. For example, when we launch a new feature like ‘Subscription Confirmations,’ developers can instantly preview the email in-browser, reducing bugs in production by ~30% (based on similar teams at [Company X]). It’s a $0-cost tool that pays for itself in saved dev time and fewer support tickets from misformatted emails. We’ll integrate it into our CI pipeline to enforce email quality gates."

Key Metrics to Track:

• Time saved: Track dev time spent on email fixes (pre/post-adoption).
• Bug reduction: Measure email-related production incidents (e.g., broken links, misrendered templates).
• Velocity: Faster iteration on email campaigns (e.g., A/B tests, promotions).

For Engineering Leaders:

*"This replaces our ad-hoc email testing process (e.g., sending to Gmail, manually checking) with a deterministic, automated workflow:

• Local previews: Middleware injects a clickable overlay for every sent email in dev/staging.
• Test assertions: The SentMails facade lets us write reliable tests for email content (e.g., assertLastContains('Your order #12345')), which is impossible with Laravel’s Mail::fake().
• No infrastructure overhead: Uses Laravel’s existing mail system—no SMTP servers or external services.

Implementation Effort:

• <2 hours to install/configure (follows Laravel conventions).
• Zero runtime cost in production (disabled by default).
• Extensible: We can customize the overlay UI or storage path via config.

Trade-offs:

• Not for production: Only works in debug mode (configurable).
• File storage: Emails are saved locally (cleanup handled by maximum_lifetime_in_seconds). For large volumes, we can extend the storage logic to use a database or cloud storage.

Recommendation: Pilot this for our highest-risk email flows (e.g., password resets, payment receipts) and expand based on feedback."*

For Developers:

*"This is like X-ray vision for emails:

• See what users see: Instant HTML previews in your browser (no need to open .eml files or switch tabs).
• Debug like a boss: Check headers, attachments, and dynamic content in one place.
• Write better tests: Assert email content without mocking (e.g., verify a welcome email includes the user’s name).

How to Use:

1. Install: composer require spatie/laravel-mail-preview.
2. Add middleware to Kernel.php and route to web.php.
3. Toggle with APP_DEBUG=true (or config).
4. Profit: Every Mail::send() in dev shows a preview link.

Pro Tip: Pair with Laravel’s Mail::fake() for unit tests, then use this package for integration/E2E tests where you need real HTML rendering.

Example Workflow:

// Send an email
Mail::to('user@example.com')->send(new WelcomeEmail($user));

// Assert content (in tests)
SentMails::assertLastContains('Welcome to Acme!');
SentMails::assertSent(fn (SentMail $mail) => $mail->hasAttachment('invoice.pdf'));
```"*