How to validate email addresses in Node.js

npm install disposable-email-domains

import { domainToASCII } from "node:url";

// RFC 5322 "atext": the characters allowed in each dot-separated part of the local part.
const ATOM = /^[a-z0-9!#$%&'*+/=?^_`{|}~-]+$/i;
// A DNS label: letters, digits and hyphens, not starting or ending with a hyphen.
const LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;

export function checkSyntax(input) {
  const email = String(input).trim();
  if (email.length > 254) return { ok: false, reason: "too_long" };

  const at = email.lastIndexOf("@");
  if (at < 1 || at === email.length - 1) return { ok: false, reason: "missing_at_or_part" };

  const local = email.slice(0, at);
  // Lower-cases and converts internationalised domains to punycode ("" if invalid).
  const domain = domainToASCII(email.slice(at + 1));

  if (Buffer.byteLength(local) > 64) return { ok: false, reason: "local_part_too_long" };
  // Splitting on "." also rejects leading, trailing and doubled dots (they create empty atoms).
  if (!local.split(".").every((atom) => ATOM.test(atom))) {
    return { ok: false, reason: "invalid_local_part" };
  }

  const labels = domain.split(".");
  if (!domain || labels.length < 2 || !labels.every((l) => LABEL.test(l)) || /^\d+$/.test(labels.at(-1))) {
    return { ok: false, reason: "invalid_domain" };
  }

  return { ok: true, local, domain, normalized: `${local.toLowerCase()}@${domain}` };
}

import { Resolver } from "node:dns/promises";

// A dedicated resolver with a short timeout, so a slow DNS server can't stall a sign-up.
export const resolver = new Resolver({ timeout: 3000, tries: 2 });

export async function checkDomain(domain) {
  try {
    const mx = await resolver.resolveMx(domain);
    // RFC 7505 "null MX": a single record pointing at "." means "this domain accepts no mail".
    if (mx.length === 1 && mx[0].exchange === "") {
      return { status: "invalid", reason: "domain_rejects_mail" };
    }
    if (mx.length > 0) {
      return { status: "ok", mx: mx.sort((a, b) => a.priority - b.priority) };
    }
  } catch (err) {
    if (err.code === "ENOTFOUND") return { status: "invalid", reason: "domain_not_found" };
    // ENODATA = the domain exists but has no MX records; handled below.
    // Anything else (ESERVFAIL, ETIMEOUT, ECONNREFUSED…) is temporary – don't blame the user.
    if (err.code !== "ENODATA") return { status: "unknown", reason: "dns_error" };
  }

  // No MX records: SMTP falls back to the domain's own A/AAAA record ("implicit MX").
  const hasAddress = await Promise.any([resolver.resolve4(domain), resolver.resolve6(domain)]).then(
    () => true,
    () => false,
  );
  return hasAddress
    ? { status: "risky", reason: "no_mx_records" }
    : { status: "invalid", reason: "no_mail_server" };
}

import { checkDomain } from "./dns-check.js";

const cache = new Map();
const TTL_MS = 60 * 60 * 1000; // 1 hour

// Caches the promise, not the result, so concurrent sign-ups on the same domain share one lookup.
export function checkDomainCached(domain) {
  const hit = cache.get(domain);
  if (hit && hit.expires > Date.now()) return hit.promise;

  const promise = checkDomain(domain);
  cache.set(domain, { promise, expires: Date.now() + TTL_MS });
  // Don't remember temporary failures.
  promise.then((result) => {
    if (result.status === "unknown") cache.delete(domain);
  });
  return promise;
}

import domains from "disposable-email-domains" with { type: "json" };

const disposable = new Set(domains);

// Checks the domain and each parent, so "x.mailinator.com" matches "mailinator.com".
export function isDisposable(domain) {
  const labels = domain.split(".");
  for (let i = 0; i < labels.length - 1; i++) {
    if (disposable.has(labels.slice(i).join("."))) return true;
  }
  return false;
}

const ROLE_ACCOUNTS = new Set([
  "admin", "billing", "contact", "help", "hello", "info", "marketing", "no-reply",
  "noreply", "office", "postmaster", "sales", "support", "team", "webmaster",
]);

export function isRoleAccount(local) {
  // Ignore "+tag" sub-addressing: "support+billing" is still "support".
  return ROLE_ACCOUNTS.has(local.toLowerCase().split("+")[0]);
}

// Real providers people mistype. Include close neighbours (mail.com, ymail.com, gmx.com…)
// too, or they'd be "corrected" to the provider one letter away.
const POPULAR_DOMAINS = [
  "gmail.com", "googlemail.com", "yahoo.com", "ymail.com", "yahoo.co.uk", "hotmail.com",
  "hotmail.co.uk", "outlook.com", "live.com", "msn.com", "icloud.com", "me.com", "mac.com",
  "aol.com", "mail.com", "gmx.com", "gmx.de", "proton.me", "protonmail.com",
];

// Levenshtein distance where swapping two adjacent letters counts as one edit.
function distance(a, b) {
  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
  for (let j = 1; j <= b.length; j++) d[0][j] = j;
  for (let i = 1; i <= a.length; i++) {
    for (let j = 1; j <= b.length; j++) {
      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
        d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
      }
    }
  }
  return d[a.length][b.length];
}

