@mikkelscheike/email-provider-links

v5.2.2

Published

a month ago

TypeScript library for email provider detection with 140 providers (259 domains), concurrent DNS resolution, alias normalization, and HTTPS login URL validation for login and password reset flows

Downloads

57,765

Email Provider Links

Generate direct login links for any email address across 140+ providers (Gmail, Outlook, Yahoo, etc.) to streamline user authentication flows.

A TypeScript library providing login URLs for 140 email providers (259 domains) with concurrent DNS detection for business domains, email alias normalization, and HTTPS login-URL validation.

🚀 Try it out

Live Demo - Test the library with any email address and see it in action!

✨ Core Features

🚀 Fast & Lightweight: Zero dependencies, small footprint (~42KB packed)
📧 140 Email Providers: Gmail, Outlook, Yahoo, ProtonMail, iCloud, and many more
🌐 259 Domains Supported: Broad international coverage
🌍 Full IDN Support: International domain names with Punycode
✅ Email Validation: International email validation with detailed error reporting
🏢 Business Domain Detection: DNS-based detection for custom domains (Google Workspace, Microsoft 365, etc.)
🔒 URL Safety: HTTPS-only login URLs with host allowlisting and malicious pattern checks
🛡️ Build Integrity: SHA-256 hash gate on provider data in CI/build (npm provenance for publishes)
📝 Type Safe: Full TypeScript support with overloads for simplified vs extended responses
⚡ Performance Oriented: Smart DNS fallback with configurable timeouts
🚦 DNS Rate Limiting: Process-wide limiter (default 10 detections / minute)
🔄 Automatic Email Normalization: Provider-specific alias rules applied in detection results
🔄 Email Alias Detection: Normalize Gmail dots, plus addressing, and provider-specific aliases
📦 Batch Processing: Efficiently process multiple emails with deduplication
🧪 Thoroughly Tested: 431 tests (430 standard + 1 live DNS) with ~91.5% statement coverage

Installation

Using npm:

npm install @mikkelscheike/email-provider-links

Requirements

Node.js: >=18.0.0 (Tested on 18.x, 20.x, 22.x, 24.x, 25.x)
TypeScript: >=4.0.0 (optional, but recommended)
Zero runtime dependencies - No external packages required

Node.js 24/25 Support ✨

Fully compatible with the latest Node.js 24.x and 25.x! The library is tested on:

Node.js 18.x (LTS)
Node.js 20.x (LTS)
Node.js 22.x
Node.js 24.x - Full support
Node.js 25.x (Latest) - Full support with latest features

Supported Providers

140 providers supporting 259 domains including:

Major Providers: Gmail, Outlook, Yahoo, ProtonMail, iCloud, Tutanota
Business Email: Microsoft 365, Google Workspace, Amazon WorkMail (via DNS detection)
International: GMX, Web.de, QQ Mail, Yandex, Naver, and 100+ more
Privacy-focused: ProtonMail, Tutanota, Hushmail, SimpleLogin, AnonAddy

See the full provider list in the Advanced Usage section.

Quick Start

import { getEmailProvider } from '@mikkelscheike/email-provider-links';

// Get provider info for any email
const result = await getEmailProvider('[email protected]');
console.log(result.provider?.loginUrl); // "https://mail.google.com/mail/"

// Works with business domains too (via DNS lookup)
const business = await getEmailProvider('[email protected]');
console.log(business.provider?.companyProvider); // "Google Workspace" or "Microsoft 365"

Key Features:

✨ Automatic Email Normalization: Emails are normalized using provider-specific rules (e.g., [email protected] → [email protected])
📦 Simplified Response (Default): Returns only essential fields. Use { extended: true } for full provider details
🚀 Fast: Known providers detected instantly, business domains via concurrent DNS lookups

API Reference

Core Functions

`getEmailProvider(email, options?)`

Recommended - Complete provider detection with business domain support.

Error notes:

INVALID_EMAIL is returned for common malformed inputs (e.g. missing @, missing TLD).
IDN_VALIDATION_ERROR is reserved for true encoding issues.

// Default: Simplified response (recommended for frontend)
const result1 = await getEmailProvider('[email protected]');
// Returns: {
//   provider: { companyProvider: "Gmail", loginUrl: "https://mail.google.com/mail/", type: "public_provider" },
//   email: "[email protected]",
//   detectionMethod: "domain_match"
// }

// Email normalization is automatic
const result2 = await getEmailProvider('[email protected]');
// Returns: {
//   provider: { companyProvider: "Gmail", loginUrl: "https://mail.google.com/mail/", type: "public_provider" },
//   email: "[email protected]",  // Normalized
//   detectionMethod: "domain_match"
// }

