email-address-kit/email-address-kit

Email Address Kit — PHP library for parsing, validating, normalizing, comparing and correcting email addresses

v1.0.1 2026-08-05 10:17 UTC

Requires

• php: ^7.4 || ^8.0

Requires (Dev)

• phpunit/phpunit: ^9.6
• rector/rector: ^1.2
• vimeo/psalm: ^5.26

Suggests

• ext-intl: Required to validate and normalize IDN domains (e.g. почта.рф) via idn_to_ascii()

MIT

• email
• validation
• canonical
• disposable
• mailbox
• normalization
• typo

Published on Packagist.org on 2026-08-05 10:24 UTC

README

Русский · English

PHP library for parsing, validating, normalizing, comparing, and correcting email addresses.

Requirements: PHP 7.4+. Framework-agnostic.

Full documentation: docs/ru · docs/en

Installation

composer require email-address-kit/email-address-kit

Quick start

Parsing an email into local-part and domain

Email::parse() splits the string into parts. Invalid input does not throw — you get an object first, then check with isValid().

use EmailAddressKit\Email;

$email = Email::parse('[e-mail]');

$email->original();              // [e-mail]
$email->address()->value();      // Alex.Petrov+News
$email->domain()->value();       // Ya.RU
(string) $email;                 // [e-mail]

Three ways to get an email string — for different jobs

Method	What it does	When to use
original()	as entered by the user, unchanged	“what came in” logs, debugging
normalized() / (string)	lowercase only, no guessing	display, templates, safe printing
canonical()	mailbox key: same rules as equals()	UNIQUE in DB, dedup, “same mailbox” lookup

$email = Email::parse('[e-mail]');

$email->original();     // [e-mail]
$email->normalized();   // [e-mail]
(string) $email;        // [e-mail]  (= normalized)
$email->canonical();    // [e-mail]

Important:

• normalized() does not collapse equivalents (ya.ru stays ya.ru) and does not strip +tag / dots.
• canonical() collapses equivalents (ya.ru → yandex.ru) and respects comparison flags, like equals():

use EmailAddressKit\Comparison\ComparisonOptions;

Email::parse('[e-mail]')->canonical();
// [e-mail]

Email::parse('[e-mail]')->canonical([
    ComparisonOptions::ignoreGmailDots(),
    ComparisonOptions::ignorePlusTag(),
]);
// [e-mail]

Two addresses are the same mailbox ⟺ their canonical() values match (with the same flags).

Service name from a domain

If the domain is in the provider catalog, you can get the service: a stable id and a human-readable name.

$email = Email::parse('[e-mail]');

$email->domain()->isKnown(); // true

$service = $email->service();
// same as: $email->domain()->service()

$service->id();   // yandex
$service->name(); // Yandex

Examples:

Email::parse('[e-mail]')->service()->name();       // Gmail
Email::parse('[e-mail]')->service()->name();  // Gmail (same service)
Email::parse('[e-mail]')->service()->name();         // Mail.ru
Email::parse('[e-mail]')->service()->name();        // Mail.ru

Unknown domain — no service:

$email = Email::parse('[e-mail]');

$email->domain()->isKnown(); // false
$email->service();           // null

Same-service domains but different mailboxes can be told apart with sameProviderAs (this is not equals):

Email::parse('[e-mail]')->domain()->sameProviderAs('inbox.ru'); // true
Email::parse('[e-mail]')->equals('[e-mail]');                 // false

List of all known services — id => name map:

use EmailAddressKit\EmailFactory;

$services = EmailFactory::default()->registry()->services();
// [
//   'gmail' => 'Gmail',
//   'mailru' => 'Mail.ru',
//   'yandex' => 'Yandex',
//   ...
// ]

$services['gmail']; // Gmail

Domain list is also available: registry()->domains().

Cyrillic support (IDN / EAI)

The library supports unicode in the domain and in the local-part.

Domain (IDN → Punycode)

Requires the PHP intl extension. A unicode domain and its ASCII form are treated as the same mailbox under equals().

$email = Email::parse('info@почта.рф');

$email->isValid();           // true (with intl)
$email->normalized();        // info@почта.рф
$email->domain()->value();   // почта.рф
$email->domain()->ascii();   // xn--80a1acny.xn--p1ai

Email::parse('info@почта.рф')
    ->equals('[e-mail]--p1ai'); // true

Without intl, a non-ASCII domain → isValid() === false, code INVALID_DOMAIN.

php -m | findstr intl
# or: php -m | grep intl

Local-part (EAI)

UTF-8 letters/digits in the mailbox name are allowed and are not converted to Punycode. Works without intl as well.

Email::parse('иван@gmail.com')->isValid();            // true
Email::parse('иван.петров@gmail.com')->isValid();     // true
Email::parse('инфо@компания.онлайн')->isValid();      // true (domain — when intl is available)

