Laravel Mailcoach Ses Feedback Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require spatie/laravel-mailcoach-ses-feedback

Publish the config file:

php artisan vendor:publish --provider="Spatie\MailcoachSesFeedback\MailcoachSesFeedbackServiceProvider"

2. Configure AWS SES: Ensure your config/mailcoach-ses-feedback.php includes valid AWS credentials and SES region:

   'aws' => [
       'key' => env('AWS_ACCESS_KEY_ID'),
       'secret' => env('AWS_SECRET_ACCESS_KEY'),
       'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
   ],
   

3. First Use Case: Run the feedback processor to fetch and process SES bounce/complaint notifications:

   php artisan mailcoach:process-ses-feedback
   

   Schedule this command in app/Console/Kernel.php:

   $schedule->command('mailcoach:process-ses-feedback')->hourly();
   

Where to Look First

• Documentation: Mailcoach SES Feedback Docs
• Config: config/mailcoach-ses-feedback.php (AWS settings, processing rules)
• Commands: artisan mailcoach:process-ses-feedback (core command)
• Events: Spatie\MailcoachSesFeedback\Events\FeedbackProcessed (extendable hooks)

Implementation Patterns

Workflow Integration

1. SES Feedback Loop:

   • Configure SES to forward bounce/complaint notifications to your Mailcoach queue.
   • Use the mailcoach:process-ses-feedback command to parse and update Mailcoach records.
   • Example SES SNS topic subscription (via AWS Console or CLI):

     aws sns subscribe --topic-arn "arn:aws:sns:us-east-1:123456789012:mailcoach-feedback" --protocol sqs --notification-endpoint "https://sqs.us-east-1.amazonaws.com/123456789012/mailcoach-queue"
     

2. Campaign-Specific Processing:

   • Filter feedback by campaign ID using the campaignId config option:

     'campaign_id' => env('MAILCOACH_CAMPAIGN_ID', null), // Process only this campaign
     

   • Override globally in config/mailcoach-ses-feedback.php or per-command:

     php artisan mailcoach:process-ses-feedback --campaign-id=123
     

3. Event-Driven Extensions:

   • Listen to FeedbackProcessed events to trigger custom logic (e.g., analytics, user notifications):

     use Spatie\MailcoachSesFeedback\Events\FeedbackProcessed;
     
     FeedbackProcessed::listen(function (FeedbackProcessed $event) {
         // Log or act on processed feedback
         Log::info('Processed feedback for email: ' . $event->email);
     });
     

4. Batch Processing:

   • Process feedback in chunks to avoid timeouts:

     // In a custom command or service
     $processor = app(\Spatie\MailcoachSesFeedback\FeedbackProcessor::class);
     $processor->processFeedbackInBatches(100); // Process 100 records at a time
     

Common Use Cases

Gotchas and Tips

Pitfalls

1. AWS Credentials:

   • Gotcha: Hardcoding AWS keys in config. Always use environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY).
   • Fix: Validate credentials before processing:

     if (!app(\Spatie\MailcoachSesFeedback\FeedbackProcessor::class)->isAwsConfigured()) {
         throw new \RuntimeException('AWS credentials not configured.');
     }
     

2. SES Notification Format:

   • Gotcha: SES notifications must be in JSON format. If using SNS/SQS, ensure the message is parsed correctly.
   • Fix: Add validation in a custom processor:

     public function processFeedback(string $feedbackJson): void
     {
         $data = json_decode($feedbackJson, true);
         if (json_last_error() !== JSON_ERROR_NONE) {
             throw new \InvalidArgumentException('Invalid JSON feedback.');
         }
         // ... rest of processing
     }
     

3. Duplicate Processing:

   • Gotcha: SES may resend notifications. Use the notificationId field to deduplicate:

     // In your FeedbackProcessed listener
     if (Feedback::where('notification_id', $event->notificationId)->exists()) {
         return; // Skip duplicate
     }
     

4. Timeouts:

   • Gotcha: Processing large batches may hit AWS API limits or timeout.
   • Fix: Use pagination or batch processing:

     $processor->processFeedbackInBatches(50); // AWS SES API limit is 100, but 50 is safer
     

5. Mailcoach Sync Issues:

   • Gotcha: Feedback processing assumes Mailcoach campaigns/emails exist. Missing records will cause errors.
   • Fix: Add pre-processing checks:

     if (!\Spatie\Mailcoach\Models\Email::where('email', $event->email)->exists()) {
         Log::warning("Feedback for non-existent email: {$event->email}");
         return;
     }
     

Debugging Tips

1. Enable Verbose Logging:

   php artisan mailcoach:process-ses-feedback --verbose
   

   Or configure in config/mailcoach-ses-feedback.php:

   'log_level' => 'debug',
   

2. Test with Mock SES: Use the spatie/laravel-mailcoach-ses-feedback-mocker package to simulate feedback:

   composer require --dev spatie/laravel-mailcoach-ses-feedback-mocker
   

   Then run:

   php artisan mailcoach:mock-ses-feedback
   

3. Check AWS SES Metrics:

   • Monitor the Notifications Delivered metric in AWS CloudWatch for your SES topic.
   • Verify SQS queue depth if using SQS as an intermediary.

Extension Points

1. Custom Feedback Types: Extend the FeedbackProcessor to handle non-standard SES feedback:

   namespace App\Services;
   
   use Spatie\MailcoachSesFeedback\FeedbackProcessor;
   
   class CustomFeedbackProcessor extends FeedbackProcessor
   {
       protected function handleCustomFeedback(array $feedback): void
       {
           // Custom logic for non-bounce/complaint feedback
       }
   }
   

2. Database Observers: Add observers to Spatie\MailcoachSesFeedback\Models\Feedback for real-time reactions:

   use Spatie\MailcoachSesFeedback\Models\Feedback;
   
   Feedback::observe(FeedbackObserver::class);
   
   class FeedbackObserver
   {
       public function saved(Feedback $feedback)
       {
           if ($feedback->is_bounce) {
               // Trigger suppression logic
           }
       }
   }
   

3. Webhook Integration: Convert processed feedback into webhooks for third-party systems:

   FeedbackProcessed::listen(function (FeedbackProcessed $event) {
       Http::post('https://third-party-api.com/webhook', [
           'email' => $event->email,
           'status' => $event->type,
       ]);
   });
   

4. Custom Feedback Storage: Override the default Feedback model to store additional metadata:

   namespace App\Models;
   
   use Spatie\MailcoachSesFeedback\Models\Feedback;
   
   class CustomFeedback extends Feedback
   {
       protected $casts = [
           'custom_metadata' => 'array',
       ];
   }
   

   Then bind the model in AppServiceProvider:

   \Spatie\MailcoachSesFeedback\FeedbackProcessor::setFeedbackModel(CustomFeedback::class);
   

Configuration Quirks

1. AWS Region:

   • Ensure the region in config/mailcoach-ses-feedback.php matches your SES endpoint.
   • Example for Frankfurt:

     'region' => 'eu-central-1',
     

2. Notification Types:

   • SES sends two types of notifications: bounce and complaint. Configure which to process:

     'notification_types' => ['bounce', 'complaint'], // Default
     

3. Dry Runs:

   • Test