What Is the Standard Schema for Holehe Results? A Complete Technical Guide

Holehe returns a standardized list of dictionaries containing eight specific fields—name, domain, exists, rateLimit, error, emailrecovery, phoneNumber, and others—ensuring uniform output across all website modules regardless of success or failure states.

Holehe is an open-source email reconnaissance tool developed by megadose that checks whether an email address is registered across hundreds of websites. Understanding the standard schema for Holehe results is essential for building automated workflows, parsing JSON outputs, and processing CSV exports consistently. This schema acts as a contract between the individual site modules and the core orchestration logic, guaranteeing that every probe returns a predictable data structure.

The Eight-Field Holehe Result Schema

Every website check performed by Holehe generates a dictionary with exactly eight keys. This fixed structure allows the CLI and programmatic consumers to process results without conditional logic for missing fields.

Core Identity Fields

• name (str): The internal identifier of the module performing the check (e.g., twitter, github, instagram).
• domain (str): The human-readable website domain (e.g., twitter.com, github.com).

These fields provide immediate context about which service was queried, appearing first in CLI outputs and serving as primary keys in CSV exports.

Status Indicators

Three boolean flags communicate the outcome of each request:

• exists (bool): True when the email address is registered on the target site; False if the account does not exist or if the check was inconclusive.
• rateLimit (bool): True when the target website rejected the request due to rate limiting, preventing a definitive answer.
• error (bool): True if an unexpected exception occurred during the module execution (network errors, parsing failures, site changes).

According to the source code in holehe/core.py, these booleans are mutually prioritized: if error or rateLimit is True, the exists field should be interpreted with caution.

Recovery Metadata

When available, Holehe extracts account recovery information leaked by the website's password reset flow:

• emailrecovery (str | None): Information returned by the site's recovery mechanism, such as masked email addresses (e.g., a***@gmail.com) or confirmation messages.
• phoneNumber (str | None): Partial or complete phone numbers associated with the account, if the module successfully extracts them from recovery pages.

Not all modules populate these fields, and many return None when the site does not expose recovery information or when the check fails.

Extensibility Container

• others (dict | None): A flexible dictionary for module-specific data that does not fit standard fields. Common entries include FullName, account creation dates, profile URLs, or custom error messages.

This field prevents schema fragmentation, allowing developers to expose new data points without breaking existing parsers that rely on the eight-field structure.

Where the Schema Is Implemented in the Source Code

The standard schema is defined implicitly through consistent usage across holehe/core.py, specifically within three critical functions:

• launch_module (line ≈ 171): When a module raises an exception, this function constructs a fallback dictionary conforming to the schema, setting error to True and populating remaining fields with default values. This guarantees that even failed checks return valid records.
• export_csv: This function uses data[0].keys() to write CSV headers, confirming that the first result's dictionary keys define the fixed column order for all exports.
• print_result: The CLI formatting logic reads the same eight keys to generate color-coded terminal output, mapping exists to green/red indicators and highlighting rateLimit warnings.

Individual modules in holehe/modules/**/*.py populate these dictionaries by returning the eight-field structure at the end of their execution flow.

Working with Holehe Results Programmatically

Basic Command-Line Usage

Generate CSV output containing the standard schema:

holehe user@example.com --csv

This command creates a color-coded terminal table and writes holehe_<timestamp>_user@example.com_results.csv with columns matching the eight-field schema exactly.

Parsing Results in Python

When importing Holehe as a library or processing saved JSON, treat the output as a list of dictionaries:

import json

# Example result set returned by Holehe

results = [
    {
        "name": "twitter",
        "domain": "twitter.com",
        "exists": True,
        "rateLimit": False,
        "error": False,
        "emailrecovery": "Password reset link sent",
        "phoneNumber": None,
        "others": {"FullName": "Jane Doe", "username": "janedoe"}
    },
    {
        "name": "github",
        "domain": "github.com",
        "exists": False,
        "rateLimit": False,
        "error": False,
        "emailrecovery": None,
        "phoneNumber": None,
        "others": None
    }
]

# Extract domains where the email exists

confirmed_sites = [r["domain"] for r in results if r["exists"]]
print(f"Email found on: {confirmed_sites}")

Filtering for Valid Registrations Only

Exclude rate-limited responses and errors to analyze confirmed accounts:

def get_valid_accounts(data):
    """Filter results to return only confirmed registrations without errors."""
    return [
        r for r in data 
        if r["exists"] and not r["error"] and not r["rateLimit"]
    ]

valid_accounts = get_valid_accounts(results)
print(f"Valid registrations: {len(valid_accounts)}")

Accessing Extended Metadata

Inspect the others field for additional intelligence gathered by specific modules:

for result in results:
    if result["others"] and "FullName" in result["others"]:
        print(f"{result['domain']}: {result['others']['FullName']}")

Summary

• Fixed Structure: Every Holehe result contains exactly eight fields: name, domain, exists, rateLimit, error, emailrecovery, phoneNumber, and others.
• Guaranteed Consistency: The launch_module function in holehe/core.py enforces this schema even when modules crash or hit rate limits, ensuring no KeyError exceptions in downstream processing.
• CSV Compatibility: The export_csv function relies on the schema's uniformity to generate headers dynamically from the first result's keys.
• Extensibility: The others dictionary allows modules to expose custom data without breaking the standard contract.
• Boolean Logic: Always check error and rateLimit before trusting the exists field to avoid false positives.

Frequently Asked Questions

What happens when a module fails or hits a rate limit?

Holehe returns a complete dictionary conforming to the standard schema regardless of outcome. If a module raises an exception, error is set to True and exists defaults to False. If a rate limit is detected, rateLimit becomes True. This design, implemented in the exception handler at line ≈ 171 of holehe/core.py, ensures your parsing logic never encounters missing keys.

How do I export Holehe results to CSV format?

Use the --csv flag when running from the command line: holehe user@example.com --csv. The tool writes a timestamped CSV file where headers are derived from the first result's dictionary keys (data[0].keys()), guaranteeing alignment with the eight-field schema. You can also process the JSON output programmatically and use Python's csv.DictWriter to maintain the same column order.

Can I add custom fields to the Holehe result schema?

No, you should not add top-level fields to the standard schema, as this would break CSV exports and CLI formatting in holehe/core.py. Instead, place custom data inside the others dictionary. This container accepts any serializable dictionary without affecting the fixed eight-field structure that downstream tools expect.

How do I filter only confirmed email registrations from the output?

Iterate through the results list and check three conditions: exists must be True, while error and rateLimit must both be False. This excludes inconclusive results caused by network failures or anti-bot protections, yielding only verified account registrations.

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