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 and iterate through all email lists:

   use Spatie\MailcoachSdk\Facades\Mailcoach;
   
   $lists = Mailcoach::emailLists();
   foreach ($lists as $list) {
       echo $list->name;
   }
   

Where to Look First

• Facade: Spatie\MailcoachSdk\Facades\Mailcoach (primary entry point).
• Resource Classes: EmailList, Subscriber, Campaign (for detailed operations).
• Pagination: Methods like next(), results() for handling large datasets.

Implementation Patterns

Core Workflows

Email List Management

1. Create & Update:

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

2. Bulk Subscriber Operations:

   $subscribers = Mailcoach::emailList('list-uuid')->subscribers();
   foreach ($subscribers as $subscriber) {
       if ($subscriber->email->endsWith('@gmail.com')) {
           $subscriber->unsubscribe();
       }
   }
   

Campaign Automation

1. Template-Based Campaigns:

   $campaign = Mailcoach::createCampaign([
       'email_list_uuid' => 'list-uuid',
       'template_uuid' => 'template-uuid',
       'fields' => ['title' => 'Hello!'],
   ]);
   $campaign->sendTest('test@example.com'); // Test before full send
   $campaign->send(); // Trigger full campaign
   

Subscriber Segmentation

1. Filtered Subscribers:

   $activeSubscribers = Mailcoach::emailList('list-uuid')
       ->subscribers(['filter[status]=active']);
   

Pagination Handling

1. Process Large Datasets:

   $subscribers = Mailcoach::emailList('list-uuid')->subscribers();
   while ($subscribers->next()) {
       foreach ($subscribers as $subscriber) {
           // Process subscriber
       }
   }
   

Integration Tips

• Event Listeners: Hook into Campaign::sent or Subscriber::confirmed via Mailcoach webhooks.
• Queue Jobs: Offload heavy operations (e.g., bulk updates) to Laravel queues:

  dispatch(new SyncSubscribersJob($emailListUuid));
  

• API Rate Limiting: Use Mailcoach::withOptions(['timeout' => 30]) for long-running tasks.

Gotchas and Tips

Pitfalls

1. Pagination Quirks:

   • Always check next() returns null before looping (avoid infinite loops).
   • Use total() to estimate processing time for large datasets.

2. API Token Security:

   • Never hardcode tokens; use Laravel’s .env or vault.
   • Restrict token permissions in Mailcoach (e.g., read-only for analytics).

3. Subscriber State:

   • unsubscribe() only works on confirmed subscribers. Use confirm() first if needed.

4. Template Fields:

   • Fields in createCampaign() must match the template’s placeholders exactly (case-sensitive).

Debugging

• HTTP Errors: Wrap calls in try-catch:

  try {
      $campaign->send();
  } catch (\Spatie\MailcoachSdk\Exceptions\MailcoachException $e) {
      Log::error($e->getMessage(), ['response' => $e->getResponse()]);
  }
  

• Fake Testing: Use Mailcoach::fake() in tests:

  Mailcoach::fake();
  $campaign = Mailcoach::createCampaign([...]);
  $campaign->send();
  Mailcoach::assertSent('campaign-uuid');
  

Extension Points

1. Custom Resources: Extend Spatie\MailcoachSdk\Resources\Resource to add domain-specific fields:

   class CustomSubscriber extends Resource {
       public function getCustomAttribute() { ... }
   }
   

2. Middleware: Add request/response filters via Mailcoach::extend():

   Mailcoach::extend(function ($mailcoach) {
       $mailcoach->onRequest(function ($request) {
           $request->headers->set('X-Custom-Header', 'value');
       });
   });
   

3. Webhook Handling: Use Laravel’s HandleIncomingWebhook trait to validate and process Mailcoach webhooks:

   class MailcoachWebhookHandler extends HandlesWebhooks {
       protected $signingKey = 'your_webhook_signing_key';
   }
   

Performance Tips

• Batch Operations: Use Mailcoach’s bulk endpoints (e.g., updateSubscribers()) for >100 subscribers.
• Caching: Cache emailLists() or campaigns() if rarely updated:

  Cache::remember('mailcoach_lists', now()->addHours(1), function () {
      return Mailcoach::emailLists();
  });