@kennethwkz/disposable-email-domains

v1.3.6

Published

2 months ago

Comprehensive TypeScript SDK for detecting disposable email addresses with real-time synchronization, advanced DNS validation (MX, SPF, DMARC), intelligent caching, and high-performance email validation. Features 119K+ domains from 15+ sources with automa

Disposable Email Domains - TypeScript SDK

✨ Features

🎯 119K+ Disposable Domains - Real-time updates from 15+ sources
⚡ High Performance - Advanced caching, Trie indexing, Bloom filters
🔧 TypeScript-First - Fully typed with strict type definitions
🛡️ Advanced Validation - Format, MX records, SPF, DMARC, SMTP deliverability
📊 Analytics & Insights - Built-in metrics and performance monitoring
💾 Flexible Caching - Memory, Redis, Database, or custom adapters
🎨 Extensible - Plugin system for custom validation rules

📊 Current Statistics

Last Updated: July 11, 2026 at 08:08 AM UTC | Next Sync: Automated twice daily (6 AM & 6 PM UTC) 📋 View Detailed Report | Last sync analysis and insights

🎯 Domain Coverage

| 📧 Total Domains | 🆕 Recent Additions | 🗑️ Recent Removals | 📈 Growth Rate | |:---:|:---:|:---:|:---:| | 133,109 | 29 | 2 | +0.02% |

⚡ Performance Metrics

| 🚀 Sync Time | ✅ Success Rate | 📦 File Size | 🔄 Deduplication | |:---:|:---:|:---:|:---:| | 0.92s | 100.0% | 2.0 MB | 203,914 removed |

🏆 Top Contributing Sources

| Repository | Domains | Success | Performance | |------------|---------|---------|-------------| | kslr/disposable-email-domains | 123,652 | ✅ | 0.44s (1.8 MB) | | disposable/disposable-email-domains | 74,522 | ✅ | 0.31s (1.1 MB) | | FGRibreau/mailchecker | 56,360 | ✅ | 0.39s (846.7 KB) | | wesbos/burner-email-providers | 27,279 | ✅ | 0.23s (388.1 KB) | | groundcat/disposable-email-domain-list | 15,411 | ✅ | 0.18s (219.5 KB) | | sublime-security/static-files | 10,522 | ✅ | 0.26s (144.0 KB) | | 7c/fakefilter | 10,197 | ✅ | 0.20s (141.3 KB) | | disposable-email-domains/disposable-email-domains | 7,973 | ✅ | 0.17s (110.6 KB) | | willwhite/freemail | 4,462 | ✅ | 0.17s (61.8 KB) | | eser/sanitizer-svc | 3,855 | ✅ | 0.26s (48.9 KB) |

🔍 Sync Analysis

Total Sources: 15 repositories monitored
Active Sources: 15 successfully synchronized
Failed Sources: 0 temporary failures
Processing Efficiency: 145157 domains/second
Average Download Time: 0.25s per repository
Total Data Processed: 4.9 MB

🎯 Quality Metrics

Duplicate Detection: 203,914 duplicates identified and removed
Data Integrity: 100.0% repository success rate
Coverage Efficiency: 39.5% unique domains retained

📦 Installation

# Using bun (recommended)
bun add @kennethwkz/disposable-email-domains

# Using npm
npm install @kennethwkz/disposable-email-domains

# Using yarn
yarn add @kennethwkz/disposable-email-domains

🚀 Quick Start

Basic Usage

import { DisposableEmailChecker } from "@kennethwkz/disposable-email-domains";

const checker = new DisposableEmailChecker();

// Single email check
const result = await checker.checkEmail("[email protected]");
console.log(result.isDisposable); // true
console.log(result.confidence); // 95

// Batch validation
const emails = ["[email protected]", "[email protected]"];
const results = await checker.checkEmailsBatch(emails);

DNS Validation

const checker = new DisposableEmailChecker({
  checkMxRecord: true,
  dnsValidation: {
    validateMxConnectivity: true,
    checkSpfRecord: true,
    checkDmarcRecord: true,
    timeout: 5000,
    retries: 3,
  },
});

const result = await checker.checkEmail("[email protected]");

// Access DNS validation results
console.log(result.dnsValidation?.hasMx); // true
console.log(result.dnsValidation?.mxRecords); // [{ exchange: 'mail.example.com', priority: 10 }]
console.log(result.dnsValidation?.hasSpf); // true
console.log(result.dnsValidation?.hasDmarc); // true
console.log(result.dnsValidation?.isConnectable); // true

SMTP Validation

const checker = new DisposableEmailChecker({
  checkMxRecord: true,
  checkSmtpDeliverability: true,
  smtpValidation: {
    timeout: 10000,
    port: 25,
    fromEmail: "[email protected]",
    helo: "mail.yourdomain.com",
  },
});

const result = await checker.checkEmail("[email protected]");

// Access SMTP validation results
console.log(result.smtpValidation?.isDeliverable); // true
console.log(result.smtpValidation?.responseCode); // 250
console.log(result.smtpValidation?.responseMessage); // '2.1.5 Recipient OK'
console.log(result.smtpValidation?.serverTested); // 'mail.example.com'

