Laravel Zerobounce Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sarfrazrizwan/laravel-zerobounce
   

   Publish the config file:

   php artisan vendor:publish --provider="Sarfrazrizwan\LaravelZeroBounce\ZeroBounceServiceProvider"
   

2. Configure .env: Add your ZeroBounce API key:

   ZEROBOUNCE_API_KEY=your_api_key_here
   

3. First Use Case: Validate a single email in a controller or service:

   use Sarfrazrizwan\LaravelZeroBounce\Facades\ZeroBounce;
   
   $result = ZeroBounce::validate('test@example.com');
   dd($result); // Returns ZeroBounce response (e.g., disposable, role-based, or valid)
   

Where to Look First

• Facade: ZeroBounce facade for quick access.
• Config: config/zerobounce.php for API key and endpoint customization.
• Documentation: ZeroBounce’s PHP SDK docs for advanced use cases.

Implementation Patterns

Core Workflows

1. Single Email Validation:

   $response = ZeroBounce::validate('user@example.com');
   if ($response->isValid()) {
       // Proceed with signup
   }
   

2. Bulk Validation:

   $emails = ['a@example.com', 'b@example.com'];
   $results = ZeroBounce::validateBulk($emails);
   foreach ($results as $result) {
       // Handle each response
   }
   

3. Integration with Laravel Events: Use the package in Creating user events:

   event(new RegisteringUser($user));
   $user->email = ZeroBounce::validate($user->email)->getEmail();
   

4. Middleware for API Requests: Validate emails before processing API payloads:

   public function handle(Request $request, Closure $next) {
       $request->validate(['email' => ZeroBounce::validate($request->email)->getEmail()]);
       return $next($request);
   }
   

Integration Tips

• Queue Delayed Validation: Offload validation to a queue job for async processing:

  ValidateEmailJob::dispatch($email)->delay(now()->addMinutes(5));
  

  // Job class
  public function handle() {
      $result = ZeroBounce::validate($this->email);
      // Store result or notify user
  }
  

• Cache Responses: Cache results for 24 hours to avoid redundant API calls:

  $result = Cache::remember("zerobounce_{$email}", now()->addHours(24), function() use ($email) {
      return ZeroBounce::validate($email);
  });
  

• Custom Response Handling: Extend the response object for domain-specific logic:

  $result = ZeroBounce::validate($email);
  if ($result->isDisposable()) {
      throw new \Exception('Disposable email detected!');
  }
  

Gotchas and Tips

Pitfalls

1. API Rate Limits: ZeroBounce enforces rate limits. Handle 429 Too Many Requests gracefully:

   try {
       $result = ZeroBounce::validate($email);
   } catch (\Sarfrazrizwan\LaravelZeroBounce\Exceptions\RateLimitExceeded $e) {
       // Retry after delay or notify admin
   }
   

2. Invalid API Key: Ensure .env has a valid ZEROBOUNCE_API_KEY. Test with:

   ZeroBounce::getClient(); // Throws exception if key is invalid
   

3. Bulk Validation Quirks:

   • Batch Size: ZeroBounce recommends batches ≤100 emails. Split larger lists:

     $chunkSize = 100;
     foreach (array_chunk($emails, $chunkSize) as $chunk) {
         ZeroBounce::validateBulk($chunk);
     }
     

   • Error Handling: Bulk responses may include mixed valid/invalid emails. Validate each result individually.

4. Deprecated Methods: The underlying SDK may evolve. Check the ZeroBounce PHP SDK for breaking changes.

Debugging

• Enable Debug Mode: Add to config/zerobounce.php:

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

  Logs API requests/responses to storage/logs/zerobounce.log.

• Test with Fake Emails: Use known disposable emails (e.g., test@example.com) to verify responses:

  $result = ZeroBounce::validate('test@mailinator.com');
  assert($result->isDisposable());
  

Extension Points

1. Custom Validation Rules: Create a reusable rule for Laravel validation:

   use Sarfrazrizwan\LaravelZeroBounce\Facades\ZeroBounce;
   
   class ValidEmail extends FormRequest {
       public function rules() {
           return ['email' => ['required', function ($attribute, $value, $fail) {
               $result = ZeroBounce::validate($value);
               if (!$result->isValid()) {
                   $fail('Invalid email address.');
               }
           }]];
       }
   }
   

2. Webhook Integration: Use ZeroBounce’s webhooks to sync validation results in real-time:

   Route::post('/zerobounce-webhook', function (Request $request) {
       // Verify webhook signature
       // Process $request->all() (e.g., update user records)
   });
   

3. Fallback Mechanism: Implement a fallback to another service if ZeroBounce fails:

   try {
       return ZeroBounce::validate($email);
   } catch (\Exception $e) {
       return FallbackValidator::validate($email);
   }
   

Config Quirks

• Endpoint Customization: Override the default API endpoint in config/zerobounce.php:

  'endpoint' => env('ZEROBOUNCE_ENDPOINT', 'https://api.zerobounce.net'),
  

  Useful for testing with a staging environment.

• Timeout Settings: Adjust HTTP client timeout (default: 30s) in config/zerobounce.php:

  'timeout' => env('ZEROBOUNCE_TIMEOUT', 30),