Mail Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require nette/mail
   

   Ensure PHP ≥8.2 (or use nette/mail:^3.1 for PHP 8.0+).

2. First Use Case: Send a Text Email

   use Nette\Mail\Message;
   use Nette\Mail\SmtpMailer;
   
   $mailer = new SmtpMailer(
       host: 'smtp.example.com',
       port: 587,
       username: 'user@example.com',
       password: 'password',
       encryption: 'tls'
   );
   
   $message = (new Message())
       ->setFrom('from@example.com')
       ->addTo('to@example.com')
       ->setSubject('Test Email')
       ->setBody('Hello, this is a test email.');
   
   $mailer->send($message);
   

3. Key Files to Reference

   • Message: Core email composition.
   • SmtpMailer: SMTP transport.
   • CssInliner: CSS-to-inline conversion.

Implementation Patterns

1. Laravel Integration via Facade

Extend Laravel’s Mail facade to use Nette’s Message:

// app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Mail;
use Nette\Mail\Message as NetteMessage;

Mail::macro('nette', function ($callback) {
    $message = new NetteMessage();
    $callback($message);
    return $message;
});

Usage:

Mail::nette(function ($message) {
    $message->setFrom('from@example.com')
            ->addTo('to@example.com')
            ->setSubject('Hello')
            ->setHtmlBody('<h1>Hi!</h1>');
});

2. Dynamic Email Templates with Blade

Render Blade templates directly in setHtmlBody():

$message->setHtmlBody(view('emails.welcome', [
    'user' => $user,
    'buttonUrl' => route('dashboard'),
]));

3. Multipart Emails (HTML + Plaintext)

$message->setHtmlBody('<h1>HTML Content</h1>')
        ->setTextBody('Plaintext alternative')
        ->setPriority(Message::PRIORITY_HIGH);

4. Attachments and Embeds

• Attachments:

  $message->createAttachment(
      file: storage_path('file.pdf'),
      mimeType: 'application/pdf',
      fileName: 'document.pdf',
      disposition: 'attachment'
  );
  

• Embedded Images:

  $message->addInlinePart(
      file: storage_path('logo.png'),
      cid: 'logo'
  );
  $message->setHtmlBody('<img src="cid:logo" alt="Logo">');
  

5. CSS Inlining for Cross-Client Compatibility

use Nette\Mail\CssInliner;

$inliner = new CssInliner(['outlook' => true]);
$message->setHtmlBody($inliner->inline($htmlContent));

6. DKIM Signing

Configure in config/mail.php:

'dkim' => [
    'domain' => env('MAIL_DKIM_DOMAIN'),
    'selector' => env('MAIL_DKIM_SELECTOR'),
    'privateKey' => env('MAIL_DKIM_PRIVATE_KEY_PATH'),
],

Apply to mailer:

$mailer = new SmtpMailer(/* ... */);
$mailer->setDkimSigner(
    domain: config('mail.dkim.domain'),
    selector: config('mail.dkim.selector'),
    privateKey: file_get_contents(config('mail.dkim.privateKey'))
);

7. Fallback Mailers

Combine multiple transports:

use Nette\Mail\FallbackMailer;

$fallbackMailer = new FallbackMailer(
    primary: new SmtpMailer(/* ... */),
    fallback: new SendmailMailer('/usr/sbin/sendmail')
);

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch

   • nette/mail:^4.0 requires PHP ≥8.2. Use ^3.1 for PHP 8.0+.
   • Fix: Downgrade or upgrade PHP.

2. SMTP Timeouts

   • Slow SMTP servers may hang. Use setTimeout():

     $mailer->setTimeout(30); // 30 seconds
     

3. CSS Inlining Quirks

   • Outlook ignores <style> tags. Use CssInliner with outlook: true:

     $inliner = new CssInliner(['outlook' => true]);
     

   • Tip: Test with Email on Acid or Litmus.

4. DKIM Key Permissions

   • Ensure the private key file is readable by the web server:

     chmod 640 private.key
     chown www-data:www-data private.key
     

5. Attachment Encoding

   • Non-ASCII filenames may break. Use encodeHeader():

     $message->createAttachment(
         file: storage_path('résumé.pdf'),
         fileName: 'resume.pdf' // Manually encode if needed
     );
     

6. Sendmail Path Issues

   • On Linux, verify /usr/sbin/sendmail exists. Use absolute paths:

     new SendmailMailer('/usr/sbin/sendmail -t -i');
     

Debugging Tips

1. Log Raw Emails Intercept messages before sending:

   $mailer->onSend[] = function ($message) {
       file_put_contents(
           storage_path('debug/email.eml'),
           $message->toString()
       );
   };
   

2. SMTP Debugging Enable verbose output:

   $mailer = new SmtpMailer(/* ... */);
   $mailer->setDebugMode(true);
   

3. Validate MIME Structure Use Message::toString() to inspect raw output:

   echo $message->toString();
   

Extension Points

1. Custom Mailers Extend Nette\Mail\IMailer for unique transports (e.g., AWS SES):

   class SesMailer implements IMailer {
       public function send(Message $message): void {
           // AWS SES logic
       }
   }
   

2. Pre-Send Hooks Modify messages dynamically:

   $mailer->onSend[] = function ($message) {
       $message->addHeader('X-Custom', 'Value');
   };
   

3. Override CssInliner Customize CSS processing:

   class CustomInliner extends CssInliner {
       protected function processRule(string $rule): string {
           // Custom logic
       }
   }
   

Performance Considerations

• Batch Processing: Queue emails with Laravel’s queue system:

  Mail::queue(function ($message) {
      $message->setFrom('from@example.com')
              ->addTo('to@example.com')
              ->setSubject('Batch Email');
  });
  

• Avoid Inlining for Large Emails: Disable CssInliner for performance-critical emails.