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/api
   

3. First Use Case: Fetch 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: Built-in pagination helpers (next(), total(), etc.).

Implementation Patterns

Core Workflows

1. CRUD Operations:

   // Create
   $list = Mailcoach::createEmailList(['name' => 'Newsletter']);
   $subscriber = Mailcoach::createSubscriber(
       emailListUuid: $list->uuid,
       attributes: ['email' => 'user@example.com']
   );
   
   // Read
   $campaign = Mailcoach::campaign('campaign-uuid');
   
   // Update
   $campaign->subject = 'Updated Subject';
   $campaign->save();
   
   // Delete
   $subscriber->delete();
   

2. Pagination Handling:

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

3. Campaign Management:

   $campaign = Mailcoach::createCampaign([
       'email_list_uuid' => 'list-uuid',
       'name' => 'Welcome Email',
       'fields' => ['title' => 'Welcome!'],
   ]);
   $campaign->sendTest('test@example.com'); // Test send
   $campaign->send(); // Live send
   

4. Subscriber Filtering:

   $subscribers = Mailcoach::emailList('list-uuid')
       ->subscribers(['filter[email]=gmail.com']);
   

Integration Tips

• Event Listeners: Trigger actions post-campaign (e.g., analytics) via sent events.
• Queue Jobs: Offload heavy operations (e.g., bulk subscriber updates) to queues.
• Service Layer: Abstract SDK calls in a service class for cleaner controllers:

  class MailcoachService {
      public function syncSubscribers(array $emails) {
          foreach ($emails as $email) {
              Mailcoach::createSubscriber(/* ... */);
          }
      }
  }
  

Gotchas and Tips

Pitfalls

1. Pagination Edge Cases:

   • Always check next() returns null before looping (avoid infinite loops).
   • Use total() to pre-calculate iterations if needed.

2. API Token Misconfiguration:

   • Verify MAILCOACH_API_TOKEN and MAILCOACH_API_ENDPOINT in .env.
   • Test with Mailcoach::fake() in tests to avoid real API calls:

     Mailcoach::fake();
     Mailcoach::createCampaign([/* ... */]);
     Mailcoach::assertSent();
     

3. Subscriber Confirmation:

   • Confirmed/unsubscribed states are managed via confirm()/unsubscribe()—no direct DB updates.

4. Template Fields:

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

Debugging

• HTTP Errors: Check Mailcoach::getLastResponse() for raw API responses.
• Rate Limiting: Implement retries with exponential backoff for 429 errors.
• UUID Validation: Validate UUIDs (e.g., Str::isUuid()) before passing to SDK methods.

Extension Points

1. Custom Resources: Extend Spatie\MailcoachSdk\Resources\Resource to add custom attributes:

   class CustomSubscriber extends Subscriber {
       public function getCustomAttribute() { /* ... */ }
   }
   

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

   Mailcoach::extend(function ($mailcoach) {
       $mailcoach->before(function ($request) {
           // Modify request
       });
   });
   

3. Testing: Use Mailcoach::fake() to mock API calls and assert interactions:

   Mailcoach::fake();
   Mailcoach::createCampaign([/* ... */]);
   Mailcoach::assertSentTimes(1);
   

Config Quirks

• Endpoint Overrides: Use Mailcoach::setEndpoint() dynamically for multi-instance setups.
• Default Pagination: Override via config:

  'pagination' => [
      'limit' => 500, // Default per-page limit
  ],