README

Comprehensive PHP email validation library with syntax checking, disposable domain detection, DNS verification, SMTP mailbox validation, and a scoring system.

Requires: PHP 8.0+ with fsockopen, getmxrr, dns_get_record and ability to connect to remote port 25.

Installation

composer require webo3/smtp-email-validation

Usage

Full Validation with Scoring (Recommended)

use webO3\SmtpEmailValidation\EmailValidator;

$validator = new EmailValidator(
    fromEmail: 'noreply@yourdomain.com',
    validThreshold: 60,  // Score >= 60 considered valid
    timeout: 30,
);

$result = $validator->validate('user@example.com');

echo $result->score;    // 0-100
echo $result->isValid;  // true/false
echo $result->email;    // 'user@example.com'

// Per-check breakdown
foreach ($result->checks as $check) {
    echo "{$check->name}: {$check->status->value} (score: {$check->score})\n";
}

// Get a specific check
$smtpCheck = $result->getCheck('smtp');

// Convert to array (useful for JSON APIs)
$array = $result->toArray();

Quick Static Method

use webO3\SmtpEmailValidation\Validator;

// Full validation with scoring
$result = Validator::validate('user@example.com', from: 'noreply@yourdomain.com');
echo $result->score; // 0-100

Custom Check Configuration

Run only specific checks or adjust settings:

use webO3\SmtpEmailValidation\EmailValidator;
use webO3\SmtpEmailValidation\Check\SyntaxCheck;
use webO3\SmtpEmailValidation\Check\DisposableDomainCheck;
use webO3\SmtpEmailValidation\Check\DnsCheck;

// Lightweight validation without SMTP (no port 25 needed)
$validator = new EmailValidator(
    validThreshold: 50,
    checks: [
        new SyntaxCheck(),
        new DisposableDomainCheck(cacheTtl: 3600), // refresh list every hour
        new DnsCheck(),
    ],
);

$result = $validator->validate('user@example.com');

Legacy SMTP-Only Check (Backward Compatible)

use webO3\SmtpEmailValidation\Validator;

$response = Validator::test('noreply@yourdomain.com', 'user@example.com');
// Returns: ['code' => 250, 'success' => true, 'msg' => 'Email is valid', 'debug' => [...]]

Examples

Runnable example scripts are provided in the examples/ directory:

# Full validation with score breakdown
php examples/basic-validation.php user@example.com

# Syntax-only check (no network calls)
php examples/syntax-only.php user@example.com

# Batch validation from arguments or file
php examples/batch-validation.php user1@gmail.com user2@mailinator.com
php examples/batch-validation.php --file emails.txt

# Custom checks (skip SMTP, JSON output)
php examples/custom-checks.php user@example.com

Validation Checks

The library runs four checks in sequence:

If syntax validation fails, all subsequent checks are skipped and the score is 0.

Disposable Domain List

The disposable domain check automatically fetches the latest list from the disposable-email-domains community project and caches it locally (default: 24 hours). If the fetch fails, a bundled fallback list is used.

You can configure the cache TTL and location:

new DisposableDomainCheck(
    cachePath: '/path/to/cache.json',  // default: sys_get_temp_dir()
    cacheTtl: 3600,                    // refresh every hour (default: 86400)
);

Scoring System

Each check produces a score from 0-100, weighted by importance:

• Overall score = weighted average of non-skipped checks (0-100)
• isValid = score >= threshold (default: 60)

Example Scores

DNS Sub-Scoring

SMTP Sub-Scoring

Legacy Response Codes

When using Validator::test():

Testing

composer install
vendor/bin/phpunit

Warning

• Many hosting providers and ISPs block direct connections to remote port 25.
• Use a valid FROM address — some blacklists may block specific sender addresses.