mail-validatr

mail-validatr is a lightweight Node.js library and CLI tool for validating email addresses.
It checks syntax, domain validity, and MX records to ensure an email address is not just well-formed, but also likely to exist.

Features

• 📬 Syntax Validation — Checks if an email matches standard formats.
• 🌐 Domain Verification — Verifies if the domain is real and reachable.
• 📨 MX Record Lookup — Confirms that the domain accepts emails (via MX records).
• ⚡ Fast and Lightweight — Minimal dependencies, fast execution.
• 🛠️ CLI and Programmatic API — Use in scripts or integrate into your Node.js apps.
• 🛡️ Custom Rules — Add custom validation rules or disposable email lists.
• ✅ Recommended Check — Indicates if the email is valid and free of warnings.

Installation

Install the library via npm:

npm install mail-validatr

For global CLI usage:

npm install -g mail-validatr

Usage

Programmatic (Node.js)

Import and use the validateEmail function:

import { validateEmail } from "mail-validatr";

async function checkEmail() {
  const result = await validateEmail("[email protected]");
  console.log(result);
}

checkEmail();

Example output:

{
  "isValidSyntax": true,
  "hasValidDomain": true,
  "hasMxRecords": true,
  "warnings": [],
  "recommended": true
}

Skipping DNS Checks

For environments without network access, you can skip DNS and MX record validation:

await validateEmail("[email protected]", { skipDnsCheck: true });

Adding Custom Warning Rules

You can define custom rules for additional validation:

const customRules = [
  (email: string) =>
    email.endsWith("@example.com")
      ? { code: "example_com_not_allowed", message: "Emails from example.com are not allowed." }
      : null,
];

await validateEmail("[email protected]", { customWarningRules: customRules });

Example output with warnings:

{
  "isValidSyntax": true,
  "hasValidDomain": true,
  "hasMxRecords": true,
  "warnings": [
    {
      "code": "example_com_not_allowed",
      "message": "Emails from example.com are not allowed."
    }
  ],
  "recommended": false
}

CLI

Validate email addresses directly from the command line:

mail-validatr [email protected]

Output:

[RESULT] Validation result for [email protected]:
- Syntax valid: true
- Domain valid: true
- MX records found: true
- Warnings: None
- Recommended: Yes

Skipping DNS Checks

Use the --skip-dns flag to skip DNS and MX record validation:

mail-validatr [email protected] --skip-dns

Verbose Output

Enable verbose output with the --verbose flag:

mail-validatr [email protected] --verbose

API

validateEmail(email: string, options?: ValidationOptions): Promise<EmailValidationResult>

Parameters:

• email (string): The email address to validate.
• options (object, optional):
  • skipDnsCheck (boolean): If true, skips DNS and MX record validation.
  • customDisposableList (string[]): Add custom disposable email domains.
  • customWarningRules (Array<(email: string) => { code: string; message: string } | null>): Add custom warning rules.

Returns:

An EmailValidationResult object:

interface EmailValidationResult {
  isValidSyntax: boolean;
  hasValidDomain?: boolean;
  hasMxRecords?: boolean;
  warnings: Array<{ code: string; message: string }>;
  recommended: boolean;
}

🧪 Example Projects

You can see real-world usage of mail-validatr in action:

• mail-validatr-example

This repository contains:

• Client Demo — Frontend-only validation with syntax + warning checks (Next.js + React + Tailwind).
• Server Demo — Full email validation with DNS & MX lookup using server routes.

Useful Scripts

• Build: npm run build
• Dev Mode (watch + test): npm run dev:test
• Run Tests: npx vitest

License

MIT © 2025
Made with ❤️ by Jindrich Bobek