Holehe Module Results: Understanding the Expected Output Format and Data Schema

Holehe module results follow a strict Python dictionary schema (JSON-compatible) containing standardized keys like exists, rateLimit, emailrecovery, and domain, which are aggregated into a list and processed by print_result in holehe/core.py for terminal display or CSV export.

Holehe is an open-source email OSINT tool that verifies whether an email address is registered across hundreds of websites. When working with Holehe module results, understanding the standardized output format is essential for parsing terminal reports, handling errors programmatically, and exporting data for further analysis. The tool enforces a fixed dictionary schema that every site-specific module must return, ensuring consistent data handling from the initial request through to final output rendering.

Fixed Dictionary Schema for Holehe Output

Every module in the Holehe ecosystem returns a Python dictionary with predefined keys. This strict schema allows holehe/core.py to uniformly process results regardless of which website was queried.

Required Dictionary Keys

Each result dictionary returned by site modules contains the following fields:

• domain (str): Human-readable identifier for the website (e.g., twitter.com).
• rateLimit (bool): Set to True if the request encountered rate limiting and the check could not complete.
• error (bool): Set to True when an unexpected exception occurs during the site query.
• exists (bool): Indicates whether the email address is registered on the platform (True) or not (False).
• emailrecovery (str or None): Recovery email address exposed by the service during the check, if available.
• phoneNumber (str or None): Phone number disclosed by the service, if any.
• others (dict or None): Extensible field for additional metadata such as full names, account creation dates, or custom error messages.

The overall data structure passed through the system is a list of these dictionaries:

[
    {
        "name": "<module_function_name>",
        "domain": "<site_identifier>",
        "rateLimit": bool,
        "error": bool,
        "exists": bool,
        "emailrecovery": str | None,
        "phoneNumber": str | None,
        "others": dict | None,
    },
    # ... additional entries for each checked website

]

Error Handling and Placeholder Entries

When the launch_module function in holehe/core.py catches an uncaught exception from a site module, it generates a fallback entry that preserves the schema structure. According to the source implementation, this placeholder maintains all required keys but sets boolean values to False and nullable fields to None, while preserving the name and domain identifiers for debugging purposes.

Terminal Output Formatting

The print_result function (defined at lines 106-151 in holehe/core.py) transforms the raw dictionary list into a color-coded terminal report. This formatting layer translates the Boolean fields into human-readable visual indicators:

• [+]: Email exists on the platform (exists == True)
• [-]: Email not found (exists == False)
• [x]: Rate limit encountered (rateLimit == True)
• [!]: Error occurred during check (error == True)

The function also renders a summary line indicating the total number of websites checked and the execution duration (e.g., "23 websites checked in 1.23 seconds").

Command Line Output Example

$ holehe user@example.com

Typical terminal output appears as follows (color codes omitted for clarity):

*************************
   user@example.com
*************************
[+] twitter.com   user@example.com
[-] github.com
[x] instagram.com
[!] facebook.com Error message: request timed out
...
23 websites checked in 2.45 seconds

Programmatic Access to Raw Results

For automation pipelines and custom integrations, you can capture the raw dictionary list before terminal formatting. The launch_module function appends results to a list passed by reference, enabling direct access to the structured data without parsing terminal output.

Python Implementation Example

import asyncio
import httpx
from holehe.core import import_submodules, get_functions, launch_module

async def run_holehe_check(email):
    modules = import_submodules('holehe.modules')
    sites = get_functions(modules)
    results = []
    
    async with httpx.AsyncClient(timeout=10) as client:
        await asyncio.gather(*[
            launch_module(site, email, client, results) 
            for site in sites
        ])
    
    # `results` contains the list of dictionaries with the fixed schema

    return results

# Execute and access raw Holehe module results

output = asyncio.run(run_holehe_check("user@example.com"))
print(output)

CSV Export Functionality

Holehe supports exporting the structured results to CSV using the --csv command-line flag. This functionality generates a timestamped file named holehe_<timestamp>_user@example.com_results.csv using the dictionary keys from the first result entry as column headers. The CSV export preserves the full schema, making it suitable for analysis in spreadsheet applications or data processing pipelines.

$ holehe user@example.com --csv

Summary

• Holehe module results utilize a strict dictionary schema with seven required keys (domain, rateLimit, error, exists, emailrecovery, phoneNumber, others).
• The launch_module function in holehe/core.py aggregates individual site results into a JSON-compatible list.
• Terminal output uses color-coded prefixes ([+], [-], [x], [!]) rendered by the print_result function to indicate account existence, rate limits, and errors.
• Raw structured data can be accessed programmatically by capturing the output list from launch_module before it reaches the formatting layer.
• CSV export via the --csv flag maintains the complete schema for external analysis.

Frequently Asked Questions

What data structure does Holehe use for module results?

Holehe returns a Python list containing dictionaries, where each dictionary represents a single website check. According to the implementation in holehe/core.py, this structure is JSON-compatible and follows a fixed schema enforced across all site modules in holehe/modules/.

How does Holehe handle failures in individual site modules?

When a module raises an uncaught exception, the launch_module function inserts a placeholder dictionary with error set to True and all other fields set to False or None, ensuring the aggregation list maintains structural integrity even when individual checks fail.

What do the [+] and [-] symbols indicate in Holehe terminal output?

In the formatted output generated by print_result, [+] indicates the email address exists on that platform (exists == True), while [-] indicates the email was not found (exists == False). The symbols [x] and [!] represent rate limiting and execution errors, respectively.

Can Holehe results be exported for use in other applications?

Yes, Holehe supports CSV export through the --csv flag, which creates a timestamped file containing all fields from the result dictionaries. Additionally, developers can import launch_module from holehe.core to capture the raw dictionary list programmatically for integration with databases, SIEM systems, or custom reporting tools.

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