What Arguments Does a Holehe Module Function Receive?

Every Holehe module function receives exactly three arguments: email (the target address as a string), client (an httpx.AsyncClient instance for HTTP requests), and out (a shared mutable list for collecting results).

Holehe is an open-source email reconnaissance tool developed by megadose that probes websites to determine if an email address is registered. Understanding the Holehe module function arguments is essential for developers extending the tool with custom service checks or debugging existing modules.

The Standard Three-Argument Contract

All modules in the Holehe ecosystem implement a uniform asynchronous interface defined by the core engine. In holehe/core.py, the launch_module function dynamically imports these check modules and invokes them with a strict three-parameter signature.

async def <module_name>(email, client, out):

This consistency allows the core runner to treat all service-checking modules—from shopping sites to social platforms—interchangeably, regardless of their internal implementation details.

Breakdown of Holehe Module Function Arguments

The email Parameter

The email parameter is a Python str containing the target email address being investigated. Modules use this value to construct login probes, registration checks, or password reset validation requests against their respective target services.

The client Parameter

The client parameter provides an httpx.AsyncClient instance pre-configured with the user-specified timeout settings from the main execution context. This shared client handles connection pooling and ensures consistent HTTP behavior across all concurrent modules. According to the source code in holehe/core.py, passing this client prevents redundant initialization and maintains unified session handling throughout the email checking process.

The out Parameter

The out parameter is a shared mutable list that acts as a result collector. Rather than returning values directly, modules append standardized dictionary objects to this list. Each result dictionary contains keys such as name, domain, method, exists, rateLimit, and frequent_rate_limit, along with optional metadata fields like emailrecovery or phoneNumber.

Core Invocation Logic in holehe/core.py

The launch_module async function in holehe/core.py demonstrates exactly how these arguments are passed to every module function:

async def launch_module(module, email, client, out):
    # `module` is the async function imported from a module file

    await module(email, client, out)      # <-- three arguments passed here

This centralized invocation pattern ensures that modules located in paths like holehe/modules/shopping/amazon.py and holehe/modules/shopping/ebay.py receive identical inputs regardless of their specific target service.

Practical Implementation Example

The following example from the Amazon module illustrates how a typical Holehe function consumes these three arguments:

# Example from holehe/modules/shopping/amazon.py

async def amazon(email, client, out):
    # email   -> "user@example.com"

    # client  -> httpx.AsyncClient instance

    # out     -> [] (shared list where result dicts are appended)

    
    # ... HTTP logic using client ...

    
    out.append({
        "name": "amazon",
        "domain": "amazon.com",
        "method": "login",
        "frequent_rate_limit": False,
        "rateLimit": False,
        "exists": True,
        # ...

    })

For developers creating custom modules, the minimal viable structure below adheres to the required contract:

async def myservice(email, client, out):
    # Perform checks using `client`

    # Append a result dict to `out`

    out.append({
        "name": "myservice",
        "domain": "myservice.com",
        "method": "login",
        "frequent_rate_limit": False,
        "rateLimit": False,
        "exists": False,
        "emailrecovery": None,
        "phoneNumber": None,
        "others": None,
    })

Summary

• Every Holehe module function must accept exactly three positional arguments: email, client, and out.
• The email argument is a string containing the target address to investigate.
• The client argument is an httpx.AsyncClient instance configured with global timeout settings from the core runner.
• The out argument is a shared mutable list where modules append result dictionaries describing account existence, rate limits, and recovery information.
• The launch_module function in holehe/core.py enforces this contract when calling modules from the holehe/modules/ directory.

Frequently Asked Questions

Does a Holehe module function return values directly?

No. Holehe modules do not use return statements to communicate results. Instead, they append standardized dictionary objects to the out parameter, which the core engine later processes through functions like print_result and optional CSV export handlers.

Can I use a different HTTP client instead of httpx inside a module?

The client argument is strictly an httpx.AsyncClient instance as configured in holehe/core.py. While you could technically import other libraries, doing so would bypass the shared connection pooling and timeout settings that Holehe relies on for performance and consistency. All official modules in holehe/modules/ use the provided client for HTTP operations.

What happens if a module fails to append to the out list?

If a module completes execution without appending a result dictionary to out, no output will be generated for that specific service. The core runner continues processing other modules, but the absence of an entry means the tool cannot determine whether the email exists on that platform, effectively excluding it from the final report.

Where is the module invocation logic defined?

The module invocation logic is defined in the launch_module async function within holehe/core.py. This function receives the module function object itself plus the three standard arguments (email, client, out), then awaits the module call, ensuring uniform argument passing across all service checks including those in holehe/modules/shopping/amazon.py and holehe/modules/shopping/ebay.py.

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