Laravel Active Email Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require veeqtoh/laravel-active-email
   

   Run migrations (if applicable) and publish the config:

   php artisan vendor:publish --provider="Veeqtoh\ActiveEmail\ActiveEmailServiceProvider"
   

2. First Use Case: Add the validation rule to a form request or controller:

   use Veeqtoh\ActiveEmail\Rules\ActiveEmail;
   
   $request->validate([
       'email' => ['required', new ActiveEmail],
   ]);
   

3. Where to Look First:

   • Check config/active-email.php for default settings.
   • Review app/Rules/ActiveEmail.php (if extended) or the package’s Rules directory.
   • Test with a disposable email (e.g., test@example.com) to verify behavior.

Implementation Patterns

Usage Patterns

1. Form Requests:

   public function rules()
   {
       return [
           'email' => ['required', 'email', new \Veeqtoh\ActiveEmail\Rules\ActiveEmail],
       ];
   }
   

2. Controller Validation:

   $validator = Validator::make($request->all(), [
       'email' => ['required', new \Veeqtoh\ActiveEmail\Rules\ActiveEmail],
   ]);
   

3. Dynamic Customization: Pass options to the rule:

   new ActiveEmail(['strict' => true, 'blacklist' => ['mailinator.com']])
   

4. API Responses: Return consistent error messages:

   $request->validate([
       'email' => [new ActiveEmail, 'message' => 'Only active emails are allowed.'],
   ]);
   

Workflows

• Registration Forms: Block disposable emails early in the user flow.
• Email Updates: Validate during profile edits to prevent temporary email abuse.
• API Onboarding: Integrate with Laravel Sanctum/Passport for secure email validation.

Integration Tips

• Laravel Fortify: Extend the RegistersUsers trait to include the rule in registration.
• Laravel Nova: Add the rule to custom validation in Nova resources.
• Testing: Use ActiveEmail::fake() in tests to mock validation:

  ActiveEmail::shouldBlock('test@example.com');
  

Gotchas and Tips

Pitfalls

1. Performance:

   • The package checks against a remote API by default (e.g., MailboxValidator).
   • Fix: Cache responses or use the strict mode sparingly in high-traffic apps.
   • Tip: Configure config/active-email.php to set a TTL for cached responses:

     'cache_ttl' => 60, // Cache for 60 minutes
     

2. False Positives:

   • Some legitimate domains (e.g., corporate aliases) may be flagged.
   • Fix: Use the whitelist option to exclude known-safe domains:

     new ActiveEmail(['whitelist' => ['company.com']])
     

3. API Dependencies:

   • The package relies on external APIs. If the service is down, validation fails silently.
   • Fix: Implement a fallback (e.g., local blacklist) or notify admins:

     'fallback' => true, // Use local lists if API fails
     

4. Rate Limits:

   • Free tiers of email validation APIs have request limits.
   • Tip: Monitor usage and upgrade plans if needed.

Debugging

• Log Validation: Enable debug mode in config to log blocked emails:

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

• Check Cache: Clear the cache if validation behaves unexpectedly:

  php artisan cache:clear
  

Config Quirks

• Strict Mode:
  • strict: true enforces real-time API checks (bypasses cache).
  • Use only for critical paths (e.g., payment emails).
• Blacklist/Greylist:
  • Blacklist: Hard-block domains (e.g., mailinator.com).
  • Greylist: Soft-block (warn users but allow submission).
  • Example:

    new ActiveEmail([
        'blacklist' => ['temp-mail.org'],
        'greylist' => ['10minutemail.com'],
    ])
    

Extension Points

1. Custom Providers: Override the default API provider by binding a new implementation:

   $this->app->bind(
       \Veeqtoh\ActiveEmail\Contracts\EmailValidator::class,
       \App\Services\CustomEmailValidator::class
   );
   

2. Local Lists: Extend the Blacklist or Whitelist classes to load from a database:

   class DatabaseBlacklist implements \Veeqtoh\ActiveEmail\Contracts\Blacklist {
       public function isBlacklisted(string $domain): bool {
           return DB::table('blocked_domains')->where('domain', $domain)->exists();
       }
   }
   

3. Event Hooks: Listen for active-email.blocked events to log or notify:

   Event::listen(\Veeqtoh\ActiveEmail\Events\EmailBlocked::class, function ($event) {
       Log::warning("Blocked email: {$event->email}");
   });