Email Sleuth

A Rust application to discover and verify professional email addresses based on contact names and company websites. This tool helps you find valid email addresses for business contacts when you have their name and company domain.

Installation and Setup

One-Line Unified Installation

Our unified installer handles everything you need:

curl -fsSL https://raw.githubusercontent.com/buyukakyuz/email-sleuth/main/setup.sh | bash

This will:

1. Install the Email Sleuth binary
2. Install ChromeDriver for enhanced verification (if desired)
3. Set up service management scripts
4. Create a default configuration

Verify Installation

# Check if email-sleuth is properly installed
es --version

Alternative Installation Methods

Manual Binary Download (All Platforms)

If you prefer not to use the script, or are on Windows:

1. Go to the Releases page.
2. Find the latest release and locate the correct archive under "Assets" for your Operating System and Architecture.
3. Download and extract the archive.
4. Move the extracted email-sleuth (or email-sleuth.exe on Windows) executable to a directory in your system's PATH.
5. (Linux/macOS only) Make the binary executable: chmod +x /path/to/email-sleuth.
6. Verify by opening a new terminal and running: email-sleuth --version.

Build from Source (Developers)

Requires the Rust toolchain (>= 1.70 recommended).

# 1. Install Rust: https://www.rust-lang.org/tools/install
# 2. Clone the repository
git clone https://github.com/buyukakyuz/email-sleuth.git
cd email-sleuth

# 3. Build the optimized release binary
cargo build --release

# 4. The executable is at target/release/email-sleuth (or .exe)
#    Copy it to your PATH

Usage

Simple Single Contact Lookup

# Basic search (SMTP verification only)
es "John Doe" example.com

# Enhanced search (using API checks)
es -m enhanced "John Doe" example.com

# Comprehensive search (using all verification methods)
es -m comprehensive "John Doe" example.com

Batch Processing

# Process all contacts in input.json with basic verification
es -i contacts.json -o results.json

# Process with comprehensive verification
es -m comprehensive -i contacts.json -o results.json

Managing ChromeDriver Service

# Check status
es --service status

# Start the service
es --service start

# Stop the service
es --service stop

# Restart the service
es --service restart

Verification Modes

Email Sleuth offers three verification modes to balance speed, accuracy, and resource usage:

Input File Format (input.json) for Batch Mode

A JSON array of objects. Each object needs name fields (first_name and last_name) and a domain.

[
  {
    "first_name": "John",
    "last_name": "Smith",
    "domain": "example.com"
  },
  {
    "first_name": "Jane",
    "last_name": "Doe",
    "domain": "acme.com"
  }
]

(See examples/example-contacts.json for a more detailed example)

Output Format (results.json)

The tool produces a detailed JSON output for each contact processed. In CLI mode with --stdout true, a simplified summary is printed. When outputting to a file, the full structure is saved.

[
  {
    "contact_input": { /* Original input contact data */ },
    "email": "[email protected]", // Best guess found (or null)
    "confidence_score": 8,             // Confidence (0-10) for 'email'
    "found_emails": [                  // All plausible candidates found
      {
        "email": "[email protected]",
        "confidence": 8,
        "source": "pattern", // "pattern", "scraped", "smtp", "api", "headless", etc.
        "is_generic": false,
        "verification_status": true, // true (exists), false (doesn't), null (inconclusive/skipped)
        "verification_message": "SMTP Verification OK: 250 2.1.5 Ok"
      }
      // ... other candidates
    ],
    "methods_used": ["pattern_generation", "smtp_verification"], // Methods used during discovery
    "verification_log": { /* Detailed verification check logs */ },
    "email_finding_skipped": false, // True if input was invalid
    "email_finding_error": null   // Unexpected processing errors
  },
  // ... results for other contacts
]

Configuration

Your configuration file is located at ~/.config/email-sleuth/config.toml after installation with the setup script.

SMTP Requirements

Email verification using SMTP requires outbound access to port 25, which many ISPs block. If you see "Connection timed out" or similar errors, try:

1. Using the enhanced or comprehensive modes which include alternative verification methods
2. Running on a cloud server (AWS EC2, DigitalOcean, etc.)
3. Using a VPN service that allows port 25 traffic

The tool will automatically test your SMTP connectivity during startup and warn you if it's blocked.

Troubleshooting

SMTP Connection Issues

If you see errors about SMTP connectivity:

1. Your ISP may be blocking port 25
2. Try using the enhanced verification modes:

   es -m enhanced "John Smith" acme.com

License

MIT License