Updated: November 17, 2026
6 min read
Bjørn Wikkeling
Share:

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 +tag and treats googlemail.com as gmail.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.