Mailcoach Sdk Php Laravel Package

Getting Started

1. Install the SDK via Composer:

   composer require spatie/mailcoach-sdk-php
   

2. Configure API access using a Mailcoach API token (v3+ required). In Laravel, store it in .env as MAILCOACH_API_TOKEN, and optionally MAILCOACH_API_URL (defaults to https://mailcoach.app).
3. Get your first client instance:

   use Spatie\MailcoachSdk\MailcoachSdk;
   
   $mailcoach = new MailcoachSdk(env('MAILCOACH_API_TOKEN'), env('MAILCOACH_API_URL'));
   

4. First use case: Subscribe a user to a list by list UUID:

   $mailcoach->subscribers()->create('list-uuid', 'john@example.com', ['name' => 'John Doe']);
   

Start with subscribers(), lists(), and campaigns() methods — these are the core entry points for most day-to-day operations.

Implementation Patterns

• Laravel Service Binding: Bind the SDK as a singleton in a service provider for DI:

  $this->app->singleton(\Spatie\MailcoachSdk\MailcoachSdk::class, function ($app) {
      return new \Spatie\MailcoachSdk\MailcoachSdk(
          config('services.mailcoach.token'),
          config('services.mailcoach.url')
      );
  });
  

• Bulk operations: Use subscribers()->bulkCreate() or updateMultiple() for high-volume syncs (e.g., after importing users).
• Event-driven syncing: Trigger SDK calls via Laravel events (e.g., UserRegistered → subscribe to welcome list).
• Campaign automation: Trigger sends or duplications via campaigns()->duplicate('uuid'), then monitor status via campaigns()->get('uuid').
• Testing: Mock the SDK using Mockery or prophecy — its clean interfaces make unit tests fast and reliable.

Gotchas and Tips

• Rate limits: Mailcoach enforces ~50 requests/second; batch operations and add jitter/circuit-breaker logic in high-throughput scenarios.
• UUID vs. slug: Some resources (e.g., lists) accept slugs or UUIDs — prefer UUIDs for reliability (slugs can change).
• Status codes: SDK throws HttpClientException for 4xx/5xx; always wrap critical calls in try/catch or use Laravel’s RateLimiter if sending many requests.
• Nested fields: Subscriber metadata (tags, custom fields) must be passed as associative arrays — no stringification needed.
• Missing v3 features: While basic ops (create/update/unsubscribe) are covered, some advanced features (e.g., automations, templates, webhooks) may require direct request() calls — check MailcoachSdk::request() for fallback.
• Cache smartly: List metadata (e.g., field names, segments) rarely changes — cache them using Laravel’s cache with short TTLs (~5 min) if reused often.