Laravel Mailcoach Postmark Setup Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require spatie/laravel-mailcoach-postmark-setup
   

   Publish the config file:

   php artisan vendor:publish --provider="Spatie\MailcoachPostmarkSetup\MailcoachPostmarkSetupServiceProvider"
   

2. Configuration Edit config/mailcoach-postmark-setup.php with your Postmark API token and server token.

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

   php artisan mailcoach:postmark:setup
   

   This creates a Postmark server token, sets up webhooks, and configures tracking domains.

Implementation Patterns

Workflow Integration

1. Pre-Campaign Setup

   • Use the mailcoach:postmark:setup command before launching campaigns to ensure Postmark is configured for tracking and feedback loops.
   • Automate this in a deployment pipeline or pre-campaign checklist.

2. Webhook Handling

   • Postmark webhooks (e.g., for bounces, complaints) are automatically configured. Ensure your Laravel app can handle these via Mailcoach’s built-in webhook routes.

3. Dynamic Configuration

   • Extend the PostmarkSetup class to customize behavior (e.g., additional webhook endpoints or server token permissions):

     use Spatie\MailcoachPostmarkSetup\PostmarkSetup;
     
     class CustomPostmarkSetup extends PostmarkSetup {
         protected function configureServerToken(): void {
             $this->serverToken->permissions = ['inbound', 'outbound', 'message_stream'];
         }
     }
     

4. Testing

   • Use Postmark’s sandbox mode (via config) to test campaigns without sending real emails:

     'sandbox' => env('MAILCOACH_POSTMARK_SANDBOX', false),
     

Gotchas and Tips

Pitfalls

1. API Token Permissions

   • Ensure your Postmark API token has server_tokens:read_write permissions. Missing this will fail during setup.

2. Webhook Verification

   • Postmark requires webhook URLs to be HTTPS. Use config('mailcoach-postmark-setup.webhook_url') to verify the endpoint matches your app’s route.

3. Tracking Domains

   • If using custom tracking domains, pre-configure them in Postmark before running the setup command to avoid errors.

4. Rate Limits

   • Postmark’s API has rate limits. Batch operations (e.g., creating many server tokens) may hit limits. Use retries or chunking.

Debugging

• Logs: Enable debug mode in config/mailcoach-postmark-setup.php to log API responses:

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

• Manual Verification: Cross-check Postmark’s dashboard with Laravel logs to confirm webhook configurations.

Extension Points

1. Custom Webhooks Override handleWebhook() in a custom service provider to process Postmark events differently:

   public function boot(): void {
       $this->app->make(\Spatie\MailcoachPostmarkSetup\PostmarkSetup::class)
           ->setWebhookHandler(function ($event) {
               // Custom logic
           });
   }
   

2. Postmark Client Access the underlying Postmark client for advanced use:

   $postmark = app(\Spatie\MailcoachPostmarkSetup\PostmarkSetup::class)->getPostmarkClient();
   

3. Environment-Specific Config Use Laravel’s config() helper to dynamically set options per environment:

   'server_token_permissions' => config('app.env') === 'production' ? ['inbound'] : [],