Mail Laravel Package

Getting Started

Minimal Setup in Laravel

1. Install the package:

   composer require nette/mail
   

2. Configure in config/mail.php (extend Laravel’s default):

   'mailers' => [
       'nette' => [
           'transport' => 'smtp',
           'host' => env('MAIL_HOST'),
           'port' => env('MAIL_PORT'),
           'username' => env('MAIL_USERNAME'),
           'password' => env('MAIL_PASSWORD'),
           'encryption' => env('MAIL_ENCRYPTION'),
           'dkim' => [
               'domain' => env('MAIL_DKIM_DOMAIN'),
               'selector' => env('MAIL_DKIM_SELECTOR'),
               'privateKey' => env('MAIL_DKIM_PRIVATE_KEY'),
           ],
           'debugger' => env('APP_DEBUG'), // Enables Tracy Bar integration
       ],
   ],
   

3. Bind the mailer in AppServiceProvider:

   public function register()
   {
       $this->app->singleton(\Nette\Mail\IMailer::class, function ($app) {
           $config = config('mail.mailers.nette');
           return new \Nette\Mail\SmtpMailer($config);
       });
   }
   

4. First use case: Send a test email via a Laravel command:

   use Nette\Mail\Message;
   use Nette\Mail\IMailer;
   
   class SendTestEmail implements ShouldQueue
   {
       public function handle(IMailer $mailer)
       {
           $message = new Message();
           $message->setFrom('noreply@example.com')
                   ->addTo('dev@example.com')
                   ->setSubject('Test Email')
                   ->setHtmlBody('<h1>Hello from Nette Mail!</h1>');
   
           $mailer->send($message);
       }
   }
   

Key First Steps

• Test locally: Use the Interceptor to redirect emails to dev@example.com (configured via mail.redirect in DI).
• Verify DKIM: Check headers with mail.headers: true in config to ensure signing works.
• Debug rendering: Enable debugger: true for Tracy Bar integration (visible in Laravel’s /debugbar if using barryvdh/laravel-debugbar).

Implementation Patterns

1. Message Composition Workflow

Laravel Mailable Integration: Extend Laravel’s Mailable to leverage Nette’s features:

use Nette\Mail\Message as NetteMessage;
use Nette\Mail\IMailer;

class NetteMailable extends Mailable
{
    public function build()
    {
        $message = new NetteMessage();
        $message->setFrom(config('mail.from.address'))
                ->addTo($this->recipient)
                ->setSubject($this->subject);

        // HTML + Plaintext (automatically generated from HTML)
        $message->setHtmlBody($this->htmlContent)
                ->setTextBody($this->textContent ?? $message->buildText());

        // Attachments
        if ($this->attachment) {
            $message->addAttachment($this->attachment, 'filename.pdf');
        }

        // Inline CSS (for Outlook compatibility)
        $message->setHtmlBody((new \Nette\Mail\HtmlComposer())
            ->inlineCss($message->getHtmlBody())
            ->getHtml());

        return $message;
    }

    public function send(IMailer $mailer)
    {
        $mailer->send($this->build());
    }
}

Key Methods:

2. Transport Strategies

Example: Hybrid Transport:

// config/mail.php
'mailers' => [
    'hybrid' => [
        'transport' => 'fallback',
        'primary' => 'smtp',
        'fallback' => 'sendmail',
        'smtp' => [...],
        'sendmail' => [...],
    ],
],

3. Debugging & Testing

• Interceptor for Dev:

  // config/services.php
  'mail.redirect' => env('APP_DEBUG') ? 'dev@example.com' : null,
  

  • Redirects all emails to a single address during development.
  • Original recipients are stored in X-Original-To headers.

• Tracy Bar Integration: Enable in config/mail.php:

  'debugger' => env('APP_DEBUG'),
  

  • Shows sent emails in Laravel Debugbar (if using barryvdh/laravel-debugbar).
  • Click to view headers, recipients, and status.

• Local Testing: Use Mail::fake() with a custom mailer:

  Mail::fake();
  $mailer = app(\Nette\Mail\IMailer::class);
  $mailer->send($message);
  
  // Assert
  Mail::assertSent(NetteMailable::class);
  

4. DKIM & Deliverability

Configure DKIM in config/mail.php:

'dkim' => [
    'domain' => 'example.com',
    'selector' => 'mail',
    'privateKey' => file_get_contents(storage_path('dkim_private.key')),
    'passPhrase' => env('DKIM_PASSPHRASE'),
],

Verify DKIM:

• Send a test email to DKIM Checker.
• Check headers for:

  DKIM-Signature: v=1; a=rsa-sha256; ...
  Authentication-Results: spf=pass (sender IP is 1.2.3.4) ...
  

5. CSS & HTML Best Practices

Outlook-Compatible Emails:

use Nette\Mail\HtmlComposer;

$composer = new HtmlComposer();
$html = $composer
    ->inlineCss($rawHtml)       // Converts `<style>` to inline styles
    ->embedImages(public_path()) // Converts `src="image.jpg"` to CID
    ->getHtml();

Common Pitfalls:

• Avoid !important in CSS (use style attributes instead).
• Test with Email on Acid or Litmus.
• Use bgcolor, width, and align attributes for Outlook 2013/2016.

Gotchas and Tips

1. Common Pitfalls

2. Debugging Tips

• Check raw email:

  $message->setRawBody($mailer->getRawMessage($message));
  

• Log headers:

  $mailer->onSend[]