@maverick/email-validator

A lightweight email validation library that checks:

• Email syntax (regex)
• Blocked domains (built-in list)
• Test/disposable domains (built-in list, optional via allowTestEmail)
• Optional DNS MX lookup for deliverability (checkDns)

Author: Manish Jyala
License: ISC

Install

npm i @maverick/email-validator

Import / Require (ESM + CJS)

ESM

import { validateEmail, EmailValidator } from "@maverick/email-validator";

CommonJS (CJS)

const { validateEmail, EmailValidator } = require("@maverick/email-validator");

Quick usage

import { validateEmail } from "@maverick/email-validator";

const result = await validateEmail("[email protected]", {
  checkDns: false,
  allowTestEmail: false,
});

console.log(result);
// {
//   isValid: true|false,
//   message: "...",
//   reason: "...",
//   input: "[email protected]",
//   checks: { ... }
// }

API

validateEmail(email, options?) (async)

Runs:

1. syntax validation
2. domain block/test validation
3. optional DNS MX validation (depends on mode)

Returns an object like:

• isValid: boolean
• message: string
• reason: string
• input: original input
• checks: object with extra details (like syntax, domainBlocked, testDomain, dns, etc.)

Options

• regex (RegExp): custom syntax regex (default: patterns.DEFAULT_EMAIL_REGEX)
• mode ("basic" | "strict" | "deliverable"): validation mode (default: "deliverable")
  • "basic": syntax + block/test only (DNS skipped)
  • "strict": stricter syntax rules + block/test (DNS depends on checkDns)
  • "deliverable": syntax + block/test + DNS MX (DNS always on)
• checkDns (boolean): used only when mode: "strict" (default: true)
• dnsTimeoutMs (number): DNS timeout in ms (default: 4000)
• dnsCacheTtlMs (number): cache DNS MX results for faster repeated checks (default: 10 minutes)
• allowTestEmail (boolean): if false, test/disposable email services are rejected (default: false)

Common reasons

• OK
• INVALID_TYPE
• EMPTY
• INVALID_SYNTAX
• PLUS_ADDRESSING_NOT_ALLOWED (rejects numeric plus tags like [email protected])
• DOMAIN_BLOCKED
• TEST_EMAIL_NOT_ALLOWED (test/disposable email domain and allowTestEmail: false)
• DNS_NO_MX
• DNS_TIMEOUT
• DNS_ERROR

validateEmailSyntax(email, options?) (sync)

Validates only the email format.

Options:

• regex (RegExp): custom regex

validateEmailDomainDns(emailOrDomain, options?) (async)

Checks whether a domain has MX records.

Options:

• timeoutMs (number): DNS timeout in ms (default: 4000)

lookupMxRecords(domain, options?) (async)

Returns MX records (sorted by priority). If lookup fails, returns [].

Options:

• timeoutMs (number): DNS timeout in ms (default: 4000)
• cacheTtlMs (number): cache MX results for faster repeated calls (default: 10 minutes)

Parsing helpers

getEmailDomain(email) (sync)

Extracts the lowercased domain from the email string.

Class-based usage

If you prefer OOP style:

import { EmailValidator } from "@maverick/email-validator";

const v = new EmailValidator({
  allowTestEmail: false,
  dnsTimeoutMs: 4000,
});

const res = await v.validate("[email protected]", { checkDns: false });

Batch validation

Validate multiple emails efficiently (with optional concurrency control):

import { validateEmails } from "@maverick/email-validator";

const results = await validateEmails(
  ["[email protected]", "[email protected]"],
  { mode: "basic", concurrency: 10 }
);

Notes

• This library does not attempt SMTP mailbox verification.
• DNS checks can fail due to network/DNS resolver issues; use checkDns: false if you only want syntax + block/test checks.