irondome / mail-canon

v0.2.0 2026-10-27 07:40 UTC

Requires

• php: >=8.2
• ext-intl: *

MIT

• email
• idna
• normalization
• Canonicalization

Published on Packagist.org on 2026-10-27 07:42 UTC

README

Generated distribution of IronDome Mail Canon. Submit issues and changes to the development repository.

mail-canon for PHP

A simple package to normalize and canonicalise email addresses across Gmail, Outlook, Yahoo, and more, by the irondome.dev team.

No network access, telemetry, or mailbox lookup.

Requirements

PHP 8.2+ with the intl extension and Composer.

Install and use

Install the published Packagist package:

composer require irondome/mail-canon:^0.1

The PHP distribution repository is generated from this monorepo. Submit issues and changes to the development repository.

<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';

use IronDome\MailCanon\MailCanon;
use IronDome\MailCanon\InvalidEmail;

$result = MailCanon::normalize('[e-mail]');
assert($result->domain === 'googlemail.com');
assert($result->canonical === '[e-mail]');
assert($result->provider === 'gmail');

try {
    MailCanon::canonicalize('not-an-address');
} catch (InvalidEmail $error) {
    // Ask the caller for a supported address.
}

Provider examples: [e-mail] canonicalizes to [e-mail]; [e-mail] has input domain alice.fastmail.com and canonical address [e-mail]. Fastmail matching uses a static first-party domain list and does not infer custom-domain mail routing.

The intl extension is required for the supported package, even though ASCII domains do not invoke it. The parser rejects non-string arguments explicitly, including when the caller uses PHP's coercive mode.

Address fields and display imports

Use normalizeStrict / canonicalizeStrict for untrusted address fields. It rejects whitespace, display wrappers, mailto:, and explicit cleanup characters. Use the existing normalizer only for intentional display imports. Both paths reject controls and ambiguous wrappers; canonical keys still require mailbox verification before account linking.

Validate and measure

Run from the monorepo's php/ directory or the distribution repository root. The distribution includes copies of both shared test corpora.

composer install
composer test
find src tests -name '*.php' -exec php -l {} \;

See API.md for every public function, result field, error, and integration boundary. Keep the original address separately and verify mailbox ownership before linking accounts. Unicode-domain acceptance is not guaranteed to be identical across every runtime.

The Composer package name is irondome/mail-canon. Licensed under MIT.