Mailchimp Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require carlead/mailchimp-bundle
   

   Register the bundle in config/app.php under providers:

   Carlead\MailchimpBundle\MailchimpBundle::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Carlead\MailchimpBundle\MailchimpBundle" --tag="config"
   

   Update config/mailchimp.php with your Mailchimp API key and default list ID.

3. First Use Case: Subscribing a User

   use Carlead\MailchimpBundle\Mailchimp;
   
   $mailchimp = app(Mailchimp::class);
   $result = $mailchimp->lists->subscribe('YOUR_LIST_ID', [
       'email_address' => 'user@example.com',
       'merge_fields'  => ['FNAME' => 'John', 'LNAME' => 'Doe']
   ]);
   

Implementation Patterns

Common Workflows

1. List Management

   // Fetch all lists
   $lists = $mailchimp->lists->getAll();
   
   // Create a new list
   $newList = $mailchimp->lists->create([
       'name' => 'Newsletter Subscribers',
       'contact' => ['company' => 'Your Company']
   ]);
   

2. Campaigns

   // Send a campaign
   $campaign = $mailchimp->campaigns->create([
       'type' => 'regular',
       'recipients' => ['list_id' => 'YOUR_LIST_ID'],
       'settings' => ['subject_line' => 'Hello!']
   ]);
   $mailchimp->campaigns->send($campaign['id']);
   

3. Segmentation

   // Create a segment
   $segment = $mailchimp->segments->create('YOUR_LIST_ID', [
       'name' => 'Active Users',
       'static_segment' => [
           'conditions' => [
               ['field' => 'DATE_ADDED', 'op' => 'greater_than', 'value' => '2023-01-01']
           ]
       ]
   ]);
   

Integration Tips

• Service Container Binding Bind the Mailchimp service in a service provider for easier dependency injection:

  $this->app->bind(Mailchimp::class, function ($app) {
      return new Mailchimp($app['config']['mailchimp']);
  });
  

• Event-Driven Workflows Use Laravel events to trigger Mailchimp actions (e.g., subscribe on user registration):

  use Illuminate\Support\Facades\Event;
  
  Event::listen('registered', function ($user) {
      $mailchimp = app(Mailchimp::class);
      $mailchimp->lists->subscribe('YOUR_LIST_ID', [
          'email_address' => $user->email,
          'merge_fields'  => ['FNAME' => $user->name]
      ]);
  });
  

• Batch Processing For large datasets, use chunking to avoid API rate limits:

  User::chunk(100, function ($users) use ($mailchimp) {
      foreach ($users as $user) {
          $mailchimp->lists->subscribe('YOUR_LIST_ID', [
              'email_address' => $user->email,
              'merge_fields'  => ['FNAME' => $user->name]
          ]);
      }
  });
  

Gotchas and Tips

Pitfalls

1. API Rate Limits Mailchimp enforces rate limits (e.g., 10 calls/second). Handle exceptions gracefully:

   try {
       $result = $mailchimp->lists->subscribe(...);
   } catch (\Carlead\MailchimpBundle\Exceptions\MailchimpException $e) {
       if ($e->getCode() === 429) {
           sleep(1); // Retry after delay
       }
   }
   

2. Merge Field Validation Merge fields must match Mailchimp’s naming conventions (e.g., FNAME, LNAME). Use lists->getMergeFields() to verify available fields.

3. List ID vs. List Name Always use the list ID (not name) in API calls. Fetch IDs upfront:

   $lists = $mailchimp->lists->getAll();
   $listId = $lists[0]['id']; // Use this, not $lists[0]['name']
   

Debugging

• Enable Debug Mode Set debug: true in config/mailchimp.php to log raw API responses:

  'debug' => env('MAILCHIMP_DEBUG', false),
  

• Common Errors

  • 400 Bad Request: Validate input data (e.g., missing email_address).
  • 401 Unauthorized: Check your API key in .env (MAILCHIMP_API_KEY).
  • 404 Not Found: Verify list/campaign IDs exist.

Extension Points

1. Custom API Endpoints Extend the Mailchimp class to add missing endpoints:

   namespace App\Services;
   
   use Carlead\MailchimpBundle\Mailchimp as BaseMailchimp;
   
   class Mailchimp extends BaseMailchimp {
       public function customEndpoint($method, $path, $data = []) {
           return $this->callApi($method, $path, $data);
       }
   }
   

2. Middleware for API Calls Add retry logic or logging middleware:

   $mailchimp->setMiddleware(function ($request, $next) {
       try {
           return $next($request);
       } catch (\Exception $e) {
           \Log::error('Mailchimp API Error: ' . $e->getMessage());
           throw $e;
       }
   });
   

3. Queue Mailchimp Tasks Offload long-running tasks (e.g., bulk unsubscribes) to Laravel queues:

   dispatch(new SubscribeUsersToMailchimp($users));
   

   class SubscribeUsersToMailchimp implements ShouldQueue {
       public function handle() {
           foreach ($this->users as $user) {
               $mailchimp->lists->subscribe('YOUR_LIST_ID', [...]);
           }
       }
   }