Swiftmailer Mailgun Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cspoo/swiftmailer-mailgun-bundle php-http/guzzle5-adapter
   

   For Laravel (not Symfony), manually register the bundle in config/app.php under providers:

   'providers' => [
       // ...
       cspoo\Swiftmailer\MailgunBundle\cspooSwiftmailerMailgunBundle::class,
   ],
   

2. Configuration: Add Mailgun credentials to .env:

   MAILGUN_KEY=key-3xxxxxxxxxxxx
   MAILGUN_DOMAIN=yourdomain.mailgun.org
   

   Publish the config file (if using Laravel):

   php artisan vendor:publish --provider="cspoo\Swiftmailer\MailgunBundle\cspooSwiftmailerMailgunBundle" --tag="config"
   

   Update config/mailgun.php with your settings.

3. First Use Case: Send an email via Laravel's Mail facade:

   use Illuminate\Support\Facades\Mail;
   
   Mail::raw('Test email via Mailgun', function($message) {
       $message->to('recipient@example.com')
               ->subject('Test Mailgun');
   });
   

Implementation Patterns

Core Workflow

1. Transport Integration: The bundle replaces Swiftmailer's default transport with Mailgun's HTTP API. Configure it in config/mail.php:

   'default' => env('MAIL_DRIVER', 'mailgun'),
   'mailgun' => [
       'transport' => 'mailgun',
       'host' => env('MAILGUN_DOMAIN'),
       'username' => env('MAILGUN_KEY'),
       'password' => '',
       'port' => 465,
       'encryption' => null,
       'timeout' => null,
       'options' => [
           'domain' => env('MAILGUN_DOMAIN'),
       ],
   ],
   

2. Queueing Emails: Use Laravel's queue system with Mailgun:

   Mail::to('user@example.com')->queue(new YourMailClass());
   

   Ensure your queue worker (php artisan queue:work) is running.

3. Customizing Headers/Attachments: Leverage Swiftmailer's methods:

   Mail::send([], [], function($message) {
       $message->getHeaders()->addTextHeader('X-Custom-Header', 'value');
       $message->attach($pathToFile);
   });
   

4. Event Listeners: Listen for mail events (e.g., Sent, Failed) via Laravel's events:

   Mail::send([], [], function($message) {
       event(new MailSent($message));
   });
   

Advanced Patterns

• Dynamic Domains/Keys: Fetch credentials dynamically (e.g., from a database) by overriding the bundle's service provider:

  $this->app->bind('cspoo_swiftmailer.mailgun', function($app) {
      return new MailgunTransport(
          $app['config']['mailgun.key'],
          $app['config']['mailgun.domain']
      );
  });
  

• Testing: Use Laravel's Mail::fake() for unit tests:

  Mail::fake();
  Mail::send([], [], function($message) {
      // Test logic
  });
  Mail::assertSent(YourMailClass::class);
  

Gotchas and Tips

Common Pitfalls

1. Authentication Errors:

   • Ensure MAILGUN_KEY and MAILGUN_DOMAIN are correct (case-sensitive).
   • Verify the domain is verified in Mailgun.
   • Check API key permissions in Mailgun’s security settings.

2. Rate Limits: Mailgun enforces rate limits. Monitor usage via:

   curl -s https://api.mailgun.net/v3/yourdomain.mailgun.org/statistics | jq
   

3. SSL/TLS Issues:

   • If using self-signed certificates, disable SSL verification in config:

     'options' => [
         'curl' => [
             CURLOPT_SSL_VERIFYPEER => false,
         ],
     ],
     

   • Prefer php-http/guzzle6-adapter for newer Laravel versions.

4. Queue Delays: Mailgun may throttle queued emails. Use Mailgun’s webhooks to track delays.

Debugging Tips

• Log HTTP Requests: Enable Swiftmailer logging in config/mail.php:

  'log' => [
      'driver' => 'single',
      'path' => storage_path('logs/mail.log'),
      'level' => 'debug',
  ],
  

• Check Mailgun Webhooks: Set up a webhook for accepting, delivered, and failed events to debug in real-time:

  # config/mailgun.php
  webhook_url: 'https://your-app.com/mailgun-webhook'
  

Extension Points

1. Custom Transport: Extend cspoo\Swiftmailer\MailgunBundle\Transport\MailgunTransport to add features like:

   • Custom headers for all emails.
   • Automatic tagging (e.g., X-Mailgun-Tag: newsletter).

2. Event Handling: Subscribe to Mailgun webhooks in Laravel:

   Route::post('/mailgun-webhook', function (Request $request) {
       MailgunWebhook::handle($request->input());
   });
   

3. Fallback Transport: Combine with other transports (e.g., SMTP) for redundancy:

   'mailgun' => [
       'transport' => env('MAIL_DRIVER') === 'mailgun' ? 'mailgun' : 'smtp',
       // ...
   ],
   

Laravel-Specific Notes

• Service Provider Binding: If using Laravel 5.5+, the bundle auto-discovers. For older versions, manually bind:

  $this->app->bind(
      'swift.transport.mailgun',
      function($app) {
          return new MailgunTransport(
              $app['config']['mail.mailgun.key'],
              $app['config']['mail.mailgun.domain']
          );
      }
  );
  

• Environment Variables: Use Laravel’s env() helper in config:

  'key' => env('MAILGUN_KEY', 'fallback-key'),
  'domain' => env('MAILGUN_DOMAIN', 'fallback-domain'),