Laravel Mailgun Email Validation Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require kouz/laravel-mailgun-email-validation
   

   For Laravel ≤5.4, manually add Kouz\LaravelMailgunValidation\ServiceProvider::class to config/app.php.

2. Publish Config:

   php artisan vendor:publish --provider="Kouz\LaravelMailgunValidation\ServiceProvider"
   

   Update config/mailgun-email-validation.php with your Mailgun API key and optional settings (e.g., timeout, api_url).

3. First Use Case: Validate an email in a form request:

   use Illuminate\Http\Request;
   
   public function store(Request $request) {
       $request->validate([
           'email' => ['required', 'mailgun_email'],
       ]);
       // Proceed with logic...
   }
   

Where to Look First

• Config File: config/mailgun-email-validation.php (API key, timeouts, and flags).
• Validation Rules: Laravel’s validation docs for rule syntax.
• Mailgun API Docs: Email Validation API for flag details.

Implementation Patterns

Core Workflow

1. Basic Validation:

   $request->validate([
       'email' => 'required|mailgun_email',
   ]);
   

   • Uses FILTER_VALIDATE_EMAIL + Mailgun API check.

2. Strict Validation with Flags:

   $request->validate([
       'email' => 'required|mailgun_email:role,disposable,mailbox,strict',
   ]);
   

   • Flags (additive):
     • role: Reject role-based emails (e.g., admin@domain.com).
     • disposable: Block disposable/temporary emails (e.g., tempmail.com).
     • mailbox: Verify mailbox existence (requires Mailgun’s mailbox check).
     • strict: Enforce all checks (equivalent to role,disposable,mailbox).

3. Custom Validation Logic:

   $validator = Validator::make($data, [
       'email' => ['required', 'mailgun_email:disposable'],
   ]);
   if ($validator->fails()) {
       // Handle errors...
   }
   

Integration Tips

• Form Requests:

  use Kouz\LaravelMailgunValidation\Rules\MailgunEmail;
  
  public function rules() {
      return [
          'email' => ['required', new MailgunEmail(['disposable'])]
      ];
  }
  

• API Responses: Return Mailgun-specific errors:

  $errors = $validator->errors();
  return response()->json(['error' => $errors->first('email')], 422);
  

• Rate Limiting: Cache Mailgun API responses (e.g., Cache::remember()) to avoid hitting API limits during bulk validation.

• Fallback for Offline: Use Laravel’s sometimes rule to skip Mailgun checks in testing:

  'email' => ['required', 'mailgun_email:sometimes'],
  

Gotchas and Tips

Pitfalls

1. API Key Exposure:

   • Never commit config/mailgun-email-validation.php to version control.
   • Use environment variables (e.g., .env) for the API key:

     MAILGUN_API_KEY=your_key_here
     

2. Rate Limits:

   • Mailgun’s free tier has strict rate limits. Cache responses aggressively:

     Cache::remember("mailgun_validate_{$email}", now()->addMinutes(5), function() use ($email) {
         return MailgunValidator::validate($email);
     });
     

3. Flag Conflicts:

   • strict overrides other flags. Use sparingly in production.
   • mailbox flag requires Mailgun’s paid plan (throws Mailgun\Exception\MailgunException otherwise).

4. False Positives:

   • Some legitimate emails (e.g., user+tag@domain.com) may fail role checks. Test thoroughly.

5. Network Issues:

   • Mailgun API timeouts (default: 5s) can cause silent failures. Extend timeout in config:

     'timeout' => 10, // seconds
     

Debugging

• Enable Logging: Add to config/mailgun-email-validation.php:

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

  Logs API responses to storage/logs/laravel.log.

• Mock API Calls: Use Laravel’s Mockery to simulate Mailgun responses in tests:

  $mock = Mockery::mock('overload:Kouz\LaravelMailgunValidation\MailgunValidator');
  $mock->shouldReceive('validate')->andReturn(true);
  

Extension Points

1. Custom Flags: Extend the validator by subclassing MailgunValidator:

   namespace App\Rules;
   
   use Kouz\LaravelMailgunValidation\MailgunValidator;
   
   class CustomMailgunValidator extends MailgunValidator {
       protected function customCheck($email) {
           // Add logic (e.g., check against a blacklist).
           return true;
       }
   }
   

2. Event Listeners: Listen for validation failures:

   use Kouz\LaravelMailgunValidation\Events\MailgunValidationFailed;
   
   MailgunValidationFailed::listen(function ($event) {
       // Log or notify admins.
   });
   

3. Queue Validation: Offload Mailgun checks to a queue (e.g., mailgun-validate-job) for async processing:

   dispatch(new ValidateEmailWithMailgun($email));
   

Performance

• Batch Validation: For bulk emails (e.g., user imports), validate in chunks:

  $emails = collect($request->emails)->chunk(10);
  foreach ($emails as $chunk) {
      $chunk->each(function ($email) {
          $this->validateEmail($email);
      });
  }
  

• Pre-Validation: Use PHP’s filter_var() for a quick local check before hitting Mailgun:

  if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
      return false;
  }