How Holehe Checks if an Email is Registered on Websites: Technical Deep Dive

Holehe determines email registration status by executing service-specific asynchronous modules that probe public APIs, password-reset endpoints, and registration forms to detect whether an address exists in a platform's user database.

Holehe is an open-source email registration checker maintained by megadose that verifies if an email address is registered across thousands of online services. The tool employs a modular architecture where each service implements a dedicated detection strategy, orchestrated through Python's asyncio and aiohttp to run thousands of checks concurrently.

Core Orchestration in holehe/core.py

The execution flow begins in holehe/core.py, which exports the run_holehe function. This orchestrator builds a shared aiohttp.ClientSession and dynamically loads every asynchronous function exported by modules under holehe/modules/.

Each module receives three arguments: the target email address, the shared HTTP client, and a result-collector object. The core executes these functions concurrently using asyncio.gather(), then aggregates responses into a list of (service, status) tuples or a formatted CLI table.

Detection Strategies for Email Verification

Individual modules implement one of four technical patterns to check if an email is registered on websites:

Public "Email-Available" APIs

Many platforms expose lightweight JSON endpoints explicitly designed to check username or email availability. The modules send targeted POST requests and parse specific response fields.

• Google: Posts to https://accounts.google.com/_/signup/webusernameavailability and inspects the "taken" boolean in the JSON response.
• GitHub: Sends a POST to https://github.com/signup_check/email and evaluates the "email" field of the returned payload.
• Replit: Queries https://replit.com/data/user/exists with the email in the request body, interpreting the exists boolean.

These implementations reside in holehe/modules/mails/google.py, holehe/modules/programing/github.py, and holehe/modules/programing/replit.py respectively.

Password-Reset Endpoint Analysis

When public availability APIs are absent, Holehe mimics a forgot-password request and analyzes the HTTP response or HTML content. This method relies on the fact that password recovery flows typically return distinct error messages for non-existent accounts.

For example, the Yahoo module in holehe/modules/mails/yahoo.py posts to Yahoo's password-reset service and parses the returned HTML for "not found" or similar absence indicators.

Form Validation via POST Requests

Legacy platforms and social media sites often validate emails through internal registration endpoints that return JSON error objects. The modules extract CSRF tokens when necessary, submit the email to these endpoints, and decode the validation response.

• Instagram: Located in holehe/modules/social_media/instagram.py, this module POSTs to an internal validation URL and checks the exists flag in the JSON response.
• Forum Software: Modules like thevapingforum.py use legacy xmlhttp.php endpoints that return 0 or 1 to indicate email availability.

HTML Scraping with Token Extraction

For sites lacking API endpoints, modules fetch the registration page, extract hidden CSRF tokens using regex or HTML parsing, submit the registration form with the target email, and parse the resulting HTML for strings like "already registered" or "email taken".

How to Use Holehe

Holehe operates as both a command-line tool and a Python library.

Command-Line Usage

Check a single address across all supported services:

holehe example@domain.com

Limit checks to specific platforms:

holehe -l google,github,instagram example@domain.com

Programmatic Usage

Import run_holehe from holehe/core.py to integrate email checking into Python applications:

import asyncio
from holehe.core import run_holehe

async def main():
    results = await run_holehe(
        email="example@domain.com",
        modules=["google", "github", "instagram"]
    )
    for service, status in results:
        print(f"{service}: {status}")

asyncio.run(main())

The run_holehe function returns a list of tuples containing the service name and registration status (registered, available, or unknown).

Key Implementation Files

The modular architecture relies on these critical components:

• holehe/core.py: Main orchestrator that builds the aiohttp client and manages concurrent execution.
• holehe/modules/__init__.py: Registry that exposes each service module's async function to the core loader.
• holehe/instruments.py: Defines custom Trio progress instruments used by the async runner for CLI feedback.
• holehe/modules/mails/google.py: Demonstrates public API availability checking against Google's account system.
• holehe/modules/programing/github.py: Shows POST-based validation endpoint implementation.
• holehe/modules/social_media/instagram.py: Illustrates JSON-based validation with CSRF handling.

Summary

• Holehe checks email registration by running service-specific async modules that probe different endpoint types.
• The tool uses aiohttp for concurrent HTTP requests, managed by the run_holehe function in holehe/core.py.
• Detection methods include public availability APIs, password-reset analysis, form validation endpoints, and HTML scraping.
• Each module returns one of three states: registered, available, or unknown.
• The modular design allows easy extension by adding new service files under holehe/modules/.

Frequently Asked Questions

How does Holehe handle rate limiting when checking multiple services?

Holehe executes requests concurrently using asyncio, but individual modules implement service-specific delays and error handling. The tool respects each platform's response patterns; when a service returns HTTP 429 (Too Many Requests) or CAPTCHA challenges, the module marks the result as "unknown" rather than hammering the endpoint.

Is it legal to use Holehe to check if an email is registered on websites?

Holehe performs read-only operations equivalent to manually visiting registration pages or using public APIs. However, users must comply with each platform's Terms of Service and applicable data protection laws. The tool should only be used for security research, OSINT investigations on your own accounts, or with explicit permission.

What is the difference between public API checks and password-reset methods?

Public API checks query endpoints explicitly designed to return availability status (e.g., Google's username availability endpoint), providing fast, reliable boolean responses. Password-reset methods simulate "forgot password" flows and infer registration status from error messages, which is slower and more fragile but works when no public API exists.

How accurate is Holehe's email registration detection?

Accuracy depends on the service module's maintenance status and the target platform's anti-bot measures. Public API methods achieve near-perfect accuracy, while HTML scraping methods may return "unknown" if the site changes its DOM structure or implements CAPTCHA. The tool is most reliable for major platforms like Google, GitHub, and Instagram where modules are actively maintained.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}