Laravel Mailcoach Ses Setup Laravel Package

Getting Started

Minimal Setup Steps

1. Installation

   composer require spatie/laravel-mailcoach-ses-setup
   

   Publish the config file:

   php artisan vendor:publish --provider="Spatie\MailcoachSesSetup\MailcoachSesSetupServiceProvider"
   

2. Configuration Edit .env with your AWS SES credentials:

   AWS_ACCESS_KEY_ID=your-access-key
   AWS_SECRET_ACCESS_KEY=your-secret-key
   AWS_DEFAULT_REGION=your-region (e.g., us-east-1)
   

3. First Use Case Run the SES setup command to verify and configure SES for Mailcoach:

   php artisan mailcoach:ses:setup
   

   This will:

   • Verify AWS credentials.
   • Check SES region.
   • Validate SES identity (verified email/domain).
   • Configure SES for production (if not already done).

Where to Look First

• Config File: config/mailcoach-ses-setup.php – Contains AWS SES settings, verification rules, and logging preferences.
• Artisan Commands: php artisan to explore available commands (mailcoach:ses:setup, mailcoach:ses:verify).
• Mailcoach Docs: Mailcoach SES Integration Guide for broader context.

Implementation Patterns

Workflow: SES Integration with Mailcoach

1. Pre-Campaign Setup

   • Use mailcoach:ses:setup to configure SES before sending campaigns.
   • Verify identities (emails/domains) via mailcoach:ses:verify:email or mailcoach:ses:verify:domain.

2. Daily Operations

   • Monitor SES Limits: Check quotas/usage via AWS Console or integrate with AWS SDK for programmatic checks.
   • Feedback Processing: Use the package’s core logic to parse SES bounce/complaint notifications (see Spatie\MailcoachSesSetup\ProcessFeedback). Example:

     use Spatie\MailcoachSesSetup\ProcessFeedback;
     
     $feedback = new ProcessFeedback();
     $feedback->process($rawNotification); // Parse SES feedback (bounce/complaint)
     

3. Automation

   • Schedule SES verification checks post-deployment:

     php artisan schedule:run
     

     Add to app/Console/Kernel.php:

     $schedule->command('mailcoach:ses:verify')->daily();
     

4. Testing

   • Use AWS_SDK_DATA environment variable to mock SES responses in tests:

     AWS_SDK_DATA=tests/AwsData
     

   • Test feedback processing with sample SES notifications (see AWS SES Notifications Docs).

Integration Tips

• Laravel Mail: Ensure your config/mail.php uses SES as the driver:

  'driver' => env('MAIL_DRIVER', 'ses'),
  

• Mailcoach Events: Listen to Mailcoach\Events\CampaignSent to trigger SES-specific actions:

  use Mailcoach\Events\CampaignSent;
  
  CampaignSent::listen(function ($campaign) {
      // Log SES metrics or trigger verification if needed
  });
  

• Logging: Enable debug logs in config/mailcoach-ses-setup.php to trace SES interactions:

  'log' => [
      'enabled' => true,
      'channel' => 'single',
  ],
  

Gotchas and Tips

Pitfalls

1. AWS Credentials

   • Issue: Hardcoded credentials in .env can leak. Use IAM roles or AWS Secrets Manager in production.
   • Fix: Rotate keys via AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY and restrict IAM permissions to SES-only actions.

2. SES Verification Delays

   • Issue: Email/domain verification in SES can take minutes to hours. The package doesn’t wait; it assumes verification is complete.
   • Fix: Manually verify via AWS Console first, or add a retry loop in your deployment script.

3. Sandbox Restrictions

   • Issue: SES sandbox mode blocks emails to unverified addresses. The package doesn’t auto-enable production.
   • Fix: Explicitly request production access via AWS Console before running mailcoach:ses:setup.

4. Feedback Processing

   • Issue: SES notifications must be signed with AWS KMS. Misconfigured keys cause parsing failures.
   • Fix: Ensure AWS_KMS_KEY_ID is set in .env if using encrypted notifications.

Debugging

• Command Errors: Check logs (storage/logs/laravel.log) for AWS SDK errors (e.g., InvalidAccessKeyId).
• SES API Limits: Throttling errors? Add retries with exponential backoff:

  use Aws\Common\Exception\RetryException;
  
  try {
      $ses->verifyEmailAddress(['EmailAddress' => 'test@example.com']);
  } catch (RetryException $e) {
      // Handle retry logic
  }
  

• Feedback Parsing: Validate SES notification JSON structure. Use dd($rawNotification) to inspect raw data.

Extension Points

1. Custom Verification Logic Override the verification process by extending Spatie\MailcoachSesSetup\Commands\SetupSesCommand:

   namespace App\Console\Commands;
   
   use Spatie\MailcoachSesSetup\Commands\SetupSesCommand as BaseCommand;
   
   class CustomSetupSesCommand extends BaseCommand {
       protected function verifySesIdentity() {
           // Custom logic (e.g., skip verification for staging)
       }
   }
   

2. Feedback Handlers Extend Spatie\MailcoachSesSetup\ProcessFeedback to add custom actions (e.g., auto-suppress bounces):

   namespace App\Services;
   
   use Spatie\MailcoachSesSetup\ProcessFeedback as BaseFeedback;
   
   class CustomFeedback extends BaseFeedback {
       protected function handleBounce($feedback) {
           // Custom bounce handling (e.g., update user record)
       }
   }
   

3. SES Metrics Integrate with Laravel Horizon or Telescope to track SES metrics:

   use Spatie\MailcoachSesSetup\Facades\MailcoachSesSetup;
   
   $metrics = MailcoachSesSetup::getSesMetrics();
   // Log or broadcast metrics
   

Config Quirks

• Region Mismatch: Ensure AWS_DEFAULT_REGION matches the SES region (e.g., us-east-1 for Virginia).
• Logging Channel: The log.channel in config defaults to single. Use stack for multi-environment logging:

  'log' => [
      'channel' => env('MAILCOACH_SES_LOG_CHANNEL', 'stack'),
  ],
  

• Environment Variables: The package expects MAILCOACH_SES_* prefixes for custom configs. Override via .env:

  MAILCOACH_SES_VERIFY_DOMAINS=example.com,test.org