Local-part comparison/normalization uses unicode lowercase where possible.

Syntax validation

Checks address format: presence of @, empty parts, illegal characters, length, domain structure.

$email = Email::parse('[e-mail]');
$email->isValid(); // true

$bad = Email::parse('not-an-email');
$bad->isValid(); // false

foreach ($bad->validation()->errors() as $error) {
    $error->code();     // e.g. INVALID_FORMAT
    $error->message();
}

Optional DNS check (MX/A)

DNS is off by default. When needed, you can verify that the domain has an MX or A record.

use EmailAddressKit\Validation\ValidationOptions;

$email = Email::parse('[e-mail]');

$email->isValid(); // true; syntax only

$email->isValid(ValidationOptions::checkDns()); // syntax + MX or A on the domain

$result = $email->validation(ValidationOptions::checkDns()); // no DNS records → DNS_CHECK_FAILED

DNS runs only after successful syntax validation. A transient DNS failure can produce a false negative. This does not check whether the mailbox exists on the server.

Comparing addresses (equals)

Checks whether two strings are the same mailbox: case-insensitive, with equivalent domains (ya.ru ↔ yandex.ru, googlemail.com ↔ gmail.com).

Email::parse('[e-mail]')->equals('[e-mail]');     // true
Email::parse('[e-mail]')->equals('[e-mail]');    // false (same service, different mailboxes)
Email::parse('[e-mail]')->equals('[e-mail]'); // false (+tag is significant)

// Gmail equivalents — same mailbox:
Email::parse('[e-mail]')->equals('[e-mail]'); // true

By default, dots in the local-part are significant even for Gmail. To treat [e-mail] and [e-mail] as the same mailbox:

use EmailAddressKit\Comparison\ComparisonOptions;

Email::parse('[e-mail]')->equals('[e-mail]', ComparisonOptions::ignoreGmailDots()); // true
Email::parse('[e-mail]')->equals('[e-mail]', ComparisonOptions::ignoreGmailDots()); // true
Email::parse('[e-mail]')->equals('[e-mail]', ComparisonOptions::ignoreGmailDots()); // false (not Gmail)

Gmail dots and +tag can be combined as an array of flags:

Email::parse('[e-mail]')->equals('[e-mail]', [
    ComparisonOptions::ignoreGmailDots(),
    ComparisonOptions::ignorePlusTag(),
]); // true

To ignore +tag for all providers:

use EmailAddressKit\Comparison\ComparisonOptions;

Email::parse('[e-mail]')->equals('[e-mail]', ComparisonOptions::ignorePlusTag()); // true

Finding matches in an array (filterEquals)

Finds every address in a list (e.g. from a DB) that is the same mailbox. Keys and original strings are preserved.

$needle = Email::parse('[e-mail]');

$needle->filterEquals([
    '[e-mail]',
    '[e-mail]',
    '[e-mail]',
    '[e-mail]',
]);
// [1 => '[e-mail]', 2 => '[e-mail]']

$needle->filterEquals([
    10 => '[e-mail]',
    11 => '[e-mail]',
    36 => '[e-mail]',
    42 => '[e-mail]',
]);
// [11 => '[e-mail]', 36 => '[e-mail]']

Fine for short in-memory lists. For large datasets, store and look up by canonical().

Domain typo detection

The detector compares the domain against known providers and suggests close matches (e.g. gmial.com → gmail.com).

$email = Email::parse('[e-mail]');

$email->hasSuggestions(); // true

foreach ($email->suggestions() as $suggestion) {
    $suggestion->email()->normalized(); // [e-mail]
    $suggestion->score();               // 0.0 … 1.0
    $suggestion->reason();              // domain_typo | domain_equivalent
}

domain_typo — likely a typo.
domain_equivalent — informational suggestion to collapse to canonical (googlemail.com → gmail.com); not applied as a typo by auto-correct.

Auto-correcting typos at high confidence

correct() applies only domain_typo, and only if the score is at least the threshold (default 0.95). Otherwise the address is left unchanged.

Email::parse('[e-mail]')->correct()->normalized();
// [e-mail]

Email::parse('[e-mail]')->correct(0.99); // custom threshold

Detecting disposable / temporary domains

This check is separate from isValid(): a temporary address is often syntactically valid.

Email::parse('[e-mail]')->isValid();      // true
Email::parse('[e-mail]')->isDisposable(); // true
Email::parse('[e-mail]')->isDisposable();      // false

The domain list is read from a compiled hash map (O(1)). Parent domains are optionally matched too: foo.mailinator.com is also treated as disposable. Update the list with composer update-disposable (or offline --local-only).

Development

composer test               # PHPUnit
composer psalm              # static analysis
composer rector             # refactoring dry-run
composer compile-domains    # known-domain index
composer update-disposable  # disposable-domain index

Configs: phpunit.xml, psalm.xml, rector.php.

License

MIT