Laravel Mailcoach Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-mailcoach-sdk
   php artisan vendor:publish --tag="mailcoach-sdk-config"
   

2. Configure .env:

   MAILCOACH_API_TOKEN=your_api_token_here
   MAILCOACH_API_ENDPOINT=https://your-mailcoach-instance.com/api
   

3. First Use Case: Fetch all email lists:

   use Spatie\MailcoachSdk\Facades\Mailcoach;
   
   $emailLists = Mailcoach::emailLists();
   

Key Entry Points

• Facade: Spatie\MailcoachSdk\Facades\Mailcoach (primary interface)
• Resource Classes: EmailList, Subscriber, Campaign (for detailed operations)
• Pagination: Built-in support via next(), previous(), etc.

Implementation Patterns

Core Workflows

1. Email List Management

• Create/Update:

  $list = Mailcoach::createEmailList(['name' => 'Newsletter']);
  $list->name = 'Updated Newsletter';
  $list->save();
  

• Bulk Operations:

  $subscribers = Mailcoach::emailList($listUuid)->subscribers(['filter[email]=gmail.com']);
  foreach ($subscribers as $subscriber) {
      $subscriber->tags = ['promo'];
      $subscriber->save();
  }
  

2. Campaign Lifecycle

• Create with Template:

  $campaign = Mailcoach::createCampaign([
      'email_list_uuid' => $listUuid,
      'template_uuid' => $templateUuid,
      'fields' => ['title' => 'Hello'],
  ]);
  

• Send Workflow:

  $campaign->sendTest('test@example.com'); // Test first
  $campaign->send(); // Full send
  

3. Subscriber Sync

• Upsert Pattern:

  $subscriber = Mailcoach::emailList($listUuid)->subscriber('user@example.com');
  if (!$subscriber) {
      $subscriber = Mailcoach::createSubscriber($listUuid, [
          'email' => 'user@example.com',
          'first_name' => 'John',
      ]);
  }
  

4. Pagination Handling

• Iterate All Subscribers:

  $subscribers = Mailcoach::emailList($listUuid)->subscribers();
  while ($subscribers->total() > $subscribers->currentPage() * 1000) {
      foreach ($subscribers as $subscriber) { /* ... */ }
      $subscribers = $subscribers->next();
  }
  

Integration Tips

• Event-Driven: Trigger Mailcoach actions on Laravel events (e.g., user.registered → add subscriber).
• Queue Jobs: Offload heavy operations (e.g., bulk updates) to queues:

  Mailcoach::queue(fn () => Mailcoach::emailList($listUuid)->subscribers()->each(...));
  

• API Rate Limiting: Use Mailcoach::withRetry() for idempotent operations:

  Mailcoach::withRetry(3)->createCampaign(...);
  

Gotchas and Tips

Pitfalls

1. API Token Permissions:

   • Ensure the token has read/write access for required endpoints (e.g., campaigns).
   • Fix: Regenerate token in Mailcoach with correct scopes.

2. Pagination Limits:

   • Default limit is 1000 items/page. For large datasets, implement chunked processing:

     $subscribers->take(500); // Override limit temporarily
     

3. UUID Validation:

   • Always validate UUIDs (e.g., Str::isUuid($uuid)) before passing to Mailcoach methods.

4. Field Mismatches:

   • Template fields must match the fields array exactly (case-sensitive). Use Mailcoach::campaign($uuid)->template->fields to verify.

Debugging

• HTTP Errors: Enable Guzzle middleware for debugging:

  Mailcoach::getClient()->getEmitter()->attach(
      new \GuzzleHttp\Middleware::tap(function ($request) {
          \Log::debug('Mailcoach Request:', ['url' => $request->getUri(), 'body' => $request->getBody()]);
      })
  );
  

• Fake Testing: Use Mailcoach::fake() to mock responses:

  Mailcoach::fake([
      'campaigns' => ['uuid' => 'test-123', 'name' => 'Test Campaign'],
  ]);
  

Extension Points

1. Custom Resources: Extend base resources (e.g., Spatie\MailcoachSdk\Resources\EmailList) to add methods:

   class CustomEmailList extends \Spatie\MailcoachSdk\Resources\EmailList {
       public function activeSubscribers() {
           return $this->subscribers(['filter[status]=active']);
       }
   }
   

   Register via service provider:

   $this->app->bind(\Spatie\MailcoachSdk\Resources\EmailList::class, CustomEmailList::class);
   

2. API Middleware: Add request/response middleware to the Guzzle client:

   Mailcoach::getClient()->getEmitter()->attach(
       new \GuzzleHttp\Middleware::mapRequest(function ($request) {
           $request = $request->withHeader('X-Custom-Header', 'value');
           return $request;
       })
   );
   

3. Event Listeners: Listen for Mailcoach webhooks (e.g., campaign sent) via Laravel events:

   Mailcoach::campaignSent(function ($campaign) {
       event(new CampaignSent($campaign));
   });
   

Configuration Quirks

• Endpoint Overrides: Use Mailcoach::setEndpoint() dynamically:

  Mailcoach::setEndpoint('https://staging-mailcoach.com/api');
  

• Timeouts: Adjust Guzzle defaults in config/mailcoach-sdk.php:

  'client' => [
      'timeout' => 30, // seconds
  ],