Amazon Mailer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require symfony/amazon-mailer
   

   Ensure your project uses Symfony Mailer (v5.4+) or Laravel's SwiftMailer bridge (if migrating).

2. Configuration: Add AWS SES credentials to .env:

   AWS_ACCESS_KEY_ID=your_access_key
   AWS_SECRET_ACCESS_KEY=your_secret_key
   AWS_DEFAULT_REGION=us-east-1
   MAIL_MAILER=amazon_ses
   

3. First Use Case: Send a test email via Laravel’s Mail facade:

   use Illuminate\Support\Facades\Mail;
   use App\Mail\TestEmail;
   
   Mail::to('recipient@example.com')->send(new TestEmail());
   

Key Files to Review

• config/mail.php (ensure amazon_ses transport is configured).
• vendor/symfony/amazon-mailer (source for transport logic).

Implementation Patterns

Workflows

1. Sending Emails:

   • Use Laravel’s Mail facade or SwiftMailer directly.
   • Configure the AmazonSesTransport in config/mail.php:

     'transports' => [
         'amazon_ses' => [
             'scheme' => 'amazon_ses',
             'host' => env('AWS_DEFAULT_REGION'),
             'path' => '/',
             'aws' => [
                 'version' => 'latest',
                 'region' => env('AWS_DEFAULT_REGION'),
                 'credentials' => [
                     'key' => env('AWS_ACCESS_KEY_ID'),
                     'secret' => env('AWS_SECRET_ACCESS_KEY'),
                 ],
             ],
         ],
     ],
     

2. Templates & Attachments:

   • Use Laravel’s Mailable classes for templates (Blade/HTML).
   • Attachments work natively:

     $mailable->attach(public_path('file.pdf'));
     

3. Queueing Emails:

   • Leverage Laravel’s queue system for async sends:

     Mail::later(now()->addMinutes(5), new TestEmail(), $queue: 'emails');
     

Integration Tips

• AWS SES Verification: Verify email addresses/domains in AWS SES console before sending.
• Logging: Enable Symfony Mailer’s debug mode for troubleshooting:

  $mailer->getTransport()->getLogger()->setLevel(\Psr\Log\LogLevel::DEBUG);
  

• Fallback Transports: Configure a fallback (e.g., log) in config/mail.php for SES outages:

  'fallback' => [
      'transport' => 'log',
  ],
  

Gotchas and Tips

Pitfalls

1. AWS SES Limits:

   • SES has sending limits (e.g., 60 emails/hour for new accounts). Monitor in AWS Console.
   • Use Amazon SES Sandbox for testing (requires verified emails).

2. Region Mismatch:

   • Ensure AWS_DEFAULT_REGION matches the SES region (e.g., us-east-1 for SES).

3. TLS/SSL Warnings:

   • Symfony Amazon Mailer may log TLS warnings if SES endpoints aren’t fully compliant. Ignore unless emails fail.

4. Queue Stuck Jobs:

   • If emails queue but don’t send, check:
     • AWS credentials validity.
     • SES sending limits.
     • Laravel queue worker logs (php artisan queue:work).

Debugging

• Enable Verbose Logging:

  \Symfony\Component\Mailer\Transport\AmazonSesTransport::class => [
      'logger' => \Psr\Log\LoggerInterface::class,
      'logger.level' => \Psr\Log\LogLevel::DEBUG,
  ],
  

• Check SES Metrics: Use AWS CloudWatch for SES delivery stats.

Extension Points

1. Custom Transport Options: Extend AmazonSesTransport to add features (e.g., custom headers):

   $transport = new AmazonSesTransport($client, [
       'headers' => ['X-Custom-Header' => 'value'],
   ]);
   

2. Event Listeners: Hook into Symfony’s MessageSentEvent for analytics:

   Mail::sent(function ($message) {
       // Log or track sent emails.
   });
   

3. Bounce/Complaint Handling: Use AWS SES notifications (SNS) to process bounces/complaints via Laravel events.