Mailcoach Mailer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/mailcoach-mailer
   

   For Laravel, use the dedicated package: spatie/laravel-mailcoach-mailer.

2. Configuration: Add the transport to your Symfony Mailer configuration (or Laravel's config/mail.php if using the Laravel wrapper):

   // config/mail.php (Laravel)
   'mailers' => [
       'mailcoach' => [
           'transport' => 'mailcoach',
           'host' => env('MAILCOACH_HOST', 'http://localhost:8000'),
           'token' => env('MAILCOACH_TOKEN'),
       ],
   ],
   

3. First Use Case: Send a test email via Mailcoach:

   use Symfony\Component\Mailer\MailerInterface;
   
   $mailer = new Mailer([
       new MailcoachTransport('http://localhost:8000', 'your-api-token'),
   ]);
   
   $email = (new Email())
       ->to('recipient@example.com')
       ->subject('Test Email')
       ->html('<h1>Hello from Mailcoach!</h1>');
   
   $mailer->send($email);
   

Key Files to Review

• config/mail.php: Mailer configuration (Laravel).
• MailcoachTransport class: Core transport logic.
• Symfony Mailer docs: Understand how transports integrate with Symfony Mailer.

Implementation Patterns

Core Workflows

1. Transactional Emails: Use Mailcoach for templated emails (e.g., password resets, notifications) while leveraging Mailcoach’s segmentation and analytics.

   $mailer->send(
       (new Email())
           ->to('user@example.com')
           ->subject('Your Invoice')
           ->html(view('emails.invoice', ['total' => $total]))
   );
   

2. Dynamic Recipients: Batch-send emails to segmented lists (e.g., newsletters) using Mailcoach’s API:

   $mailer->send(
       (new Email())
           ->to(['user1@example.com', 'user2@example.com']) // or use Mailcoach’s list API
           ->subject('Weekly Digest')
           ->html(view('emails.digest'))
   );
   

3. Template Integration: Pre-design emails in Mailcoach’s UI, then reference them by ID:

   $mailer->send(
       (new Email())
           ->to('user@example.com')
           ->subject('Welcome')
           ->html('<mailcoach-template id="123" />') // Renders Mailcoach template
   );
   

Integration Tips

• Laravel Notifications: Extend Mailable to use Mailcoach:

  class WelcomeMail extends Mailable {
      public function build() {
          return $this->subject('Welcome')
                      ->withMailcoachTemplate(123)
                      ->view('emails.welcome');
      }
  }
  

• Queueing: Use Laravel queues to defer Mailcoach sends:

  Mail::to('user@example.com')->mailcoach()->queue(new WelcomeMail());
  

• Event Listeners: Trigger Mailcoach emails on model events (e.g., created):

  User::created(function ($user) {
      Mail::to($user->email)->mailcoach()->send(new WelcomeMail());
  });
  

• API Integration: Fetch Mailcoach campaigns dynamically:

  $client = new MailcoachClient('http://mailcoach:token@localhost:8000');
  $campaign = $client->campaigns()->find(1);
  

Gotchas and Tips

Pitfalls

1. Authentication:

   • Ensure the MAILCOACH_TOKEN is correct and has permissions for the API endpoint.
   • Tokens are not the same as Mailcoach’s admin panel credentials.

2. Template Rendering:

   • Mailcoach templates (<mailcoach-template id="..." />) must be defined in the Mailcoach UI first.
   • Fallback to raw HTML if the template fails to render:

     $email->html(view('fallback.email'));
     

3. Rate Limiting:

   • Mailcoach may throttle API requests. Use Laravel’s queue system to avoid timeouts:

     php artisan queue:work --sleep=3 --tries=3
     

4. CORS Issues:

   • If Mailcoach is hosted separately, ensure CORS is configured to allow your Laravel app’s domain.

5. Debugging:

   • Enable Symfony Mailer’s debug mode:

     $mailer = new Mailer([new MailcoachTransport(..., true)]);
     

   • Check Mailcoach’s API logs for failed requests.

Tips

1. Environment-Specific Config: Use Laravel’s .env to switch between local/staging/prod Mailcoach instances:

   MAILCOACH_HOST=mailcoach.staging.app
   MAILCOACH_TOKEN=staging_token_here
   

2. Testing:

   • Use Mailcoach’s "test mode" to preview emails without sending:

     config(['mail.mailers.mailcoach.options.test_mode' => true]);
     

   • Mock the transport in PHPUnit:

     $this->partialMock(MailcoachTransport::class, [], function ($mock) {
         $mock->method('send')->willReturn(true);
     });
     

3. Performance:

   • Batch API calls for large recipient lists to reduce overhead.
   • Cache Mailcoach template responses if they’re static.

4. Extensions:

   • Custom Headers: Pass additional headers via the Email object:

     $email->getHeaders()->addTextHeader('X-Custom-Header', 'value');
     

   • Webhooks: Set up Mailcoach webhooks to trigger Laravel events (e.g., on email opens/clicks).

5. Fallback Transport: Combine Mailcoach with another transport (e.g., SMTP) for redundancy:

   $mailer = new Mailer([
       new MailcoachTransport(...),
       new SmtpTransport(...),
   ]);