Download the PHP package willvincent/laravel-email-verifier without Composer

Laravel Email Verifier

A comprehensive email verification package for Laravel 11/12 that validates email addresses through multiple layers of checks including format validation, domain sanity, MX records, disposable domain detection, and optional integration with external email verification providers.

Features

• Multi-layered Validation: Format, domain sanity, MX records, disposable domains, role-based addresses, plus addressing
• Score-based System: Each email receives a quality score (0-100) based on multiple checks
• External Provider Support: Optional integration with 8 major email verification APIs
  • Abstract API
  • Bouncer
  • Emailable
  • Kickbox
  • NeverBounce
  • QuickEmailVerification
  • VerifiedEmail
  • ZeroBounce
• Fail-Open Design: External provider failures don't block email validation
• Configurable Rules: Enable/disable specific validation rules
• Laravel Validation Integration: Use as custom validation rule or extension
• Artisan Command: Fetch and update disposable domain lists
• Fully Typed: 100% type coverage with strict types
• Well Tested: 98.8% test coverage with 125 passing tests

Requirements

• PHP 8.2+
• Laravel 11.x or 12.x

Installation

Publish Configuration

Publish Translations (Optional)

Configuration

The package comes with sensible defaults. Key configuration options in config/email-verifier.php:

Usage

Basic Usage

As Validation Rule (Object Style)

As Validation Rule (String Style)

Understanding Results

Scoring System

• 100: Perfect email (valid format, good domain, MX records exist)
• 95: Plus addressing detected ([email protected])
• 85: Role-based address (info@, admin@, support@)
• 85: Catch-all domain (external provider detected)
• 80: Unknown status from external provider
• 75: Risky (external provider flagged)
• 0: Hard rejection (invalid format, disposable, no MX in strict mode)

External Providers

Setup Example (Kickbox)

1. Sign up at Kickbox

2. Add to .env:

3. The package will automatically use Kickbox for additional verification

Supported Providers

All providers follow the same pattern:

Creating a Custom Provider

You can create your own external verification driver by implementing the ExternalEmailVerifier interface:

Register your custom driver in a service provider:

Configure in config/email-verifier.php:

Then set in .env:

Best Practices for Custom Drivers:

• Fail-Open Design: Always return accepted: true on errors/timeouts with a reduced score (80-90)
• Scoring: Use 100 for valid, 75 for risky, 80 for unknown, 0 for hard rejections
• Meta Data: Include provider name, status, and raw response for debugging
• Timeouts: Respect the email-verifier.external.timeout_seconds config
• Retries: Use retry(1, 250) for transient failures
• Configuration: Check if API key/endpoint are configured before making requests

Provider Behavior

• External providers are optional and only called after local checks pass
• Failures are fail-open (provider unavailable = accept with lower score)
• Results are merged with local validation scores
• Custom endpoints can be configured for all providers

Disposable Domain Detection

Update Disposable Domains List

Options:

Add Custom Disposable Domains

In config/email-verifier.php:

Advanced Usage

Dependency Injection

Custom Validation Messages

In resources/lang/en/validation.php:

Or publish and edit the package translations:

Testing

Architecture

Validation Flow

1. Format Check: RFC 5322 validation
2. Domain Sanity: Check for valid TLD, no leading/trailing dots
3. Normalization: Lowercase domain, optionally lowercase local part
4. MX Records: Verify domain has mail servers
5. Disposable Detection: Check against known disposable domains
6. Role-Based Detection: Flag generic addresses (admin@, info@)
7. Plus Addressing: Detect and flag plus addressing
8. Score Check: Reject if score below threshold
9. External Verification (optional): Verify with third-party API
10. Final Score Check: Apply threshold after external verification

Chain of Responsibility Pattern

Each validation rule is independent and can modify the result:

Rules can:

• Reject the email ($result->accepted = false)
• Reduce the score ($result->score -= 15)
• Add reasons ($result->addReason('...'))
• Add metadata ($result->meta['key'] = 'value')

Performance

Latency Characteristics

• Local checks: < 1ms (format, domain, disposable)
• MX lookup: 10-50ms (DNS query)
• External provider: 100-500ms (HTTP request)
• Total (with external): ~150-600ms per email

Performance Recommendations

1. Use Queue-Based Verification for User Registration

For the best user experience during registration, validate emails asynchronously:

Job implementation:

2. Disable External Verification in Synchronous Validation

For form requests that need immediate responses, disable external verification:

3. Use External Verification Selectively

Only enable external verification when email quality is critical:

4. Cache Verification Results

For repeated verification of the same email:

5. Batch Verification

For bulk operations, process in chunks:

Performance Impact Summary

Recommendation: For user-facing forms, use allowExternal: false during validation and run full verification with external providers in a background queue. This provides instant feedback while still maintaining high email quality standards.

Security

• No Data Leakage: Validation messages are generic by default
• Fail-Open: External provider failures don't block legitimate users
• Rate Limiting: Recommended for public endpoints
• Input Validation: All inputs are validated and sanitized

License

MIT License. See LICENSE.md for details.

Credits

Created by Will Vincent

Support

• Issues: GitHub Issues
• Security: Please report security vulnerabilities privately

Contributing

Contributions are welcome! Please ensure:

• All tests pass (composer test)
• Type coverage remains 100% (composer type-coverage)
• PHPStan level 9 passes (composer phpstan)
• Code style follows Pint (composer pint-test)