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

> Discover how Holehe checks email registration by probing public APIs and registration forms. Understand the technical methods used to verify if an email exists on websites.

- Repository: [Palenath/holehe](https://github.com/megadose/holehe)
- Tags: deep-dive
- Published: 2026-08-22

---

**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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/holehe/modules/mails/google.py), [`holehe/modules/programing/github.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/programing/github.py), and [`holehe/modules/programing/replit.py`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/thevapingforum.py) use legacy [`xmlhttp.php`](https://github.com/megadose/holehe/blob/main/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:

```bash
holehe example@domain.com

```

Limit checks to specific platforms:

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

```

### Programmatic Usage

Import `run_holehe` from [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) to integrate email checking into Python applications:

```python
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`](https://github.com/megadose/holehe/blob/main/holehe/core.py)**: Main orchestrator that builds the `aiohttp` client and manages concurrent execution.
- **[`holehe/modules/__init__.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/__init__.py)**: Registry that exposes each service module's async function to the core loader.
- **[`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py)**: Defines custom Trio progress instruments used by the async runner for CLI feedback.
- **[`holehe/modules/mails/google.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/mails/google.py)**: Demonstrates public API availability checking against Google's account system.
- **[`holehe/modules/programing/github.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/programing/github.py)**: Shows POST-based validation endpoint implementation.
- **[`holehe/modules/social_media/instagram.py`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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.