Holehe Standardized Result Dictionary: The 7 Fields Every OSINT Module Returns

The Holehe standardized result dictionary contains seven required keys—domain, exists, emailrecovery, phoneNumber, others, rateLimit, and error—that enable the core printer to process email-checking results from thousands of services uniformly.

The megadose/holehe repository enforces a strict data contract between its modules and central output logic. Every OSINT module returns this standardized dictionary to holehe/core.py, ensuring consistent formatting regardless of which website or service was queried. Understanding these seven fields is essential for developers extending Holehe with custom modules or parsing its JSON output programmatically.

The Seven Required Dictionary Fields

Every module in the holehe/modules/ directory constructs a dictionary with identical top-level keys. The core printer expects this exact structure, as implemented in the print_result function at lines 123–144 of holehe/core.py.

Domain and Existence Indicators

domain stores the target website or service as a string (e.g., "facebook.com"), identifying which service was queried. exists is a boolean flag indicating whether the supplied email address is registered on that service—True confirms an account exists, while False indicates it does not.

Recovery and Contact Information

emailrecovery captures any password-reset hints exposed by the service, typically returning a string like "p***@example.com" or None if no hint is available. phoneNumber stores partial or full phone numbers leaked by the service during the check, also returning a string or None when no data is exposed.

Extensible Metadata and Error States

others provides a free-form dictionary for additional scraped data—such as full names, account creation dates, or profile URLs—that does not fit the standard schema. rateLimit is a boolean set to True when the service enforces rate limiting and the check must be skipped. error signals unexpected failures like network timeouts or parsing exceptions, returning True when the module encounters an exception rather than a valid response.

How the Core Printer Processes the Dictionary

The print_result function in holehe/core.py evaluates these fields in a specific priority order to determine output formatting:

1. Rate Limit Check: if results["rateLimit"] triggers first, handling services that blocked the request due to throttling.
2. Error Handling: elif "error" in results.keys() and results["error"] catches unexpected exceptions and prints generic error messages.
3. Non-Existence: elif results["exists"] == False reports that the email is not registered on the service.
4. Successful Matches: elif results["exists"] == True builds the success line, conditionally appending emailrecovery, phoneNumber, and values from the others dictionary.

This branching logic ensures that rateLimit and error states take precedence over existence checks, preventing false negatives when services block requests.

Implementing the Contract in Custom Modules

When developing new modules for the holehe/modules/ directory, you must return the complete dictionary structure even for failed checks. The core printer relies on every key being present to avoid KeyError exceptions during output generation.

# Example module implementation from holehe/modules/social_media/facebook.py

def check_facebook(email, client, out):
    try:
        # ... HTTP request logic ...

        return {
            "domain": "facebook.com",
            "exists": True,
            "emailrecovery": "j***@gmail.com",
            "phoneNumber": None,
            "others": {"FullName": "John Doe", "ProfileURL": "..."},
            "rateLimit": False,
            "error": False,
        }
    except Exception:
        return {
            "domain": "facebook.com",
            "exists": False,
            "emailrecovery": None,
            "phoneNumber": None,
            "others": None,
            "rateLimit": False,
            "error": True,
        }

The out parameter in modern Holehe versions acts as a list append function, but the underlying dictionary structure remains identical. Always populate all seven keys to maintain compatibility with the printer logic in holehe/core.py.

Summary

• Seven mandatory keys: domain, exists, emailrecovery, phoneNumber, others, rateLimit, and error form the standardized contract.
• Core processing: The printer in holehe/core.py (lines 123–144) evaluates rateLimit and error before checking exists to ensure accurate status reporting.
• Extensibility: The others dictionary allows modules to return service-specific data without breaking the standard schema.
• Consistency: Every module from holehe/modules/social_media/ to holehe/modules/shopping/ must return this identical structure for the CLI and JSON output to function correctly.

Frequently Asked Questions

What happens if a Holehe module omits one of the required dictionary keys?

The core printer in holehe/core.py will raise a KeyError when attempting to access the missing field, typically during the conditional checks at lines 123–144. All seven keys must be present in every return statement, even when their values are None or False.

Can the others dictionary contain nested data structures?

Yes, the others field accepts any valid Python dictionary, including nested objects, lists, or additional metadata. The core printer stringifies these values when displaying results, making it suitable for complex data like profile timestamps, avatar URLs, or location histories scraped by individual modules.

How does Holehe handle rate limiting differently from errors?

When rateLimit is True, the printer in holehe/core.py reports that the service blocked the request due to throttling, distinguishing it from technical failures. The error flag indicates unexpected exceptions like network timeouts or HTML parsing failures, while rateLimit specifically signals HTTP 429 responses or CAPTCHA challenges that prevent the check from completing.

Is the standardized dictionary format documented in the Holehe source code?

The schema is enforced through the print_result function implementation in holehe/core.py rather than formal type hints. Developers should examine lines 123–144 of that file and reference existing modules in holehe/modules/social_media/facebook.py to understand the expected return structure for the megadose/holehe codebase.

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