Stop copying your email regex: @magikmaker/email-validator
I kept copying the same email validation code between dux and RedirMe, so I extracted it into @magikmaker/email-validator: zero dependencies, provider rules, typo hints, disposable domains, DNS over HTTPS and pluggable mailbox verification.
I just released
@magikmaker/email-validator
,
a new open source npm package. It started the way most of my packages
start: by noticing I was repeating myself.
While I was working on several projects, among them the dux application and the redirme.com service, I found the same email checks turning up again and again. A bit of syntax checking here, a typo hint there, a list of throwaway domains copied from one repository into the next, each copy drifting a little further from the others. When I fixed a bug in one, the other kept it. So I pulled it all out into one maintained library that every project can share.
1yarn add @magikmaker/email-validator
It has zero dependencies and runs unchanged on Cloudflare Workers, Node 20+, Deno, Bun and in the browser.
You do not need Cloudflare to use it. My own projects run on
Cloudflare Workers, so that is where a few of the examples below come
from, but nothing in the library depends on a Cloudflare account. The
optional DNS check calls Cloudflare’s public DNS over HTTPS resolver
by default, the same free service as 1.1.1.1, which answers anyone
without a key. Prefer Google? Pass endpoint: 'https://dns.google/resolve'.
And where I mention KV or D1 for caching, any store works: the cache is
just an object with a get and a set method, so Redis, Postgres or a
plain Map will do.
Here are a few of the things I learned along the way that might be useful even if you never install it.
Validation and verification are different jobs
Most “email validation” mixes two things that are worth keeping apart:
- Validation is everything you can check without contacting the mailbox: syntax, whether the TLD exists, typos, disposable domains and optionally a DNS lookup. It is free, fast and private, because the address never leaves your code.
- Verification asks a third party (Kickbox, ZeroBounce and the like) whether the mailbox actually exists. That costs money per address, takes a second or two and sends the address to someone else.
The library does validation itself and treats verification as a plug-in.
A provider only has to map its API onto eight shared statuses
(valid, invalid, catch_all, unknown, disposable, role,
spamtrap, abuse). Timeouts, abort signals, caching, a daily budget
and failing open are handled once, in the core, for every provider.
[email protected] cannot exist
A regex happily accepts [email protected]. Gmail does not: its addresses
have 6 to 30 letters and digits, and the only symbol allowed is a dot.
Outlook, Proton, Tuta and iCloud publish similar rules, so the library
knows them:
1import { checkProviderRules } from '@magikmaker/email-validator'
2
3checkProviderRules('[email protected]')
4// { provider: 'gmail', verdict: 'reject',
5// message: 'Gmail addresses have 6 to 30 letters and digits, ...' }
This catches a surprising number of fake signups that sail through every syntax check.
One mailbox, many spellings
[email protected] and [email protected] end up in the
same inbox. If you use email addresses to enforce “one trial per
person”, that matters. The rules differ per provider, though:
- Gmail ignores dots, strips the
+tagand treatsgooglemail.comasgmail.com; - Proton ignores dots, hyphens and underscores;
- Tuta has no plus addressing at all, so
+is part of the name; - Outlook and iCloud strip the tag, but dots count.
canonicalEmailKey() reduces every variant to one key. The provider
table lives in a JSON file, so adding a provider needs no code change.
Typo hints without false alarms
gmial.com is one step away from gmail.com, so suggesting a fix is
easy. The hard part is not nagging people with perfectly real domains.
The library uses the optimal string alignment distance (Levenshtein
plus swapping two neighbouring letters, so gmial counts as a single
edit) and only suggests a distance of 2 when both domains are at least
eight characters long. Short real domains like gmx.at or live.de
are left alone. It also knows that names like gmail only exist on
one TLD, so gmail.de becomes a hint for gmail.com.
1import { checkTypedEmail } from '@magikmaker/email-validator'
2
3checkTypedEmail('[email protected]')?.message
4// 'Did you mean [email protected]?'
Fun detail: hotmial.com and gmial.com are both on the disposable
domain list. Typo domains of big providers are popular with throwaway
mail services and typo squatters, so once you plug in the disposable
check, those addresses are not just a hint but a hard reject.
DNS checks on Workers, over HTTPS
Cloudflare Workers cannot send UDP packets, so a classic MX lookup is
out. The dns entry uses DNS over HTTPS instead (Cloudflare’s JSON API
by default, Google’s works too). Two details I like:
- A domain can publish the null MX record
0 .( RFC 7505 ) to say “I never accept mail”. That is treated as undeliverable, just like a domain without MX, A or AAAA records. - Everything unclear (SERVFAIL, a timeout, a network error) fails open and is never cached. A DNS hiccup should never stop a real person from signing up.
Keep the browser bundle small
The disposable domain list has about 10,000 entries and weighs around 63 KB gzipped. You do not want that in a signup form by accident. So the package has separate entry points:
1// Core, about 11 KB gzipped: safe for the browser
2import { createValidator } from '@magikmaker/email-validator'
3// Opt in to the heavier parts where you need them
4import { isDisposableDomain } from '@magikmaker/email-validator/disposable'
5import { createDomainCheck } from '@magikmaker/email-validator/dns'
A size check in the build fails when the core entry picks up anything from the disposable list, the DNS code or a provider, so it cannot creep back in unnoticed.
Two small tricks worth stealing
Punycode without a dependency. To check an internationalised domain
such as пример.рф against the IANA TLD list, you need its ASCII form.
Every modern runtime already has a converter built in:
1new URL('http://пример.рф').hostname // 'xn--e1afmkfd.xn--p1ai'
Cache the hash, not the address. Verification results are worth
caching (you pay per lookup), but a cache full of email addresses is a
privacy liability. The cache key is a SHA-256 hash of the address,
computed with Web Crypto (crypto.subtle), so KV or D1 never holds
the address itself. And because it is Web Crypto, the same code runs on
Workers, Node and in the browser.
Try it
The package is MIT licensed, the code is on GitHub and the README has full examples for a browser form, a Node server and a Cloudflare Worker with Kickbox and a KV cache. Issues and pull requests are very welcome, especially for mail providers with rules I do not know about yet.
