Laravel Mailcoach Postmark Feedback Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-mailcoach-postmark-feedback
   

   Publish the config file:

   php artisan vendor:publish --provider="Spatie\MailcoachPostmarkFeedback\MailcoachPostmarkFeedbackServiceProvider"
   

2. Configuration:

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

     POSTMARK_API_TOKEN=your_postmark_token_here
     

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

     'webhook_secret' => env('MAILCOACH_POSTMARK_FEEDBACK_WEBHOOK_SECRET'),
     'postmark_api_token' => env('POSTMARK_API_TOKEN'),
     

3. First Use Case:

   • Trigger a Postmark webhook by sending an email via Mailcoach.
   • Postmark will send feedback (e.g., opens, clicks) to your configured webhook endpoint.
   • The package processes this feedback and updates Mailcoach records automatically.

Implementation Patterns

Workflow Integration

1. Webhook Setup:

   • Register the webhook route in routes/web.php:

     Route::post('/mailcoach/postmark-feedback', [\Spatie\MailcoachPostmarkFeedback\Http\Controllers\PostmarkFeedbackController::class, 'handle']);
     

   • Protect the route with middleware (e.g., web) and ensure it’s accessible via Postmark’s IP ranges or a secret.

2. Processing Feedback:

   • The package listens for Postmark’s Message Opened and Message Clicked events.
   • Use Mailcoach’s existing campaign and subscriber models to track engagement:

     use Spatie\Mailcoach\Models\Campaign;
     use Spatie\Mailcoach\Models\Subscriber;
     
     $campaign = Campaign::find($id);
     $subscriber = $campaign->subscribers()->where('email', $email)->first();
     

3. Custom Logic:

   • Extend the feedback processing by overriding the Spatie\MailcoachPostmarkFeedback\Processors\FeedbackProcessor class.
   • Example: Add custom analytics or trigger actions (e.g., send a follow-up email):

     namespace App\Services;
     
     use Spatie\MailcoachPostmarkFeedback\Processors\FeedbackProcessor;
     
     class CustomFeedbackProcessor extends FeedbackProcessor
     {
         public function handleOpened($campaign, $subscriber, $eventData)
         {
             // Custom logic here
             parent::handleOpened($campaign, $subscriber, $eventData);
         }
     }
     

   • Bind your custom processor in AppServiceProvider:

     $this->app->bind(
         \Spatie\MailcoachPostmarkFeedback\Processors\FeedbackProcessor::class,
         App\Services\CustomFeedbackProcessor::class
     );
     

4. Batch Processing:

   • For large campaigns, use Mailcoach’s queue system to process feedback asynchronously:

     $this->app->bind(
         \Spatie\MailcoachPostmarkFeedback\Processors\FeedbackProcessor::class
     )->when(Queue::class)->needs(\Spatie\MailcoachPostmarkFeedback\Processors\FeedbackProcessor::class);
     

Gotchas and Tips

Pitfalls

1. Webhook Secret Mismatch:

   • Ensure the webhook_secret in config/mailcoach-postmark-feedback.php matches the secret configured in Postmark’s webhook settings.
   • Debugging: Check Laravel logs for 403 Forbidden errors if the secret is incorrect.

2. Duplicate Feedback:

   • Postmark may retry webhook deliveries. Use Laravel’s unique() or database constraints to avoid duplicate records:

     $exists = \DB::table('mailcoach_feedback')->where('event_uuid', $eventData['MessageID'])->exists();
     if (!$exists) {
         // Process feedback
     }
     

3. Timezone Issues:

   • Postmark timestamps are in UTC. Ensure your Laravel app’s timezone (config/app.php) matches to avoid misaligned logs or reports.

4. Missing Subscribers:

   • If a Postmark feedback event references an unknown subscriber, the package skips processing. Handle this gracefully:

     if (!$subscriber) {
         \Log::warning("Subscriber not found for email: {$email}");
         return;
     }
     

Debugging

1. Enable Logging:

   • Add debug logs in config/mailcoach-postmark-feedback.php:

     'log_processed_events' => env('MAILCOACH_POSTMARK_FEEDBACK_LOG_EVENTS', false),
     

   • Check storage/logs/laravel.log for processed events.

2. Test Webhooks Locally:

   • Use tools like ngrok to expose your local handle endpoint to Postmark for testing:

     ngrok http 8000
     

   • Configure Postmark to send test webhooks to your ngrok URL.

3. Postmark Event Validation:

   • Verify the X-Postmark-Signature header matches the expected HMAC-SHA256 signature:

     $signature = hash_hmac('sha256', $rawBody, env('POSTMARK_API_TOKEN'));
     if (!hash_equals($request->header('X-Postmark-Signature'), $signature)) {
         abort(403, 'Invalid signature');
     }
     

Extension Points

1. Custom Feedback Models:

   • Extend the mailcoach_feedback table or create a pivot table for additional metadata:

     Schema::create('mailcoach_feedback_extended', function (Blueprint $table) {
         $table->id();
         $table->foreignId('feedback_id')->constrained('mailcoach_feedback');
         $table->string('custom_field')->nullable();
         $table->timestamps();
     });
     

2. Event Dispatching:

   • Dispatch custom events when feedback is processed:

     event(new \App\Events\FeedbackProcessed($campaign, $subscriber, $eventData));
     

   • Listen for these events in your application:

     Event::listen(\App\Events\FeedbackProcessed::class, function ($event) {
         // Trigger analytics, notifications, etc.
     });
     

3. Rate Limiting:

   • Protect your webhook endpoint from abuse with Laravel’s throttle middleware:

     Route::post('/mailcoach/postmark-feedback', [/* ... */])->middleware('throttle:60,1');