Mail Laravel Package

Product Decisions This Supports

• Developer Safety & Debugging:
  • Interceptor feature eliminates accidental production sends by redirecting emails to a fixed address (e.g., dev@example.com) during development, directly addressing a top pain point in Laravel apps (e.g., Laravel issue #4567). This supports faster iteration and reduces support tickets from misrouted emails.
  • MailTracy Bar panel integrates with Tracy Debugger, enabling real-time email inspection without logging to files or external tools. This aligns with Laravel’s debugging-first philosophy and reduces reliance on third-party tools like MailHog.
• HTML Email Workflow Optimization:
  • HtmlComposer decouples HTML pre-processing (CSS inlining, image embedding, subject extraction) from the Message class, enabling modular email composition. This supports:
    • Headless email generation (e.g., for APIs or background jobs).
    • Reusable email templates across projects (e.g., shared HtmlComposer pipelines).
    • Plain-text alternative generation as a first-class citizen, improving accessibility compliance.
  • Backward compatibility with Message::setHtmlBody() ensures zero migration risk for existing codebases.
• Enterprise-Grade Email Handling:
  • Header preservation (via X-Original-* headers) enables audit trails for compliance (e.g., GDPR, HIPAA) and debugging complex routing (e.g., forwarded emails).
  • Subject prefixing (e.g., [TEST]) streamlines internal review workflows without manual editing.
• Roadmap for Email Tooling:
  • Standalone HtmlComposer paves the way for email template libraries (e.g., MJML integration) or AI-generated emails (e.g., LLMs composing HTML + plain-text).
  • Debugger integration justifies deeper investment in Laravel’s built-in email tools over third-party solutions (e.g., Mailtrap, MailHog).

When to Consider This Package

• Adopt if:
  • Your team frequently sends test emails to real users (e.g., during development) and needs automatic redirection to a safe address (e.g., dev@example.com).
  • You use Tracy Debugger and want real-time email inspection without additional setup (e.g., MailHog, Laravel Horizon).
  • Your email workflow requires modular HTML processing (e.g., shared CSS inlining, image embedding across projects).
  • You need audit trails for sent emails (e.g., original headers preserved in X-Original-*).
  • Your emails include both HTML and plain-text alternatives, and you want automated generation of the latter.
  • You’re building headless email APIs or background job-based emails and need fine-grained control over HTML composition.
• Look elsewhere if:
  • You don’t use Tracy Debugger and prefer file-based logging (e.g., Laravel’s logs/mail.log) or third-party tools (e.g., Mailtrap).
  • Your emails are 100% plain-text and don’t require HTML processing or DKIM.
  • You need drag-and-drop email builders (complement with MJML or SendGrid’s tools).
  • Your app doesn’t support dependency injection (Interceptor requires DI).
  • You’re on PHP <8.1 (v4.1.2 drops support for older versions; see upgrade guide).

How to Pitch It (Stakeholders)

For Executives: *"v4.1.2 eliminates two critical risks in our email workflow:

1. No more accidental production sends: The Interceptor automatically redirects all dev emails to dev@example.com, saving hours of support time and preventing customer confusion.
2. Real-time email debugging: The Tracy Bar panel lets devs inspect every sent email (From/To/Subject) without logging to files—like a postman for emails—directly in the browser. Impact:

• Faster development: Test emails safely, debug issues instantly.
• Lower risk: Zero accidental production sends.
• Compliance-ready: Preserves original headers for audits. Cost: Zero. Just update the package and configure mail.redirect in .env."*

For Engineering: *"v4.1.2 solves two major pain points with minimal effort:

1. Interceptor (DI: mail.redirect: dev@example.com):

   • Redirects all To/Cc/Bcc to a safe address during dev.
   • Preserves original recipients in X-Original-* headers for debugging.
   • Optional subject prefixing (e.g., [TEST]) for clarity.
   • Zero config: Slots into Laravel’s DI container automatically.

2. MailTracy Bar:

   • Shows sent emails live in the Tracy Bar (auto-enabled in debug mode).
   • Lists From/To+Cc+Bcc/Subject/Status—no more digging through logs.
   • Opt out with mail: debugger: false if needed.

3. HtmlComposer (new):

   • Standalone HTML pipeline for CSS inlining, image embedding, and plain-text generation.
   • Example:

     $composer = new HtmlComposer();
     $composer->inlineCss($html); // Accumulates stylesheets
     $composer->embedImages(public_path('images'));
     $plainText = $composer->generatePlainText(); // Auto-extracts from HTML
     

   • Backward compatible: Message::setHtmlBody() still works unchanged.

Tradeoffs:

• Interceptor: Requires DI (no impact if you’re already using Laravel’s container).
• Tracy Bar: Needs Tracy Debugger (install via composer require nette/tracy).
• PHP 8.1+: Drop-in upgrade for most Laravel apps.

Recommendation: High priority for teams sending HTML emails in dev or needing debugging tools. For plain-text-only apps, skip the HtmlComposer but adopt Interceptor + Tracy Bar."*

For Developers: *"New features that save time:

1. Dev Mode Safety: Add this to .env to never send test emails to real users again:

   MAIL_REDIRECT=dev@example.com
   

   Original recipients are preserved in X-Original-To headers.

2. Debugging Made Easy: With Tracy Debugger installed, sent emails appear in the Tracy Bar panel: Toggle with:

   config(['mail.debugger' => true]); // Auto-enabled in debug mode
   

3. HTML Email Superpowers: Use HtmlComposer for reusable email processing:

   $composer = new HtmlComposer();
   $composer->inlineCss($html); // Handles @media, :hover, etc.
   $composer->embedImages(storage_path('app/emails'));
   $plainText = $composer->generatePlainText(); // Auto-generated from HTML
   

   Pro Tip: Chain methods for modular templates:

   $template = $composer
       ->inlineCss($html)
       ->embedImages(public_path('assets'))
       ->generatePlainText();
   

Breaking Changes:

• PHP 8.1+ required (drop support for older versions).
• Interceptor uses DI (no manual instantiation).

Migration:

composer require nette/mail:v4.1.2
php artisan config:clear

Add to .env:

MAIL_REDIRECT=dev@example.com
MAIL_DEBUGGER=true
```"*