Mail Laravel Package

Getting Started

Install the package with Composer: composer require illuminate/mail. Though technically standalone, this package is designed for use within Laravel applications—standalone usage requires manual bootstrapping of service providers, config loading, and container setup. First, create a mailable class via php artisan make:mail WelcomeUser, define content in build(), and send it using Mail::to($user)->send(new WelcomeUser()). Start with the default log mailer in .env (MAIL_MAILER=log) for safe local testing—emails are written to storage/logs/laravel.log instead of actually sending.

Implementation Patterns

• Encapsulate Email Logic: Keep business rules (e.g., dynamic content, conditional attachments) inside mailable classes, not controllers. Use constructor injection for required data (e.g., $order, $token).
• Markdown-Driven Templates: Prefer --markdown flag (php artisan make:mail --markdown=emails.orders.shipped) for responsive emails. Leverage Blade’s @component('mail::message'), @slot, and @endslot for consistent layouts and auto-inlined CSS.
• Asynchronous Delivery: Attach ShouldQueue to mailables or use Mail::queue() to avoid blocking requests. Ensure models passed to mailables are serializable (e.g., pass order_id, not Order instance).
• Environment-Specific Switching: Swap mailers via .env: use ses, smtp, or mailgun for production, log for local dev, and array for testing (emails discarded but trackable via Mail::spy()).
• Testing with Fakes: In tests, call Mail::fake(), trigger the action, then assert expectations: Mail::assertSent(OrderShipped::class, fn ($mail) => $mail->order->id === $orderId).

Gotchas and Tips

• Stale Model References in Queues: If queueing mailables with Eloquent models, resolve models inside the mailable’s build() (e.g., Order::findOrFail($this->orderId))—serialized models may be outdated by job execution time.
• view() vs markdown(): Using view() bypasses Laravel’s email layout engine and CSS inlining—always use markdown() for Markdown mailables to ensure responsiveness and consistent styling.
• Attachment Gotchas: Attachments must be absolute paths (e.g., storage_path('app/reports/' . $filename)) or closures that resolve at send time. Avoid relative paths—they’ll fail in queued jobs where the working directory may differ.
• No config/mail.php Outside Laravel: Standalone usage requires manually publishing/configuring mail.php and registering Illuminate\Mail\MailServiceProvider with a resolved container.
• Symfony Mailer Version Quirks: Ensure symfony/mailer ≥7.4.0 compatibility—some driver options (e.g., SES config keys like region) changed between v6 and v7. Check composer show symfony/mailer if emails fail silently.