Mailchimp Mailer Laravel Package

Getting Started

Minimal Setup

1. Install the Package:

   composer require symfony/mailchimp-mailer
   

2. Configure .env: Choose one of the supported DSN formats:

   # SMTP (recommended for transactional emails)
   MAILER_DSN=mandrill+smtp://USERNAME:PASSWORD@smtp.mandrillapp.com
   
   # HTTPS (for API-based workflows)
   MAILER_DSN=mandrill+https://YOUR_MAILCHIMP_API_KEY@default
   
   # API (direct API calls)
   MAILER_DSN=mandrill+api://YOUR_MAILCHIMP_API_KEY@default
   

   Replace USERNAME:PASSWORD with your Mandrill SMTP credentials or YOUR_MAILCHIMP_API_KEY with your Mailchimp API key.

3. Register the Transport in Laravel: Add this to your config/mail.php under the transports key:

   'mailchimp' => [
       'dsn' => env('MAILER_DSN'),
   ],
   

   Then set the default mailer to mailchimp in the same file:

   'default' => env('MAIL_MAILER', 'mailchimp'),
   

4. First Use Case: Send a Test Email Create a Laravel Mailable:

   php artisan make:mail TestMailchimpEmail
   

   Update the build method in app/Mail/TestMailchimpEmail.php:

   public function build()
   {
       return $this->markdown('emails.test')
                   ->subject('Test Email from Mailchimp');
   }
   

   Send the email from a controller or command:

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

5. Verify in Mailchimp: Check your Mailchimp Campaigns or Transactional Emails tab to confirm delivery.

Implementation Patterns

Core Workflows

1. Transactional Emails

• Pattern: Use Laravel’s Mailable classes with Mailchimp’s Merge Tags or Template IDs.

• Example:

  // In your Mailable class
  public function build()
  {
      return $this->markdown('emails.order_confirmation')
                  ->with([
                      'orderId' => $this->order->id,
                      'userName' => $this->user->name,
                  ])
                  ->subject('Your Order #'.$this->order->id.' Confirmed');
  }
  

  Map Laravel variables to Mailchimp Merge Tags (e.g., *|MC:FNAME|* for userName).

• Mailchimp Template Setup:

  1. Create a template in Mailchimp with Merge Tags matching your Laravel data.
  2. Reference the template ID in your Laravel config or dynamically via API.

2. Marketing Campaigns

• Pattern: Trigger campaigns programmatically using the Mailchimp API.
• Example:

  use Symfony\Component\Mailchimp\MailchimpClient;
  
  public function triggerCampaign(MailchimpClient $mailchimp, int $campaignId)
  {
      $campaign = $mailchimp->get('campaigns')->read($campaignId);
      $campaign->status = 'active';
      $campaign->save();
  }
  

  Register the client in Laravel’s service container:

  // In a service provider
  $this->app->singleton(MailchimpClient::class, function ($app) {
      return new MailchimpClient(env('MAILCHIMP_API_KEY'));
  });
  

3. Inline Images in Emails

• Pattern: Use Content-ID headers for embedding images in HTML emails.
• Example:

  public function build()
  {
      return $this->markdown('emails.product_update')
                  ->attach(public_path('images/logo.png'), [
                      'as' => 'logo.png',
                      'mime' => 'image/png',
                      'contentId' => 'logo', // This ensures the image is embedded
                  ])
                  ->subject('New Product Update');
  }
  

  This leverages the fix in v8.1.1 for proper inline image handling in Mandrill.

Gotchas and Tips

Debugging and Common Issues

1. Inline Images Not Displaying:

   • Ensure you’re using the contentId parameter when attaching images (fixed in v8.1.1).
   • Verify the Content-ID header is correctly set in the email headers.
   • Example debug step:

     Mail::to('recipient@example.com')->send(new TestMailchimpEmail());
     // Check the raw email headers for `Content-ID: logo`
     

2. Merge Tags Not Rendering:

   • Double-check that your Mailchimp template Merge Tags match the keys in your ->with() array.
   • Example: If your template uses *|MC:FNAME|*, ensure your ->with() includes 'FNAME' => 'John'.

3. API Rate Limits:

   • Mailchimp enforces API rate limits. Cache API responses where possible.
   • Use Laravel’s cache() helper to store campaign or template data temporarily.

Configuration Quirks

• DSN Format:
  • The mandrill+https:// and mandrill+api:// DSNs are interchangeable for most use cases. Prefer mandrill+https:// for clarity.
  • Avoid using mandrill+smtp:// for new projects unless you require SMTP-specific features.

Extension Points

1. Custom Mailchimp Client: Extend the Symfony\Component\Mailchimp\MailchimpClient to add project-specific logic:

   class CustomMailchimpClient extends MailchimpClient
   {
       public function sendTransactionalWithTracking($templateId, $to, $data)
       {
           // Custom logic to track opens/clicks
           $response = parent::sendTransactional($templateId, $to, $data);
           // Log tracking data
           return $response;
       }
   }
   

2. Event Listeners for Emails: Listen to Laravel’s MailableSent event to log or process sent emails:

   use Illuminate\Mail\Events\MessageSent;
   
   public function handle(MessageSent $event)
   {
       if ($event->mailerName === 'mailchimp') {
           // Log or process Mailchimp-specific emails
       }
   }
   

3. Testing: Use Laravel’s MailFake for unit testing:

   public function test_mailchimp_email()
   {
       Mail::fake();
   
       Mail::to('user@example.com')->send(new TestMailchimpEmail());
   
       Mail::assertSent(TestMailchimpEmail::class);
   }