Combined DNS + SMTP Validation

// When both are enabled, MX records from DNS are passed to SMTP (no duplicate lookups)
const checker = new DisposableEmailChecker({
  checkMxRecord: true,
  checkSmtpDeliverability: true,
  dnsValidation: {
    validateMxConnectivity: true,
    checkSpfRecord: true,
    checkDmarcRecord: true,
  },
  smtpValidation: {
    timeout: 8000,
    fromEmail: "[email protected]",
  },
});

const result = await checker.checkEmail("[email protected]");

// Get complete validation picture
console.log({
  isValid: result.isValid,
  isDisposable: result.isDisposable,
  hasMx: result.dnsValidation?.hasMx,
  isDeliverable: result.smtpValidation?.isDeliverable,
  confidence: result.confidence,
});

📋 Configuration

DisposableEmailChecker Options

interface EmailCheckerConfig {
  // Validation Options
  strictValidation?: boolean; // Strict RFC validation (default: false)
  checkMxRecord?: boolean; // Enable MX checking (default: false)
  checkSmtpDeliverability?: boolean; // Enable SMTP testing (default: false)
  enableSubdomainChecking?: boolean; // Check subdomains (default: true)
  enablePatternMatching?: boolean; // Use regex patterns (default: true)

  // Performance Options
  enableCaching?: boolean; // Enable caching (default: true)
  cacheSize?: number; // Cache size (default: 10000)
  enableIndexing?: boolean; // Use Trie/Bloom filters (default: true)
  indexingStrategy?: "trie" | "bloom" | "hybrid"; // Indexing strategy (default: 'hybrid')

  // DNS Validation
  dnsValidation?: {
    timeout?: number; // DNS timeout in ms (default: 5000)
    retries?: number; // Retry attempts (default: 3)
    enableCaching?: boolean; // Cache DNS results (default: true)
    cacheSize?: number; // DNS cache size (default: 5000)
    cacheTtl?: number; // DNS cache TTL in ms (default: 300000)
    concurrency?: number; // Max concurrent queries (default: 10)
    validateMxConnectivity?: boolean; // Test SMTP connectivity (default: false)
    checkSpfRecord?: boolean; // Check SPF records (default: false)
    checkDmarcRecord?: boolean; // Check DMARC records (default: false)
    customDnsServers?: string[]; // Custom DNS servers
    fallbackDnsServers?: string[]; // Fallback DNS servers
  };

  // SMTP Validation
  smtpValidation?: {
    timeout?: number; // SMTP timeout in ms (default: 10000)
    port?: number; // SMTP port (default: 25)
    fromEmail?: string; // FROM address (default: '[email protected]')
    helo?: string; // HELO hostname (default: 'mail.example.com')
    retries?: number; // Retry attempts (default: 2)
    enableCaching?: boolean; // Cache SMTP results (default: true)
    cacheSize?: number; // SMTP cache size (default: 1000)
    cacheTtl?: number; // SMTP cache TTL in ms (default: 600000)
  };

  // Data Sources
  disposableDomainsUrl?: string; // Remote domain list URL
  localDataPath?: string; // Local domain list path
  allowlistPath?: string; // Allowlist file path
  blacklistPath?: string; // Blacklist file path

  // Custom Configuration
  customPatterns?: RegExp[]; // Custom regex patterns
  trustedDomains?: string[]; // Trusted domains (always valid)
  suspiciousPatterns?: RegExp[]; // Suspicious patterns
  customCache?: any; // Custom cache implementation
}

🎯 API Reference

Core Methods

`checkEmail(email: string): Promise<EmailValidationResult>`

Validates a single email address with all enabled checks.

`checkEmailsBatch(emails: string[]): Promise<EmailValidationResult[]>`

Validates multiple emails efficiently with batch processing.

`validateDomain(domain: string): Promise<DnsValidationResult>`

Performs DNS validation for a domain (requires checkMxRecord: true).

`addToAllowlist(domain: string): void`

Adds a domain to the allowlist (always considered valid).

`addToBlacklist(domain: string): void`

Adds a domain to the blacklist (always considered invalid).

`getStats(): object`

Retrieves comprehensive statistics including DNS and SMTP metrics.

`getMetrics(): PerformanceMetrics`

Retrieves detailed performance metrics for all validation operations.

`clearAllCaches(): Promise<void>`

Clears all caches (email validation, DNS, and SMTP).

Result Interfaces

interface EmailValidationResult {
  email: string;
  isValid: boolean;
  isDisposable: boolean;
  isAllowed: boolean;
  isBlacklisted: boolean;
  domain: string;
  localPart: string;
  matchType: "exact" | "subdomain" | "pattern" | "none";
  confidence: number; // 0-100
  validationTime: number; // milliseconds
  errors: string[];
  warnings: string[];

