@gmana/email-checker

A powerful and lightweight TypeScript library to detect disposable email addresses with advanced validation features and comprehensive domain coverage.

✨ Features

• 🚀 Comprehensive Detection: 286+ disposable email domains (constantly updated)
• 🔧 Highly Configurable: Custom whitelists, validation modes, and extensible options
• 📊 Detailed Validation: Rich validation results with metadata and error reporting
• ⚡ Performance Optimized: O(1) lookups with intelligent caching system
• 🌍 International Support: Handles international domains and subdomains
• 💪 TypeScript First: Full type safety with comprehensive type definitions
• 🪶 Zero Dependencies: Lightweight with no external runtime dependencies
• 📦 Universal: Works in Node.js, browsers, and supports both ESM & CJS

📦 Installation

npm install @gmana/email-checker

yarn add @gmana/email-checker

pnpm add @gmana/email-checker

bun add @gmana/email-checker

🚀 Quick Start

Basic Usage

import { isDisposableEmail } from "@gmana/email-checker"

// Simple boolean check
console.log(isDisposableEmail("[email protected]")) // true
console.log(isDisposableEmail("[email protected]")) // false
console.log(isDisposableEmail("[email protected]")) // true

Advanced Validation with Details

import { validateEmail } from "@gmana/email-checker"

const result = validateEmail("[email protected]")
console.log(result)
// {
//   isValid: true,
//   isDisposable: true,
//   domain: "tempmail.net",
//   errors: [],
//   metadata: {
//     isInternational: false,
//     hasSubdomains: false,
//     isWhitelisted: false
//   }
// }

🔧 Configuration

Global Configuration

import { configureEmailChecker, isDisposableEmail } from "@gmana/email-checker"

// Configure global settings
configureEmailChecker({
  strictMode: true, // Enable strict email validation
  whitelistedDomains: ["company.com"], // Always allow these domains
  customDisposableDomains: [
    // Add custom disposable domains
    "suspicious-temp.com",
    "fake-emails.net",
  ],
  allowInternational: true, // Allow international domains
  allowSubdomains: false, // Disallow subdomains
  enableCaching: true, // Enable performance caching
  maxCacheSize: 1000, // Cache size limit
})

// Now all validation uses these settings
console.log(isDisposableEmail("[email protected]")) // false (whitelisted)

Per-Validation Options

import { isDisposableEmail, validateEmail } from "@gmana/email-checker"

// Override global config for specific validations
const isDisposable = isDisposableEmail("[email protected]", {
  allowSubdomains: true,
  whitelistedDomains: ["tempmail.com"],
})

const result = validateEmail("user@münchen-temp.de", {
  allowInternational: true,
  strictMode: false,
})

📚 Complete API Reference

Core Functions

isDisposableEmail(email: string, options?: EmailValidationOptions): boolean

Simple boolean check for disposable emails.

isDisposableEmail("[email protected]") // true
isDisposableEmail("[email protected]") // false
isDisposableEmail("invalid-email") // false

validateEmail(email: string, options?: EmailValidationOptions): EmailValidationResult

Comprehensive validation with detailed results.

const result = validateEmail("[email protected]")
// Returns detailed validation information

Configuration Functions

configureEmailChecker(config: Partial<EmailCheckerConfig>): void

Set global configuration options.

resetEmailCheckerConfig(): void

Reset configuration to defaults.

getEmailCheckerConfig(): EmailCheckerConfig

Get current configuration settings.

Domain Analysis Functions

isDomainDisposable(domain: string): boolean

Check if a specific domain is disposable.

isDomainDisposable("tempmail.net") // true
isDomainDisposable("gmail.com") // false

getDomainInfo(domain: string, options?: EmailValidationOptions): DomainInfo

Get detailed information about a domain.

const info = getDomainInfo("tempmail.net")
// { domain: "tempmail.net", isDisposable: true, isWhitelisted: false, isInternational: false }

getDisposableDomains(): string[]

Get the complete list of known disposable domains.

const domains = getDisposableDomains()
console.log(`Total domains: ${domains.length}`) // Total domains: 286+

Utility Functions

extractDomain(email: string): string | null

Extract domain from email address.

extractDomain("[email protected]") // "example.com"
extractDomain("invalid-email") // null

isValidEmailFormat(email: string, strictMode?: boolean): boolean

Validate email format.

isValidEmailFormat("[email protected]") // true
isValidEmailFormat("invalid-email") // false

Cache Management

clearCache(): void

Clear the domain validation cache.

getCacheStats(): { size: number; maxSize: number }

Get cache statistics.

const stats = getCacheStats()
console.log(`Cache: ${stats.size}/${stats.maxSize}`)

