node-email-verifier
Advanced tools
Node Email Verifier is an email validation library for Node.js that checks if an email address has a valid format and optionally verifies the domain's MX (Mail Exchange) records to ensure it can receive emails. It also includes disposable email detection and detailed validation results.
Need email verification without managing servers? Check out ValidKit - a hosted API built on this library with:
# Quick test with ValidKit API
curl -X POST https://api.validkit.com/api/v1/verify \
-H "Content-Type: application/json" \
-H "X-API-Key: vk_beta_test_key_123456789" \
-d '{"email": "test@example.com"}'
node-email-verifier serves 50,000+ weekly downloads on npm and is actively maintained.
If you find it helpful or use it in production, consider sponsoring to support continued development, security updates, and new features.
Install the package using npm:
npm install node-email-verifier --save
This package supports both ES modules and CommonJS:
// ES Modules (recommended)
import emailValidator from 'node-email-verifier';
// CommonJS
const emailValidator = require('node-email-verifier');
Note: When using CommonJS require(), the function returns a promise that resolves with the
validation result.
// CommonJS usage example
const emailValidator = require('node-email-verifier');
// Since emailValidator returns a promise, handle it with async/await:
(async () => {
const isValid = await emailValidator('test@example.com');
console.log('Email is valid:', isValid);
})();
// Or with .then():
emailValidator('test@example.com')
.then((isValid) => console.log('Email is valid:', isValid))
.catch((error) => console.error('Validation error:', error));
Here's how to use Node Email Verifier in both JavaScript and TypeScript:
import emailValidator from 'node-email-verifier';
// Basic validation (format + MX checking)
async function validateEmail(email) {
try {
const isValid = await emailValidator(email);
console.log(`Is "${email}" valid?`, isValid);
} catch (error) {
console.error('Validation error:', error);
}
}
const emailValidator = require('node-email-verifier');
// Basic validation (format + MX checking)
async function validateEmail(email) {
try {
const isValid = await emailValidator(email);
console.log(`Is "${email}" valid?`, isValid);
} catch (error) {
console.error('Validation error:', error);
}
}
// Disposable email detection
async function validateWithDisposableCheck(email) {
try {
const isValid = await emailValidator(email, {
checkDisposable: true,
});
console.log(`Is "${email}" valid (blocking disposable)?`, isValid);
} catch (error) {
console.error('Validation error:', error);
}
}
// Detailed validation results
async function getDetailedValidation(email) {
try {
const result = await emailValidator(email, {
detailed: true,
checkDisposable: true,
});
console.log('Detailed validation result:', result);
/*
Example output:
{
valid: false,
email: 'test@10minutemail.com',
format: { valid: true },
mx: { valid: true, records: [...] },
disposable: {
valid: false,
provider: '10minutemail.com',
reason: 'Email from disposable provider'
}
}
*/
} catch (error) {
console.error('Validation error:', error);
}
}
// Custom timeout and advanced options
async function validateWithCustomOptions(email) {
try {
const isValid = await emailValidator(email, {
checkMx: true,
checkDisposable: true,
timeout: '500ms', // or timeout: 500 for milliseconds
});
console.log(`Is "${email}" valid with all checks?`, isValid);
} catch (error) {
if (error.message === 'DNS lookup timed out') {
console.error('Timeout on DNS lookup.');
} else {
console.error('Validation error:', error);
}
}
}
// Format-only validation (fastest)
async function validateFormatOnly(email) {
try {
const isValid = await emailValidator(email, { checkMx: false });
console.log(`Is "${email}" format valid?`, isValid);
} catch (error) {
console.error('Validation error:', error);
}
}
// Usage examples
validateEmail('test@example.com');
validateWithDisposableCheck('test@10minutemail.com'); // → false
getDetailedValidation('invalid-email'); // → detailed error info
validateFormatOnly('test@example.com'); // → true (no MX check)
import emailValidator, {
EmailValidatorOptions,
ValidationResult,
ErrorCode,
} from 'node-email-verifier';
import { isEmailValidationError } from 'node-email-verifier';
// Basic validation with typed options
async function validateEmailTyped(email: string): Promise<boolean> {
const options: EmailValidatorOptions = {
checkMx: true,
checkDisposable: true,
timeout: 5000,
};
try {
const isValid = await emailValidator(email, options);
console.log(`Is "${email}" valid?`, isValid);
return isValid;
} catch (error) {
console.error('Validation error:', error);
return false;
}
}
// Detailed validation with typed results
async function getDetailedValidationTyped(email: string): Promise<ValidationResult> {
const result = await emailValidator(email, {
detailed: true,
checkMx: true,
checkDisposable: true,
});
// TypeScript infers this is ValidationResult when detailed: true
if (!result.valid) {
console.log('Validation failed:');
if (!result.format.valid) {
console.log('- Format issue:', result.format.reason);
}
if (result.disposable && !result.disposable.valid) {
console.log('- Disposable email from:', result.disposable.provider);
}
if (result.mx && !result.mx.valid) {
console.log('- MX issue:', result.mx.reason);
}
}
return result;
}
// Error handling with error codes
async function handleValidationErrors(email: string): Promise<void> {
try {
const result = await emailValidator(email, {
detailed: true,
checkMx: true,
checkDisposable: true,
timeout: 5000,
});
// TypeScript infers this is ValidationResult when detailed: true
if (!result.valid && result.errorCode === ErrorCode.INVALID_EMAIL_FORMAT) {
throw new Error('Please enter a valid email address');
}
if (result.disposable?.errorCode === ErrorCode.DISPOSABLE_EMAIL) {
throw new Error('Disposable email addresses are not allowed');
}
} catch (error) {
if (isEmailValidationError(error) && error.code === ErrorCode.DNS_LOOKUP_TIMEOUT) {
throw new Error('Email verification timed out. Please try again.');
}
throw error;
}
}
// Type-safe inline validation
async function quickValidation(email: string): Promise<boolean> {
const result = await emailValidator(email, {
checkMx: false,
checkDisposable: true, // Block disposable emails
timeout: 2000,
});
// TypeScript infers this is boolean when detailed is false/undefined
return result;
}
// Create specialized validators
function createValidator(options: EmailValidatorOptions) {
return (email: string) => emailValidator(email, options);
}
const fastValidator = createValidator({
checkMx: false,
checkDisposable: false,
});
const businessValidator = createValidator({
checkMx: true,
checkDisposable: true,
timeout: 10000,
});
const detailedValidator = createValidator({
detailed: true,
checkMx: true,
checkDisposable: true,
});
When using CommonJS with TypeScript, you can still get full type support:
// For CommonJS projects, use require with type imports
import type { EmailValidatorOptions, ValidationResult } from 'node-email-verifier';
const emailValidator = require('node-email-verifier');
// Basic validation with typed options
async function validateEmailCJS(email: string): Promise<boolean> {
const options: EmailValidatorOptions = {
checkMx: true,
checkDisposable: true,
timeout: 5000,
};
try {
const isValid = await emailValidator(email, options);
console.log(`Is "${email}" valid?`, isValid);
return isValid;
} catch (error) {
console.error('Validation error:', error);
return false;
}
}
// Detailed validation with typed results
async function getDetailedValidationCJS(email: string): Promise<ValidationResult> {
const result = await emailValidator(email, {
detailed: true,
checkMx: true,
checkDisposable: true,
});
// TypeScript infers this is ValidationResult when detailed: true
if (!result.valid) {
console.log('Validation failed:');
if (!result.format.valid) {
console.log('- Format issue:', result.format.reason);
}
if (result.disposable && !result.disposable.valid) {
console.log('- Disposable email from:', result.disposable.provider);
}
if (result.mx && !result.mx.valid) {
console.log('- MX issue:', result.mx.reason);
}
}
return result;
}
// Alternative: Use dynamic import in CommonJS for full type inference
async function validateWithDynamicImport(email: string): Promise<boolean> {
const { default: emailValidator } = await import('node-email-verifier');
return emailValidator(email, {
checkMx: true,
checkDisposable: true,
});
}
For more comprehensive examples, check out the examples directory:
Run any example:
node examples/basic-validation.js
Block temporary and throwaway email services to improve data quality:
// Block disposable emails
const isValid = await emailValidator('test@10minutemail.com', {
checkDisposable: true,
}); // → false
// Allow disposable emails (default behavior)
const isValid = await emailValidator('test@10minutemail.com', {
checkDisposable: false,
}); // → true (if format and MX are valid)
Supported disposable providers: 600+ domains including 10minutemail, guerrillamail, yopmail, tempmail, mailinator, and many more.
Get comprehensive validation information with specific failure reasons:
// Get detailed validation results
const result = await emailValidator('test@10minutemail.com', {
detailed: true,
checkMx: true,
checkDisposable: true,
});
console.log(result);
/*
Output:
{
"valid": false,
"email": "test@10minutemail.com",
"format": { "valid": true },
"mx": {
"valid": true,
"records": [{"exchange": "mx.10minutemail.com", "priority": 10}]
},
"disposable": {
"valid": false,
"provider": "10minutemail.com",
"reason": "Email from disposable provider",
"errorCode": "DISPOSABLE_EMAIL"
}
}
*/
// Handle validation results
if (!result.valid) {
if (!result.format.valid) {
console.log('Invalid email format:', result.format.reason);
}
if (result.disposable && !result.disposable.valid) {
console.log('Disposable email detected:', result.disposable.provider);
}
if (result.mx && !result.mx.valid) {
console.log('MX validation failed:', result.mx.reason);
}
}
Detailed validation results now include error codes for programmatic error handling:
const result = await emailValidator('invalid-email', {
detailed: true,
checkMx: true,
checkDisposable: true,
});
// Check specific error codes
if (!result.valid) {
if (result.errorCode) {
console.log('Top-level error:', result.errorCode);
}
switch (result.format.errorCode) {
case ErrorCode.EMAIL_MUST_BE_STRING:
console.log('Email must be a string');
break;
case ErrorCode.EMAIL_CANNOT_BE_EMPTY:
console.log('Email cannot be empty');
break;
case ErrorCode.INVALID_EMAIL_FORMAT:
console.log('Invalid email format');
break;
}
if (result.mx?.errorCode) {
switch (result.mx.errorCode) {
case ErrorCode.NO_MX_RECORDS:
console.log('No mail server found');
break;
case ErrorCode.DNS_LOOKUP_FAILED:
console.log('DNS lookup error');
break;
case ErrorCode.DNS_LOOKUP_TIMEOUT:
console.log('DNS lookup timed out');
break;
case ErrorCode.MX_SKIPPED_DISPOSABLE:
console.log('MX check skipped due to disposable email');
break;
}
}
if (result.disposable?.errorCode === ErrorCode.DISPOSABLE_EMAIL) {
console.log('Disposable email detected');
}
}
// Handle thrown errors
import emailValidator, { ErrorCode } from 'node-email-verifier';
try {
await emailValidator('test@example.com', { timeout: -1 });
} catch (error) {
if (error.code === ErrorCode.INVALID_TIMEOUT_VALUE) {
console.log('Invalid timeout configuration');
}
}
Available Error Codes:
EMAIL_MUST_BE_STRING - Email is not a stringEMAIL_CANNOT_BE_EMPTY - Email string is emptyINVALID_EMAIL_FORMAT - Email format is invalidNO_MX_RECORDS - No MX records found for domainDNS_LOOKUP_FAILED - DNS lookup encountered an errorDNS_LOOKUP_TIMEOUT - DNS lookup timed outMX_SKIPPED_DISPOSABLE - MX check was skipped because email is disposableMX_LOOKUP_FAILED - MX record lookup failed for unknown reasonDISPOSABLE_EMAIL - Email is from a disposable providerINVALID_TIMEOUT_VALUE - Invalid timeout parameterUNKNOWN_ERROR - An unknown error occurredEnable structured logging for debugging and observability:
const result = await emailValidator('test@example.com', {
debug: true, // Enable debug mode
checkMx: true,
checkDisposable: true,
detailed: true,
});
// Debug logs are written to console.log as JSON:
// {
// "type": "email-validator-debug",
// "timestamp": "2025-06-22T10:30:45.123Z",
// "phase": "mx_record_check",
// "email": "test@example.com",
// "data": { "domain": "example.com", "timeoutMs": 10000 },
// "timing": { "start": 123.45 },
// "memory": { "heapUsed": 12345678, "heapTotal": 23456789, "rss": 34567890 }
// }
Debug Mode Features:
// Intercept debug logs for analysis
const debugLogs = [];
const originalLog = console.log;
console.log = (message) => {
try {
const parsed = JSON.parse(message);
if (parsed.type === 'email-validator-debug') {
debugLogs.push(parsed);
}
} catch (e) {
originalLog(message);
}
};
// Run validation
const result = await emailValidator(email, { debug: true });
// Restore console.log and analyze
console.log = originalLog;
console.log(`Validation took ${debugLogs.length} steps`);
See the debug mode example for more advanced usage patterns.
Improve performance for high-volume email validation with built-in MX record caching:
// Basic usage - caching is enabled by default
const isValid = await emailValidator('test@example.com', {
checkMx: true,
});
// Configure cache settings
const result = await emailValidator('test@example.com', {
checkMx: true,
detailed: true,
cache: {
enabled: true, // Enable caching (default: true)
defaultTtl: 600000, // 10 minutes TTL (default: 5 minutes)
maxSize: 5000, // Store up to 5000 domains (default: 1000)
},
});
// Cache statistics in detailed results
console.log(result.cacheStats);
// {
// hits: 42, // Number of cache hits
// misses: 8, // Number of cache misses
// size: 50, // Current cache size
// evictions: 0, // Number of evicted entries
// hitRate: 84.00 // Cache hit rate percentage
// }
// Check if result was served from cache
if (result.mx?.cached) {
console.log('MX records were served from cache');
}
Cache Management:
import { globalMxCache } from 'node-email-verifier';
// Clear entire cache
globalMxCache.flush();
// Clear specific domain
globalMxCache.delete('example.com');
// Get cache statistics
const stats = globalMxCache.getStatistics();
console.log(`Cache hit rate: ${stats.hitRate}%`);
// Reset statistics (keeps cached data)
globalMxCache.resetStatistics();
Performance Benefits:
// Use all features together
const result = await emailValidator(email, {
checkMx: true, // Verify MX records
checkDisposable: true, // Block disposable emails
detailed: true, // Get detailed results
timeout: '5s', // Custom timeout
debug: true, // Enable debug logging
});
// Business-friendly validation
const isBusinessEmail = await emailValidator(email, {
checkMx: true,
checkDisposable: true, // Block temporary emails
timeout: '10s',
}); // Returns boolean for simple usage
This package supports both ES modules and CommonJS through the exports field in package.json.
Key configuration details:
"type": "module": Designates this as an ES module package"main": Points to ./dist/index.js for legacy compatibility"types": TypeScript definitions at ./dist/index.d.ts for both module systems"exports": Modern Node.js module resolution with conditional exports:
"import": ES module entry point (./dist/index.js)"require": CommonJS entry point (./dist/index.cjs)"types": Shared TypeScript definitions (./dist/index.d.ts)For the complete configuration, see the package.json file.
This configuration ensures the package works correctly with:
import emailValidator from 'node-email-verifier' (ES modules)const emailValidator = require('node-email-verifier') (CommonJS)emailValidator(email, [opts]): Promise<boolean | ValidationResult>Validates the given email address with comprehensive validation options including format checking, MX record verification, disposable email detection, and detailed results.
// Type-safe handling of both return types
async function handleValidation(email) {
const result = await emailValidator(email, {
checkDisposable: true,
detailed: true, // This determines the return type
});
// When detailed: true, result is ValidationResult
if (typeof result === 'object') {
console.log('Detailed validation:');
console.log('Valid:', result.valid);
if (!result.valid) {
if (!result.format.valid) {
console.log('Format error:', result.format.reason);
}
if (result.disposable && !result.disposable.valid) {
console.log('Disposable provider:', result.disposable.provider);
}
}
return result.valid;
}
// When detailed: false (default), result is boolean
console.log('Simple validation:', result);
return result;
}
// TypeScript automatically infers the correct type based on options
const detailedResult = await emailValidator(email, { detailed: true }); // ValidationResult
const booleanResult = await emailValidator(email, { detailed: false }); // boolean
email (unknown): The email address to validate. Can be any type, but only strings will be
considered valid.opts (EmailValidatorOptions | boolean, optional): Configuration options or a boolean for
backward compatibility.EmailValidatorOptions)interface EmailValidatorOptions {
checkMx?: boolean; // Whether to check for MX records (default: true)
checkDisposable?: boolean; // Whether to check for disposable emails (default: false)
detailed?: boolean; // Return detailed validation results (default: false)
timeout?: string | number; // Timeout for DNS lookup (default: '10s')
debug?: boolean; // Enable debug mode with structured logging (default: false)
cache?: MxCacheOptions; // MX record caching configuration (default: enabled)
}
// See "Type Definitions" section below for ValidationResult interface
checkMx (boolean, optional): Whether to check for MX records. Defaults to true.checkDisposable (boolean, optional): Whether to check for disposable email providers.
Defaults to false.detailed (boolean, optional): Return detailed validation results instead of boolean.
Defaults to false.timeout (string | number, optional): The timeout for the DNS MX lookup. Can be:
5000)'5s', '2000ms', '1m')'10s' (10 seconds)debug (boolean, optional): Enable debug mode for structured logging. When true, logs
detailed timing and memory usage information to console.log as JSON. Defaults to false.cache (MxCacheOptions, optional): Configure MX record caching behavior. Caching is enabled
by default with a 5-minute TTL. Options:
enabled (boolean): Enable/disable caching. Default: truedefaultTtl (number): TTL in milliseconds. Default: 300000 (5 minutes)maxSize (number): Maximum cache entries. Default: 1000For backward compatibility, you can also pass a boolean as the second parameter:
true: Enable MX checking (equivalent to { checkMx: true })false: Disable MX checking (equivalent to { checkMx: false })Promise<boolean | ValidationResult>: A promise that resolves to:
boolean (when detailed: false or not specified):
true if the email address passes all enabled validationsfalse if the email address fails any enabled validationValidationResult (when detailed: true):
format validation resultsmx results only when checkMx: truedisposable results only when checkDisposable: trueError: When DNS lookup times out, the error message will be "DNS lookup timed out"This library is written in TypeScript and provides several benefits for TypeScript users:
EmailValidatorOptions interface in your own codeThe library exports the following types:
// Import the types and utilities from the library
// Types are imported separately from runtime values for clarity
import type {
ErrorCode,
MxRecord,
ValidationResult,
EmailValidatorOptions,
CacheStatistics,
MxCacheOptions,
} from 'node-email-verifier';
import { EmailValidationError, isEmailValidationError } from 'node-email-verifier';
// Main function type
declare function emailValidator(
email: unknown,
opts?: EmailValidatorOptions | boolean
): Promise<boolean | ValidationResult>;
// Options interface
export interface EmailValidatorOptions {
checkMx?: boolean;
checkDisposable?: boolean;
detailed?: boolean;
timeout?: string | number;
debug?: boolean;
cache?: MxCacheOptions;
}
// MX cache configuration
export interface MxCacheOptions {
enabled?: boolean;
defaultTtl?: number;
maxSize?: number;
}
// Cache statistics
export interface CacheStatistics {
hits: number;
misses: number;
size: number;
evictions: number;
hitRate: number;
}
// MX record type
export interface MxRecord {
exchange: string;
priority: number;
}
// Validation result interface
export interface ValidationResult {
valid: boolean;
email: string;
errorCode?: ErrorCode; // Top-level error code for quick access
format: {
valid: boolean;
reason?: string;
errorCode?: ErrorCode;
};
mx?: {
valid: boolean;
records?: MxRecord[];
reason?: string;
errorCode?: ErrorCode;
cached?: boolean; // Whether result was from cache
};
disposable?: {
valid: boolean;
provider?: string | null;
reason?: string;
errorCode?: ErrorCode;
};
cacheStats?: CacheStatistics; // Cache statistics when cache is enabled
}
// Error handling types
export class EmailValidationError extends Error {
code: ErrorCode;
constructor(code: ErrorCode, message?: string);
}
// Type guard for error handling
export function isEmailValidationError(error: unknown): error is EmailValidationError;
When using this library in production environments, especially with MX record checking enabled, it's important to consider DNS rate limiting. For detailed guidance on:
See our API Best Practices Guide.
npm run build - Compile TypeScript to JavaScriptnpm run test - Run the test suitenpm run lint - Check JavaScript/TypeScript code for linting issuesnpm run lint:fix - Automatically fix JavaScript/TypeScript linting issuesnpm run lint:md - Check Markdown files for linting issuesnpm run lint:md:fix - Automatically fix Markdown linting issuesnpm run lint:yaml - Check YAML files for validitynpm run lint:all - Run all linters (JS/TS, Markdown, YAML)npm run format - Format code with Prettiernpm run format:check - Check if code is properly formattednpm run check - Run all linting, formatting, and testsnpm run precommit - Fix linting, format code, and run testsnpm run benchmark - Run performance benchmarks for disposable domain lookupsnpm run benchmark:init - Run initialization and memory usage benchmarksnpm run benchmark:all - Run all benchmarksThis project uses:
Before committing, run npm run precommit to ensure code quality.
This project uses husky and lint-staged to maintain code quality:
These hooks are installed automatically when you run npm install.
node-email-verifier/
├── src/ # Source TypeScript files
├── dist/ # Built JavaScript files and CommonJS wrapper
├── test/ # Test files (unit and integration tests)
├── scripts/ # Build scripts and performance benchmarks
├── docs/ # Additional documentation
│ ├── AI_WORKFLOW.md # AI-assisted PR workflow guide
│ ├── API_BEST_PRACTICES.md # Rate limiting and production usage
│ ├── ESM_COMMONJS_COMPATIBILITY.md # Module compatibility guide
│ ├── INTEGRATION_TESTING.md # Integration testing guide
│ └── PERFORMANCE.md # Performance benchmarks and analysis
└── examples/ # (Coming soon) Example usage scripts
Check out our Feature Enhancement Roadmap to see what's coming next and what we're working on. We welcome feedback and contributions on these planned features!
Contributions are always welcome! Please see our Contributing Guide for detailed information about:
Quick start:
npm install
npm run check # Run all quality checks
Feel free to submit a PR!
If you find Node Email Verifier useful, please consider supporting its development:
Your support helps maintain this project and fund new features. Thank you! 💖
This project is licensed under the MIT License.
FAQs
A Node.js module for verifying email addresses
The npm package node-email-verifier receives a total of 43,982 weekly downloads. As such, node-email-verifier popularity was classified as popular.
We found that node-email-verifier demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Application Security
/Security News
Socket CEO Feross Aboukhadijeh and a16z partner Joel de la Garza discuss vibe coding, AI-driven software development, and how the rise of LLMs, despite their risks, still points toward a more secure and innovative future.
Research
/Security News
Threat actors hijacked Toptal’s GitHub org, publishing npm packages with malicious payloads that steal tokens and attempt to wipe victim systems.
Research
/Security News
Socket researchers investigate 4 malicious npm and PyPI packages with 56,000+ downloads that install surveillance malware.