Laravel Mailcoach Mailgun Feedback Laravel Package

Getting Started

Minimal Setup Steps

1. Installation

   composer require spatie/laravel-mailcoach-mailgun-feedback
   

   Publish the config file:

   php artisan vendor:publish --provider="Spatie\MailcoachMailgunFeedback\MailcoachMailgunFeedbackServiceProvider"
   

2. Configuration Update .env with your Mailgun API key and webhook URL:

   MAILGUN_API_KEY=your_api_key
   MAILGUN_WEBHOOK_URL=https://your-app.com/mailgun-webhook
   

3. Webhook Endpoint Add the webhook route in routes/web.php:

   Route::post('/mailgun-webhook', [\Spatie\MailcoachMailgunFeedback\MailgunFeedbackController::class, 'handle']);
   

4. First Use Case Trigger a Mailcoach campaign via Mailgun. The package will automatically process feedback (opens, clicks, bounces) when Mailgun sends webhook events.

Implementation Patterns

Core Workflow

1. Webhook Handling

   • Mailgun sends feedback events (e.g., opened, clicked, bounced) to your /mailgun-webhook endpoint.
   • The controller validates the event signature and dispatches a FeedbackProcessed event.

2. Event Processing

   • Listen to FeedbackProcessed in an event handler:

     use Spatie\MailcoachMailgunFeedback\Events\FeedbackProcessed;
     
     public function handle(FeedbackProcessed $event) {
         $feedback = $event->feedback;
         // Log, update analytics, or trigger actions (e.g., unsubscribe)
     }
     

3. Integration with Mailcoach

   • Use the Mailcoach facade to fetch campaigns/recipients:

     use Spatie\Mailcoach\Facades\Mailcoach;
     
     $campaign = Mailcoach::campaigns()->find($feedback->campaign_id);
     

4. Batch Processing

   • For high-volume campaigns, queue the FeedbackProcessed event:

     event(new FeedbackProcessed($feedback))->toQueue();
     

Advanced Patterns

• Custom Feedback Types Extend the Feedback model to add custom fields:

  use Spatie\MailcoachMailgunFeedback\Models\Feedback;
  
  class CustomFeedback extends Feedback {
      protected $casts = [
          'custom_field' => 'string',
      ];
  }
  

• Webhook Retries Implement a retry mechanism for failed webhook deliveries using Laravel’s retry helper or a queue job.

• Analytics Dashboard Aggregate feedback data in a custom table (e.g., feedback_stats) for reporting:

  Feedback::query()
      ->where('event_type', 'opened')
      ->groupBy('campaign_id')
      ->get(['campaign_id', \DB::raw('count(*) as opens')]);
  

Gotchas and Tips

Pitfalls

1. Webhook Signature Validation

   • Mailgun sends a X-Mailgun-Signature header. Ensure your .env has:

     MAILGUN_WEBHOOK_SECRET=your_webhook_signing_key
     

   • Debugging: If validation fails, check the X-Mailgun-Timestamp and X-Mailgun-Signature headers manually.

2. Timezone Mismatches

   • Mailgun timestamps are in UTC. Convert to your local timezone in handlers:

     $feedback->created_at = $feedback->created_at->setTimezone('Europe/Amsterdam');
     

3. Duplicate Events

   • Mailgun may retry failed webhooks. Use feedback->event_id to deduplicate:

     if (!Feedback::where('event_id', $feedback->event_id)->exists()) {
         Feedback::create($feedbackData);
     }
     

4. Rate Limiting

   • High-volume campaigns may hit Laravel’s request limits. Use queue workers:

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

Tips

1. Testing Webhooks

   • Use Mailgun’s webhook tester or curl:

     curl -X POST https://your-app.com/mailgun-webhook \
          -H "X-Mailgun-Signature: YOUR_SIGNATURE" \
          -H "X-Mailgun-Timestamp: 1234567890" \
          -d 'event=opened&recipient=test@example.com'
     

2. Logging Feedback

   • Log raw feedback data for debugging:

     \Log::debug('Mailgun feedback', ['data' => $request->all()]);
     

3. Extending Feedback Model

   • Override the Feedback model to add custom logic:

     namespace App\Models;
     
     use Spatie\MailcoachMailgunFeedback\Models\Feedback as BaseFeedback;
     
     class Feedback extends BaseFeedback {
         protected static function booted() {
             static::created(function ($feedback) {
                 // Trigger actions (e.g., send survey)
             });
         }
     }
     

4. Performance Optimization

   • Batch inserts for bulk feedback:

     Feedback::insert($feedbackDataArray);
     

   • Use database indexes on event_id, campaign_id, and recipient_email.

5. Security

   • Restrict the webhook endpoint to Mailgun’s IPs (check Mailgun’s IP ranges).
   • Use Laravel’s throttle middleware for abuse protection:

     Route::post('/mailgun-webhook', [\Spatie\MailcoachMailgunFeedback\MailgunFeedbackController::class, 'handle'])
          ->middleware('throttle:100,1');