🎯 Advanced Usage Examples

Form Validation with Zod

import { z } from "zod"
import { isDisposableEmail } from "@gmana/email-checker"

const signUpSchema = z.object({
  email: z
    .string()
    .min(1, "Email is required")
    .email("Invalid email format")
    .refine((email) => !isDisposableEmail(email), {
      message: "Disposable emails are not allowed",
    }),
})

type SignUpData = z.infer<typeof signUpSchema>

Express.js Middleware

import express from "express"
import { validateEmail } from "@gmana/email-checker"

const app = express()

// Advanced email validation middleware
app.post("/signup", (req, res) => {
  const { email } = req.body
  const validation = validateEmail(email)

  if (!validation.isValid) {
    return res.status(400).json({
      error: "Invalid email",
      details: validation.errors,
    })
  }

  if (validation.isDisposable) {
    return res.status(400).json({
      error: "Disposable emails are not allowed",
      domain: validation.domain,
    })
  }

  // Continue with signup process
})

React Hook Integration

import { useState, useEffect } from "react"
import { validateEmail } from "@gmana/email-checker"

function useEmailValidation(email: string) {
  const [validation, setValidation] = useState(null)

  useEffect(() => {
    if (email) {
      const result = validateEmail(email)
      setValidation(result)
    }
  }, [email])

  return validation
}

// Usage in component
function SignUpForm() {
  const [email, setEmail] = useState("")
  const validation = useEmailValidation(email)

  return (
    <div>
      <input
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Enter email"
      />
      {validation?.isDisposable && (
        <p className="error">Disposable emails are not allowed</p>
      )}
    </div>
  )
}

Bulk Email Processing

import { isDisposableEmail, configureEmailChecker } from "@gmana/email-checker"

// Configure once for optimal performance
configureEmailChecker({
  enableCaching: true,
  maxCacheSize: 5000,
})

async function processBulkEmails(emails: string[]) {
  const results = emails.map((email) => ({
    email,
    isDisposable: isDisposableEmail(email),
    isValid: email.includes("@"),
  }))

  const stats = {
    total: emails.length,
    disposable: results.filter((r) => r.isDisposable).length,
    valid: results.filter((r) => r.isValid).length,
  }

  return { results, stats }
}

🎛️ TypeScript Types

interface EmailValidationOptions {
  allowInternational?: boolean
  allowSubdomains?: boolean
  customDisposableDomains?: string[]
  whitelistedDomains?: string[]
  strictMode?: boolean
}

interface EmailValidationResult {
  isValid: boolean
  isDisposable: boolean
  domain: string | null
  errors: string[]
  metadata: {
    isInternational: boolean
    hasSubdomains: boolean
    isWhitelisted: boolean
  }
}

interface EmailCheckerConfig extends EmailValidationOptions {
  enableCaching?: boolean
  maxCacheSize?: number
}

interface DomainInfo {
  domain: string
  isDisposable: boolean
  isWhitelisted: boolean
  isInternational: boolean
}

🌍 International Domain Support

The library fully supports international domains and provides proper handling for:

// International domains
validateEmail("user@münchen-mail.de") // Properly handled
validateEmail("test@временная-почта.рф") // International disposable domains

// Subdomain analysis
validateEmail("[email protected]") // Detects parent domain
validateEmail("[email protected]") // Flexible subdomain handling

🏎️ Performance Characteristics

• O(1) Domain Lookups: Using Set-based storage for instant domain checking
• Intelligent Caching: LRU cache with configurable size limits
• Memory Efficient: Minimal memory footprint with smart data structures
• Bundle Size: < 10KB minified, < 3KB gzipped

🔄 Migration Guide

From v0.x to v1.x

The basic API remains unchanged, but new features are available:

// v0.x - Still works
import { isDisposableEmail } from "@gmana/email-checker"
const isDisposable = isDisposableEmail("[email protected]")

// v1.x - Enhanced with new features
import { validateEmail, configureEmailChecker } from "@gmana/email-checker"

// Configure once
configureEmailChecker({
  whitelistedDomains: ["yourcompany.com"],
  strictMode: true,
})

// Get detailed results
const result = validateEmail("[email protected]")

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Add New Disposable Domains: Submit PRs with new disposable email providers
2. Report Issues: Found a legitimate domain being flagged? Let us know!
3. Feature Requests: Suggest new features or improvements
4. Bug Fixes: Help us squash bugs and improve reliability

📄 License

MIT © Sun Sreng

🔗 Links

• Homepage: https://github.com/sun-sreng/npm-gmana-email-checker
• Issues: https://github.com/sun-sreng/npm-gmana-email-checker/issues
• Sponsor: https://github.com/sponsors/sun-sreng