// "gmial.com" → "gmail.com"; null when the domain is fine or nothing is close.
export function suggestDomain(domain) {
  if (POPULAR_DOMAINS.includes(domain)) return null;
  let best = null;
  let bestDistance = 3;
  for (const candidate of POPULAR_DOMAINS) {
    const dist = distance(domain, candidate);
    if (dist < bestDistance) [best, bestDistance] = [candidate, dist];
  }
  return bestDistance <= (domain.length <= 6 ? 1 : 2) ? best : null;
}

import { checkSyntax } from "./syntax.js";
import { checkDomainCached } from "./dns-cache.js";
import { isDisposable } from "./disposable.js";
import { isRoleAccount, suggestDomain } from "./extras.js";

/**
 * Returns { status, reason, email, didYouMean } where status is
 * "valid" | "invalid" | "risky" | "unknown".
 */
export async function validateEmail(input) {
  const syntax = checkSyntax(input);
  if (!syntax.ok) return { status: "invalid", reason: syntax.reason, email: null, didYouMean: null };

  const { local, domain, normalized } = syntax;
  const suggestion = suggestDomain(domain);
  const base = { email: normalized, didYouMean: suggestion ? `${local}@${suggestion}` : null };

  const dns = await checkDomainCached(domain);
  if (dns.status === "invalid" || dns.status === "unknown") return { ...base, status: dns.status, reason: dns.reason };

  // The domain can receive mail. Now look for risk signals, most serious first.
  if (isDisposable(domain)) return { ...base, status: "risky", reason: "disposable" };
  if (suggestion) return { ...base, status: "risky", reason: "possible_typo" };
  if (dns.status === "risky") return { ...base, status: "risky", reason: dns.reason };
  if (isRoleAccount(local)) return { ...base, status: "risky", reason: "role_based" };
  return { ...base, status: "valid", reason: "mail_server_found" };
}

import express from "express";
import { validateEmail } from "./validate-email.js";

const app = express();
app.use(express.json());

app.post("/signup", async (req, res) => {
  const result = await validateEmail(req.body?.email ?? "");

  if (result.status === "invalid" || result.reason === "disposable") {
    return res.status(422).json({
      error: result.reason === "disposable"
        ? "Please use a permanent email address."
        : "That email address can't receive mail.",
      didYouMean: result.didYouMean,
    });
  }

  // "unknown" means DNS had a hiccup – accept the address and re-check it later.
  // await createUser(result.email);
  res.status(201).json({ ok: true, email: result.email, didYouMean: result.didYouMean });
});

app.listen(3000);

import { test } from "node:test";
import assert from "node:assert/strict";
import { checkSyntax } from "./syntax.js";

test("accepts normal addresses", () => {
  for (const email of ["jane@example.com", "jane.doe+news@example.co.uk", "user@münchen.de"]) {
    assert.equal(checkSyntax(email).ok, true, email);
  }
});

test("rejects malformed addresses", () => {
  for (const email of ["", "jane", "@example.com", "jane@", "a..b@example.com", "jane@example", "jane@-example.com"]) {
    assert.equal(checkSyntax(email).ok, false, email);
  }
});

const API = "https://validateemail.io/v1";
const headers = {
  Authorization: `Bearer ${process.env.VALIDATEEMAIL_KEY}`,
  "Content-Type": "application/json",
};

export async function validateWithApi(email) {
  try {
    const res = await fetch(`${API}/validate?email=${encodeURIComponent(email)}`, {
      headers,
      signal: AbortSignal.timeout(5000),
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json();
  } catch (err) {
    // Never block a sign-up because the validator is slow or unreachable.
    console.warn("Email validation unavailable:", err.message);
    return { status: "unknown", reason: "validator_unavailable" };
  }
}

// Validates any number of addresses, 100 per request.
export async function validateList(emails) {
  const results = [];
  for (let i = 0; i < emails.length; i += 100) {
    const res = await fetch(`${API}/validate/batch`, {
      method: "POST",
      headers,
      body: JSON.stringify({ emails: emails.slice(i, i + 100) }),
      signal: AbortSignal.timeout(30000),
    });
    if (!res.ok) throw new Error(`Batch failed: HTTP ${res.status}`);
    results.push(...(await res.json()).results);
  }
  return results;
}