Laravel Mailcoach Mailgun Setup Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require spatie/laravel-mailcoach-mailgun-setup
   

   Publish the config file:

   php artisan vendor:publish --provider="Spatie\MailcoachMailgunSetup\MailcoachMailgunSetupServiceProvider"
   

2. Configuration Edit .env with your Mailgun API credentials:

   MAILGUN_DOMAIN=your-domain.mailgun.org
   MAILGUN_SECRET_KEY=your-api-key
   

3. First Use Case Run the setup command to configure Mailgun for Mailcoach:

   php artisan mailcoach:mailgun:setup
   

   This creates:

   • A dedicated Mailcoach webhook route in Mailgun.
   • A Mailcoach tracking domain (e.g., mail.yourdomain.com).
   • Required Mailgun routes for open/click tracking.

Implementation Patterns

Workflow Integration

1. Pre-Campaign Setup

   • Run mailcoach:mailgun:setup once after Mailcoach installation.
   • Verify the tracking domain (e.g., mail.yourdomain.com) is added to Mailgun’s Domains tab.

2. Campaign-Specific Actions

   • Use Mailcoach’s built-in UI to create campaigns; this package handles the Mailgun backend.
   • For custom scripts, leverage Mailcoach’s events to trigger Mailgun-specific logic.

3. Webhook Handling

   • Mailgun sends open/click events to /mailcoach/webhooks/mailgun.
   • Extend Spatie\MailcoachMailgunSetup\WebhookHandler to customize event processing (e.g., logging, analytics).

Common Patterns

• Domain Management Use MailcoachMailgunSetup::createTrackingDomain() to dynamically add domains:

  $domain = MailcoachMailgunSetup::createTrackingDomain('mail.yourdomain.com');
  

• Route Configuration Register custom Mailgun routes via MailcoachMailgunSetup::addRoute():

  MailcoachMailgunSetup::addRoute('campaigns/{campaignId}/opens', 'post');
  

• Event Listeners Listen for mailcoach.mailgun.webhook.received to process events:

  Event::listen('mailcoach.mailgun.webhook.received', function ($event) {
      // Custom logic (e.g., update CRM)
  });
  

Gotchas and Tips

Pitfalls

1. Webhook Verification

   • Mailgun requires a secret token for webhook verification. Ensure .env has:

     MAILGUN_WEBHOOK_SECRET=your-unique-secret
     

   • If webhooks fail, check Mailgun’s Webhooks tab for errors and regenerate the secret.

2. DNS Configuration

   • The tracking domain (e.g., mail.yourdomain.com) must have:
     • A CNAME pointing to mailgun.org (or your Mailgun subdomain).
     • SPF/DKIM/DMARC records configured in Mailgun’s Domains tab.
   • Test with dig TXT yourdomain.com to verify records.

3. Rate Limits

   • Mailgun’s free tier has 1,000 emails/day. Exceeding this may trigger temporary bans.
   • Monitor usage via Mailgun’s Analytics dashboard.

4. Idempotency

   • The setup command is idempotent but may overwrite existing routes. Backup Mailgun routes before running.

Debugging

• Webhook Failures Enable debug logging in config/mailcoach-mailgun-setup.php:

  'debug' => env('MAILGUN_DEBUG', false),
  

  Check storage/logs/laravel.log for webhook payloads.

• Command Errors Run with --verbose:

  php artisan mailcoach:mailgun:setup --verbose
  

Extension Points

1. Custom Webhook Logic Override the webhook handler:

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       $this->app->bind(
           \Spatie\MailcoachMailgunSetup\WebhookHandler::class,
           \App\CustomMailgunWebhookHandler::class
       );
   }
   

2. Dynamic Domain Setup Extend the setup command to fetch domains from a database:

   // app/Console/Commands/SetupMailgun.php
   protected function getTrackingDomains()
   {
       return Domain::where('is_tracking', true)->pluck('name')->toArray();
   }
   

3. Event Dispatching Dispatch custom events after webhook processing:

   Event::dispatch(new MailgunEventProcessed($event->payload));