Step 1: Email Parsing & Normalization

First, the email address is parsed and normalized:

• Extracts the domain from the email (e.g., example.com from user@example.com)
• Normalizes Gmail addresses by removing dots and plus aliases (e.g., john.doe+tag@gmail.com → johndoe@gmail.com)
• Handles common email alias patterns for other providers

Step 2: Domain Database Lookup

The library maintains a comprehensive database of 218+ email domains mapped to their providers. This includes:

• Consumer providers: gmail.com → Gmail, outlook.com → Microsoft Outlook, yahoo.com → Yahoo Mail, etc.
• International variants: gmail.co.uk, outlook.fr, yahoo.co.jp, and many more
• Provider aliases: Multiple domains pointing to the same provider (e.g., hotmail.com, live.com → Outlook)

Result: If found, returns instantly with detectionMethod: 'domain_match' (typically <1ms).

Step 3: DNS MX Record Analysis

If the domain isn't in the database (common for business/custom domains), the library performs DNS lookups:

• MX Record Query: Queries DNS for Mail Exchange (MX) records to find the mail server
• Pattern Matching: Analyzes MX record hostnames for known patterns:
  • *.google.com or *.googlemail.com → Google Workspace
  • *.outlook.com, *.office365.com, *.mail.protection.outlook.com → Microsoft 365
  • *.yahoo.com, *.yahoodns.net → Yahoo Mail
  • And many more patterns for other providers
• Timeout Protection: DNS queries are limited by a configurable timeout (default 5 seconds) to prevent hanging

Result: If a pattern matches, returns with detectionMethod: 'mx_record' or detectionMethod: 'mx_pattern' (typically 50-500ms depending on DNS response time).

Step 4: Heuristic Detection

For domains that don't match known patterns, the library uses heuristics to detect:

• Email Alias Services: Detects proxy/alias services like SimpleLogin, AnonAddy, Firefox Relay by analyzing MX records and domain patterns
• Provider-Specific Patterns: Recognizes common email forwarding services and their characteristics
• Domain Analysis: Examines domain structure, TLD patterns, and other signals

Result: May identify proxy services or provide hints about the email infrastructure.

Step 5: Login URL Retrieval

Once a provider is identified, the library retrieves the appropriate login URL:

• Pre-configured URLs: Each provider in the database has a verified HTTPS login URL
• Security Validation: All URLs are validated to ensure they:
  • Use HTTPS protocol only
  • Match allowlisted domains
  • Pass malicious pattern detection (no IP addresses, URL shorteners, etc.)
  • Are protected against injection attacks

Step 6: Response Formatting

The library returns a structured result object:

{
  provider: {
    companyProvider: "Gmail",
    loginUrl: "https://mail.google.com/mail/"
  },
  email: "user@gmail.com",
  detectionMethod: "domain_match",
  // Extended mode includes additional metadata:
  // - MX records analyzed
  // - Detection timing breakdown
  // - Provider metadata
}