Laravel Mailcoach Sendgrid Feedback Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-mailcoach-sendgrid-feedback
   

   Publish the config file:

   php artisan vendor:publish --provider="Spatie\MailcoachSendgridFeedback\MailcoachSendgridFeedbackServiceProvider"
   

2. Configuration:

   • Ensure spatie/laravel-mailcoach is installed and configured.
   • Set your SendGrid API key in .env:

     SENDGRID_API_KEY=your_api_key_here
     

   • Configure the package in config/mailcoach-sendgrid-feedback.php:

     'webhook_secret' => env('MAILCOACH_SENDGRID_FEEDBACK_WEBHOOK_SECRET'),
     'webhook_url' => env('MAILCOACH_SENDGRID_FEEDBACK_WEBHOOK_URL'),
     

3. First Use Case:

   • Set up a webhook endpoint in SendGrid to forward feedback events to your Laravel app.
   • Register the webhook route in routes/web.php:

     Route::post('/mailcoach/sendgrid-feedback', [\Spatie\MailcoachSendgridFeedback\Http\Controllers\SendgridFeedbackController::class, 'handle']);
     

   • Send a test email campaign via Mailcoach and verify feedback (e.g., bounces, clicks) is processed automatically.

Implementation Patterns

Workflow Integration

1. Webhook Handling:

   • SendGrid forwards feedback events (e.g., bounce, click, open) to your Laravel app via HTTP POST.
   • The package automatically validates the webhook signature using the webhook_secret and processes the payload.

2. Feedback Processing:

   • Extend the Spatie\MailcoachSendgridFeedback\FeedbackProcessors\FeedbackProcessor class to customize how feedback is handled:

     namespace App\MailcoachSendgridFeedback;
     
     use Spatie\MailcoachSendgridFeedback\FeedbackProcessors\FeedbackProcessor;
     
     class CustomFeedbackProcessor extends FeedbackProcessor
     {
         public function processBounce($bounce)
         {
             // Custom logic for bounces (e.g., log to a custom table)
         }
     
         public function processClick($click)
         {
             // Custom logic for clicks (e.g., track in analytics)
         }
     }
     

   • Bind your processor in AppServiceProvider:

     public function boot()
     {
         $this->app->bind(
             \Spatie\MailcoachSendgridFeedback\FeedbackProcessors\FeedbackProcessor::class,
             \App\MailcoachSendgridFeedback\CustomFeedbackProcessor::class
         );
     }
     

3. Campaign Tracking:

   • Use Mailcoach’s built-in reports to visualize feedback data (e.g., open rates, bounce rates).
   • Query processed feedback via Eloquent:

     use Spatie\Mailcoach\Models\Feedback;
     
     $bounces = Feedback::where('type', 'bounce')->get();
     

4. Event Listeners:

   • Listen for feedback events to trigger custom actions:

     use Spatie\MailcoachSendgridFeedback\Events\FeedbackProcessed;
     
     FeedbackProcessed::listen(function ($feedback) {
         // Example: Send Slack notification for hard bounces
         if ($feedback->type === 'bounce' && $feedback->severity === 'hard') {
             // Notify team
         }
     });
     

Gotchas and Tips

Pitfalls

1. Webhook Secret Mismatch:

   • Ensure the webhook_secret in .env matches the one configured in SendGrid’s webhook settings.
   • Debugging: Check Laravel logs for 403 Forbidden errors if the secret is incorrect.

2. Payload Validation:

   • SendGrid sends feedback in a nested JSON structure. The package validates this, but malformed payloads may cause silent failures.
   • Tip: Log raw payloads during development:

     \Log::debug('Raw SendGrid feedback payload:', ['payload' => $request->getContent()]);
     

3. Rate Limiting:

   • High-volume campaigns may overwhelm your server. Use Laravel’s queue system to process feedback asynchronously:

     // In CustomFeedbackProcessor
     public function processFeedback($feedback)
     {
         \Queue::push(new ProcessFeedbackJob($feedback));
     }
     

4. Time Zone Sync:

   • SendGrid timestamps may not align with your Laravel app’s time zone. Normalize timestamps in your processor:

     $feedback->created_at = now();
     

Tips

1. Testing Webhooks Locally:

   • Use tools like ngrok to expose your local MAILCOACH_SENDGRID_FEEDBACK_WEBHOOK_URL to SendGrid.
   • Simulate feedback with SendGrid’s API or Postman.

2. Custom Feedback Types:

   • Extend the Feedback model to add custom fields:

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

3. Monitoring:

   • Track webhook delivery status in SendGrid’s dashboard. Set up alerts for failed deliveries.
   • Use Laravel Horizon to monitor queued feedback processing.

4. Security:

   • Restrict the webhook endpoint to SendGrid’s IP ranges (check SendGrid’s docs) to prevent abuse.
   • Use Laravel’s VerifyCsrfToken middleware for additional protection (though the package handles CSRF via the secret).

5. Performance:

   • Batch process feedback for large campaigns to reduce database load:

     // In CustomFeedbackProcessor
     public function processFeedback($feedback)
     {
         if (collect($this->buffer)->count() >= 100) {
             $this->flushBuffer();
         }
         $this->buffer[] = $feedback;
     }