# What Determines `exists: True` vs `False` in Holehe Modules: A Technical Deep Dive

> Understand how Holehe modules determine email existence. Learn what triggers `exists: True` vs `False` for the megadose/holehe repository. Get the technical details.

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

---

**A Holehe module returns `exists: True` when the target service explicitly confirms an email address is already registered, and `exists: False` when the service indicates the address is available or when the module cannot determine its status.**

Holehe is an open-source reconnaissance tool by **megadose** that checks email address registration across hundreds of online services. Each service-specific module implements custom logic to interpret API responses, HTTP status codes, or HTML content—then distills that evidence into a single boolean `exists` flag. This article explains exactly how that determination happens, with concrete code examples from the repository.

---

## The Core Pattern: Service Response → Boolean Interpretation

Every Holehe module follows a consistent structure. Located in `holehe/modules/`, each file implements an async function that:

1. Sends a request to the service's registration or availability endpoint
2. Parses the response (JSON, HTML, or status code)
3. Sets `exists` based on service-specific indicators
4. Appends a standardized result dictionary

The `exists` field is **never guessed**—it is always derived from concrete service feedback as implemented in `megadose/holehe`.

---

## How Different Services Trigger `exists: True`

The exact signal varies by platform. Here are the four primary patterns found in the source code.

### JSON Field Extraction

**Twitter** queries [`/i/users/email_available.json`](https://github.com/megadose/holehe/blob/main//i/users/email_available.json) and checks the `"taken"` field:

```python

# holehe/modules/social_media/twitter.py

if req.json()["taken"]:
    out.append({
        "name": name,
        "domain": domain,
        "method": method,
        "frequent_rate_limit": False,
        "rateLimit": False,
        "exists": True,  # Email is already registered

        "emailrecovery": None,
        "phoneNumber": None,
        "others": None,
    })
else:
    out.append({"exists": False, ...})

```

**Facebook** uses the inverse pattern—checking `"available": false`:

```python

# holehe/modules/social_media/facebook.py

# Response indicates existing account when "available" is False

if not data.get("available", True):
    exists = True

```

**Blablacar** directly forwards the service's own `exists` field when present:

```python

# holehe/modules/transport/blablacar.py

if "exists" in data:
    out.append({"exists": data["exists"], ...})
else:
    out.append({"exists": False, ...})

```

### HTTP Status Code Interpretation

**Docker Hub** treats `200 OK` as confirmation of an existing account:

```python

# holehe/modules/software/docker.py

resp = await client.get(f"https://hub.docker.com/v2/users/{email}")
if resp.status_code == 200:
    out.append({"exists": True, ...})
else:
    out.append({"exists": False, ...})

```

A `404` or any non-200 response results in `exists: False`.

### HTML String Matching

**Adobe** scrapes the response body for specific error text:

```python

# holehe/modules/software/adobe.py

if "The email address you entered is already in use" in response.text:
    out.append({"exists": True, ...})
else:
    out.append({"exists": False, ...})

```

---

## When `exists` Is Forced to `False`

Modules intentionally set `exists: False` in two scenarios: when the service confirms availability, or when the check **fails entirely**.

### Explicit Service Confirmation

If Twitter returns `{"taken": false}`, Facebook returns `{"available": true}`, or Docker returns `404`, the module records `exists: False`—meaning the email appears unregistered.

### Error and Rate-Limit Handling

Any exception (network failure, rate-limiting, unexpected response format) triggers a safe fallback. As seen across all modules in `megadose/holehe`:

```python

# Generic pattern found in every module's exception handler

except Exception:
    out.append({
        "name": name,
        "domain": domain,
        "method": method,
        "frequent_rate_limit": frequent_rate_limit,
        "rateLimit": True,   # Signals uncertainty

        "exists": False,     # No definitive claim

        "emailrecovery": None,
        "phoneNumber": None,
        "others": None,
    })

```

The `rateLimit: True` flag alerts users that the `exists: False` result is **not reliable**—the check simply couldn't complete.

---

## The Result Dictionary Structure

Every module returns identical keys to [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), which orchestrates execution and printing:

```python
{
    "name": "twitter",           # Service identifier

    "domain": "twitter.com",     # Service domain

    "method": "login",           # Check method used

    "frequent_rate_limit": False, # Known rate-limit behavior

    "rateLimit": False,          # Was this attempt rate-limited?

    "exists": True,              # Core finding: account exists?

    "emailrecovery": None,       # Recovery email (if leaked)

    "phoneNumber": None,         # Phone number (if leaked)

    "others": None               # Additional metadata

}

```

The `exists` boolean is the **primary output** that drives Holehe's terminal reporting and JSON export.

---

## Module Categories and Representative Implementations

| Category | File Path | Determination Method |
|----------|-----------|----------------------|
| Social Media | [`holehe/modules/social_media/twitter.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/twitter.py) | JSON `"taken"` field |
| Social Media | [`holehe/modules/social_media/facebook.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/facebook.py) | JSON `"available"` field (inverted) |
| Transport | [`holehe/modules/transport/blablacar.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/transport/blablacar.py) | Forwarded `"exists"` from service |
| Software | [`holehe/modules/software/docker.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/software/docker.py) | HTTP 200 status code |
| Software | [`holehe/modules/software/adobe.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/software/adobe.py) | HTML error string match |
| Core Orchestration | [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) | Aggregates `exists` from all modules |

---

## Summary

- **`exists: True`** requires **explicit service confirmation** that an email is registered—via JSON field, HTTP status, or HTML indicator—not pattern matching alone.
- **`exists: False`** means the service reported availability **or** the module encountered an error and cannot make a definitive claim.
- **Each module is service-specific**—no universal "email exists" API exists, so `megadose/holehe` implements hundreds of unique parsers.
- **Errors are conservative**—any exception forces `exists: False` with `rateLimit: True` to prevent false positives.

---

## Frequently Asked Questions

### How does Holehe avoid false positives when determining `exists: True`?

Holehe modules only set `exists: True` when the target service **explicitly confirms** registration. For example, Twitter's API returns `{"taken": true}`—not merely a similar-looking response. This design prevents pattern-matching errors. When confirmation is ambiguous, modules default to `exists: False`.

### Can `exists: False` mean the check failed rather than the email is available?

Yes. The `exists: False` value appears in two cases: when the service confirms an email is free, **and** when the module hits a rate-limit, network error, or unexpected response format. Check the `rateLimit` field—if `True`, the `exists: False` result is unreliable and should be re-checked.

### Why doesn't Holehe use a single method for all services?

Each platform implements different anti-abuse protections and exposes different signals. Some return JSON ([`twitter.py`](https://github.com/megadose/holehe/blob/main/twitter.py)), others expose status codes ([`docker.py`](https://github.com/megadose/holehe/blob/main/docker.py)), and many require HTML scraping ([`adobe.py`](https://github.com/megadose/holehe/blob/main/adobe.py)). The modular architecture of `megadose/holehe` allows contributors to implement service-specific parsers without changing core logic.

### What happens if a service changes its API response format?

The module will likely catch an exception and return `exists: False` with `rateLimit: True`. This conservative fallback prevents false claims. Community contributors monitor services and update modules in `holehe/modules/` when formats change. Always use the latest version from the repository for accurate results.