  // DNS validation results (when enabled)
  dnsValidation?: {
    hasMx: boolean;
    mxRecords: Array<{ exchange: string; priority: number }>;
    hasSpf: boolean;
    hasDmarc: boolean;
    isConnectable: boolean;
    dnsValidationTime: number;
  };

  // SMTP validation results (when enabled)
  smtpValidation?: {
    isValid: boolean;
    isDeliverable: boolean;
    responseCode: number | null;
    responseMessage: string | null;
    smtpValidationTime: number;
    serverTested: string | null;
  };
}

🔧 Advanced Usage

Standalone Components

import { EmailValidator, DnsResolver, SmtpValidator } from "@kennethwkz/disposable-email-domains";

// Standalone DNS resolver
const dnsResolver = new DnsResolver({
  timeout: 5000,
  retries: 3,
  validateMxConnectivity: true,
});
const dnsResult = await dnsResolver.validateMxRecord("gmail.com");

// Standalone SMTP validator
const smtpValidator = new SmtpValidator({
  timeout: 10000,
  fromEmail: "[email protected]",
});
const smtpResult = await smtpValidator.validateEmail("[email protected]");

// Email validator with DNS and SMTP
const emailValidator = new EmailValidator(
  false, // strict mode
  { timeout: 5000, validateMxConnectivity: true }, // DNS config
  { timeout: 10000, fromEmail: "[email protected]" }, // SMTP config
);
const validation = await emailValidator.validateEmailDeliverability("[email protected]");

Custom Cache Implementation

import { DisposableEmailChecker, type ICache } from "@kennethwkz/disposable-email-domains";

class RedisCache implements ICache {
  async get(key: string): Promise<any> {
    /* ... */
  }
  async set(key: string, value: any, ttl?: number): Promise<void> {
    /* ... */
  }
  async has(key: string): Promise<boolean> {
    /* ... */
  }
  async delete(key: string): Promise<boolean> {
    /* ... */
  }
  async clear(): Promise<void> {
    /* ... */
  }
  async size(): Promise<number> {
    /* ... */
  }
}

const checker = new DisposableEmailChecker({
  customCache: new RedisCache(),
});

Performance Monitoring

const checker = new DisposableEmailChecker({
  checkMxRecord: true,
  checkSmtpDeliverability: true,
  enableCaching: true,
});

// Process some emails
await checker.checkEmail("[email protected]");
await checker.checkEmail("[email protected]");

// Get comprehensive statistics
const stats = checker.getStats();
console.log("Performance:", {
  totalValidations: stats.performance.totalValidations,
  avgTime: stats.performance.averageValidationTime,
  cacheHitRate: stats.performance.cacheHitRate,
  dnsStats: stats.dns,
  smtpStats: stats.smtp,
});

High-Volume Batch Processing

async function validateLargeList(emails: string[]) {
  const checker = new DisposableEmailChecker({
    enableCaching: true,
    cacheSize: 50000,
    checkMxRecord: true,
    checkSmtpDeliverability: true,
    dnsValidation: {
      enableCaching: true,
      cacheSize: 20000,
      concurrency: 25,
    },
    smtpValidation: {
      enableCaching: true,
      cacheSize: 10000,
    },
  });

  const batchSize = 50;
  const results = [];

  for (let i = 0; i < emails.length; i += batchSize) {
    const batch = emails.slice(i, i + batchSize);
    const batchResults = await checker.checkEmailsBatch(batch);
    results.push(...batchResults);

    // Add delay for SMTP validation to respect mail servers
    if (i + batchSize < emails.length) {
      await new Promise((resolve) => setTimeout(resolve, 2000));
    }
  }

  return results;
}

⚡ Performance

Benchmarks

| Operation | Time | Cache Hit Rate | Memory | | ----------------------------- | ----------- | -------------- | ------ | | Single email validation | ~1-5ms | 90%+ | <5MB | | Batch validation (100 emails) | ~50-200ms | 90%+ | <10MB | | DNS validation | ~50-200ms | 90%+ | <10MB | | SMTP validation | ~500-2000ms | 75%+ | <5MB | | Combined DNS+SMTP | ~600-2200ms | 85%+ | <15MB |

Optimization Tips

Enable caching for all validation types (DNS, SMTP, email)
Use appropriate batch sizes: 100-200 for DNS, 25-50 for SMTP
Set reasonable timeouts: 5s for DNS, 10s for SMTP
Add delays between SMTP batches (1-2s) to respect mail servers
Use hybrid indexing for optimal performance with large domain lists

Run benchmarks locally:

bun run test:bench

🧪 Testing

# Run all tests
bun run test

# Type checking
bun run test:types

# Coverage report
bun run test:coverage

# Benchmarks
bun run test:bench

🔄 Domain Synchronization

The domain database is automatically synchronized from 15+ trusted sources twice daily (6 AM & 6 PM UTC). See Syncer Documentation for advanced synchronization features.

📚 Documentation

API Reference - Complete API documentation
Configuration Guide - Detailed configuration options
Performance Guide - Optimization techniques
Examples - More usage examples
Syncer Documentation - Domain synchronization details