// Extended response (includes domains, alias config, etc.)
const extended = await getEmailProvider('[email protected]', { extended: true });
// Returns: {
//   provider: {
//     companyProvider: "Gmail",
//     loginUrl: "https://mail.google.com/mail/",
//     domains: ["gmail.com", "googlemail.com"],  // Only in extended
//     alias: { dots: { ignore: true, strip: false }, ... },  // Only in extended
//     type: "public_provider"
//   },
//   email: "[email protected]",
//   loginUrl: "https://mail.google.com/mail/",  // Top-level loginUrl only in extended
//   detectionMethod: "domain_match"
// }

// Business domains (DNS lookup with timeout)
const result3 = await getEmailProvider('[email protected]', { timeout: 2000 });
// Returns: {
//   provider: { companyProvider: "Google Workspace", loginUrl: "...", type: "custom_provider" },
//   email: "[email protected]",
//   detectionMethod: "mx_record"
// }

`getEmailProviderSync(email, options?)`

Fast - Instant checks for known providers (no DNS lookup). Synchronous version for when you can't use async.

// Default: Simplified response
const result = getEmailProviderSync('[email protected]');
// Returns: {
//   provider: { companyProvider: "Outlook", loginUrl: "https://outlook.live.com/", type: "public_provider" },
//   email: "[email protected]",
//   detectionMethod: "domain_match"
// }

// Email normalization is automatic
const result2 = getEmailProviderSync('[email protected]');
// Returns: {
//   provider: { companyProvider: "Gmail", loginUrl: "https://mail.google.com/mail/", type: "public_provider" },
//   email: "[email protected]",  // Normalized
//   detectionMethod: "domain_match"
// }

// Extended response (includes domains, alias config, etc.)
const extended = getEmailProviderSync('[email protected]', { extended: true });
// Returns full provider object with domains array and alias configuration

`getEmailProviderFast(email, options?)`

Performance-focused - Enhanced provider detection with performance metrics (timing, confidence, debug) for monitoring and debugging.

// Default: Simplified response with performance metrics
const result = await getEmailProviderFast('[email protected]');
// Returns: {
//   provider: { companyProvider: "Gmail", loginUrl: "https://mail.google.com/mail/", type: "public_provider" },
//   email: "[email protected]",
//   detectionMethod: "domain_match",
//   timing: { mx: 0, txt: 0, total: 0 },  // DNS query timings (0ms for known providers)
//   confidence: 1.0                        // Confidence score (0-1)
// }

// Extended response with performance metrics
const extended = await getEmailProviderFast('[email protected]', { extended: true });
// Returns full provider object (domains, alias config, etc.) plus timing and confidence

// Business domain with debug info enabled
const business = await getEmailProviderFast('[email protected]', {
  timeout: 2000,
  enableParallel: true,
  collectDebugInfo: true,
  extended: true
});
// Returns: {
//   provider: { ...full provider details... },
//   email: "[email protected]",
//   detectionMethod: "mx_record",
//   timing: { mx: 120, txt: 95, total: 125 },  // Actual DNS query times
//   confidence: 0.95,                          // Confidence based on DNS match quality
//   debug: {                                    // Detailed DNS query information
//     mxMatches: ["aspmx.l.google.com"],
//     txtMatches: [],
//     queries: [...],
//     fallbackUsed: false
//   }
// }

Options:

timeout?: number - DNS query timeout in milliseconds (default: 5000)
enableParallel?: boolean - Enable parallel MX/TXT lookups for faster detection (default: true)
collectDebugInfo?: boolean - Include detailed debug information in result (default: false)
extended?: boolean - Return full provider details including domains and alias configuration (default: false)

When to use getEmailProviderFast:

You need performance metrics (timing, confidence) for monitoring
You're debugging DNS detection issues
You want fine-grained control over DNS query behavior
You're building performance dashboards or analytics

Note: For most use cases, getEmailProvider() is sufficient. Use getEmailProviderFast() when you specifically need the performance metrics or debugging capabilities.

Real-World Example

async function handlePasswordReset(email: string) {
  // Validate email first
  const validation = validateEmailAddress(email);
  if (!validation.isValid) {
    throw new Error(`Invalid email: ${validation.error?.message}`);
  }

  // Get provider information (default: simplified response)
  // Email is automatically normalized in result
  const result = await getEmailProvider(email);
  
  return {
    providerUrl: result.provider?.loginUrl || null,  // Access loginUrl from provider object
    providerName: result.provider?.companyProvider || null,
    normalizedEmail: result.email, // Already normalized (e.g., '[email protected]' from '[email protected]')
    isSupported: result.provider !== null,
    detectionMethod: result.detectionMethod
  };
}

// If you need full provider details (domains, alias config, etc.)
async function analyzeEmailProvider(email: string) {
  const result = await getEmailProvider(email, { extended: true });
  
  // Access full provider details
  if (result.provider) {
    console.log('All domains:', result.provider.domains);
    console.log('Alias rules:', result.provider.alias);
  }
  
  return result;
}

Configuration

// Custom DNS timeout (default: 5000ms)
const result = await getEmailProvider(email, { timeout: 2000 });

// Extended response with custom timeout
const extended = await getEmailProvider(email, { timeout: 2000, extended: true });

// Rate limiting configuration
import { Config } from '@mikkelscheike/email-provider-links';
console.log('Max requests:', Config.MAX_DNS_REQUESTS_PER_MINUTE); // 10
console.log('Default timeout:', Config.DEFAULT_DNS_TIMEOUT);       // 5000ms

Advanced Usage

Library Statistics

import { getLibraryStats, getSupportedProviders } from '@mikkelscheike/email-provider-links';

const stats = getLibraryStats();
console.log(`Version ${stats.version} supports ${stats.providerCount} providers`);

const providers = getSupportedProviders();
console.log(`Total providers: ${providers.length}`);

Email Alias Detection & Normalization

The library automatically normalizes emails using provider-specific rules. For example, [email protected] becomes [email protected] because Gmail ignores plus addressing.

import { normalizeEmail, emailsMatch } from '@mikkelscheike/email-provider-links';

// Normalize emails to canonical form
const canonical = normalizeEmail('[email protected]');
console.log(canonical); // '[email protected]'

// Check if two emails are the same (accounting for aliases)
emailsMatch('[email protected]', '[email protected]'); // true (Gmail ignores dots)
emailsMatch('[email protected]', '[email protected]'); // false (Outlook preserves dots)

// Provider-specific rules:
// - Gmail: Ignores dots and plus addressing
// - Outlook: Preserves dots, ignores plus addressing
// - Yahoo: Preserves dots, ignores plus addressing
// - Most others: Preserve everything except case

Provider Support Checking

import { isEmailProviderSupported, extractDomain } from '@mikkelscheike/email-provider-links';

// Check if provider is supported
const supported = isEmailProviderSupported('[email protected]');

// Extract domain safely
const domain = extractDomain('[email protected]');
console.log(domain); // 'example.com'

Performance and Detection System

Development Mode Features

When NODE_ENV is set to 'development', the library provides additional insights:

// Memory usage is automatically logged:
// Current memory usage: 0.08 MB

Performance Benchmarks

Extensively optimized for both speed and memory efficiency:

Speed Metrics:

Initial provider load: ~0.5ms
Known provider lookup: <1ms
DNS-based detection: ~10ms average
Batch processing: 1000 operations in ~1.1ms
Email validation: <1ms for complex IDN domains

Memory Management:

Initial load: ~0.10MB heap usage
Batch operations: ~0.00004MB per 1000 operations
Maximum load: < 25MB under heavy concurrent operations
Cache efficiency: >99% hit rate
Garbage collection: Automatic optimization

Real-World Performance:

50,000+ operations/second for known providers
100 concurrent DNS lookups in <1 second
Average latency: <1ms for cached lookups
Maximum latency: <25ms per lookup

To run benchmarks:

# Memory usage benchmark
npm run benchmark:memory

# DNS performance benchmark
npm run benchmark:dns

# Both scripts are available in the scripts/ directory
# and can be modified for custom performance testing

Live DNS verification (optional)

There is an optional test suite that performs real DNS lookups for all domains in providers/emailproviders.json. This test is skipped by default but can be enabled easily:

# Run all tests including live DNS verification
npm run test:live-dns

# Run only the live DNS test
npm run test:live-dns -- __tests__/provider-live-dns.test.ts

Note: The live DNS test performs actual network requests and may take a few seconds to complete. Some performance tests may fail when live DNS is enabled due to network latency.

Optional strict mode (also validates configured MX/TXT patterns):

RUN_LIVE_DNS_STRICT=1 npm run test:live-dns -- __tests__/provider-live-dns.test.ts

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines on adding new email providers.

Quality Assurance: This project maintains high standards with 431 comprehensive tests (430 standard + 1 live DNS) and ~91.5% statement coverage.

Security: Login URLs are HTTPS-only and host-allowlisted. Provider JSON integrity is verified in the build pipeline; published packages use npm provenance. See Security Policy.

Security

For security concerns or to report vulnerabilities, see our Security Policy.

License

MIT License - see LICENSE file for details.

Zero dependencies • TypeScript-first • Production ready • International support