API Query Tool - Complete Documentation

1. Data Collection

Queries the Domainer's Secret DB - a private, exclusive OSINT database that contains billions of records for you to gather data based on search terms. Features multi-threading, deduplication, and intelligent filtering to avoid scraping identical data gathered from different sources during a single search.

2. List Builder

Processes collected data to create targeted email campaigns with keyword filtering, name standardization, and email validation.

3. Gmail Automation

Why send 1000's of emails by hand? Automate email sending through Gmail using chrome, you can watch the bot work or set it to headless, emails are sent with AI-generated variations, bounce detection is integrated to avoid contacting a dead email a second time on a follow up campaign.

Stats are kept on various aspects of the email automation for tracking purposes. Never send the same email twice.. Only will contact numerous times if you are doing follow up emails.

Installation & Setup

System Requirements

Python 3.8 or higher
Chrome browser installed
Minimum 4GB RAM (8GB recommended for large datasets)
Internet connection for API access
Linux/Mac/Windows (Linux recommended)

Required Python Packages

        pip install requests
        pip install selenium
        pip install seleniumbase
        pip install beautifulsoup4
        pip install sqlite3 (usually pre-installed)
      

Directory Structure

        api-query-tool/
      ├── main.py# Main entry point  
      ├── collect_data.py# Data collection module  
      ├── db.py# Database operations  
      ├── settings_loader.py# Settings management  
      ├── stats_db.py# Statistics database  
      ├── zerobounce_integration.py# Email validation  
      ├── settings.txt# Configuration file (create this)  
      ├── list_builder/# List building module  
      │   ├── main.py#  
      │   ├── campaign_processor.py#  
      │   └── database_operations.py#  
      ├── gmail/# Gmail automation module  
      │   ├── main.py#  
      │   ├── browser_automation.py#  
      │   ├── email_operations.py#  
      │   └── ai_integration.py#  
      ├── saved_results/# Created automatically  
      ├── profiles/# Chrome profiles (created automatically)  
      ├── cookies/# Saved cookies (created automatically)  
      └── import_data/# CSV import directory (create if needed)

      

Settings.txt Configuration

The settings.txt file is the heart of the system configuration. Every option controls specific behavior.

API Configuration Settings

API-Token

Purpose: Your API authentication token

Format: API-Token: your-token-here

Required: Yes

Details: Without this poop, no data collection is possible. Get your token from the dashboard.

API-Total-Threads

Purpose: Number of concurrent threads for API requests when using "all" mode

Format: API-Total-Threads: 3 or API-Total-Threads: None

Default: 3

Range: 1-9 threads

Details: Higher thread counts speed up data collection but may hit rate limits. Use 1-2 for stable connections, 3-5 for good connections, 6-9 only if you have excellent bandwidth.

Rate Limiting: Using too many threads may trigger API rate limits, causing 429 errors.

API-Ignore-Hashed-PW

Purpose: Skip password hashes (20+ characters) during data collection

Format: API-Ignore-Hashed-PW: True

Default: False

Why use it: Hashed passwords are useless for most purposes and take up database space. Enable this to save storage and processing time.

Proxy Configuration (API)

Use-Proxy-For-API

Purpose: Route API requests through a proxy server

Format: Use-Proxy-For-API: True

When to use: If the API is blocked in your region or you need to hide your IP

API-Proxy-Host & API-Proxy-Port

Purpose: Proxy server connection details

Format:

              API-Proxy-Host: 192.168.1.100
              API-Proxy-Port: 8080
            

API-Proxy-Authentication

Purpose: Enable username/password authentication for proxy

Format: API-Proxy-Authentication: True

API-Proxy-Username & API-Proxy-Password

Format:

              API-Proxy-Username: myuser
              API-Proxy-Password: mypass123
            

The script tests proxy connectivity before use, showing connection status (required for API).

Gmail Account Settings

Username & Password

Purpose: Gmail account credentials for automation

Format:

              Username: youremail@gmail.com
              Password: yourpassword
            

Security: Use an app-specific password if 2FA is enabled. Never use your main Gmail account.

Headless

Purpose: Run Chrome in background without GUI

Format: Headless: False

When True: No browser window appears, faster execution

When False: See browser actions, useful for debugging

Incognito

Purpose: Use incognito mode (no saved cookies/profiles)

Format: Incognito: False

Impact: When True, you'll need to log in every time. When False, login sessions persist.

Email Campaign Settings

Max-Daily-Send

Purpose: Maximum emails to send in one session

Format: Max-Daily-Send: 50

Recommended: 20-50 for new accounts, 50-100 for established accounts

Warning: Sending too many emails triggers spam filters

Gmail-Send-Delay

Purpose: Random delay between emails (seconds)

Format: Gmail-Send-Delay: 60-300

How it works: Randomly waits between min-max seconds

Example scenarios:

30-60: Fast sending, higher risk
60-300: Balanced approach
300-600: Very safe, slow

Read-Random-Emails

Purpose: Read emails to appear more human-like

Format: Read-Random-Emails: True

Behavior: Opens and "reads" unread emails between sends

Read-Random-Amount

Purpose: How many emails to read

Format: Read-Random-Amount: 1-3

Options:

1-3: Read 1 to 3 random emails
5: Always read exactly 5
2-5: Read between 2 and 5

Email Templates

Base Template (Mail-Subject & Mail-Body)

              Mail-Subject: Hello {First_Name}!
              Mail-Body: Hi {First_Name},\n\nI hope this email finds you well.\n\nBest regards
            

Placeholder: {First_Name} gets replaced with recipient's name

Line breaks: Use \n for new lines

Additional Templates (1-3)

You can define up to 3 additional templates:

              Mail-Subject-1: Quick question
              Mail-Body-1: Hey there,\n\nJust wanted to reach out...
              Mail-Subject-2: Following up
              Mail-Body-2: Hi,\n\nI wanted to follow up on...
              Mail-Subject-3: Important update
              Mail-Body-3: Hello,\n\nI have an important update...
            

Usage: Templates are rotated randomly if multiple exist. Set any to "None" to disable.

AI Instructions for Email Generation

AIMLAPI-Token

Purpose: API key for AI email generation

Required for: Automatic email variation generation

AIML-AI-Model

Purpose: Which AI model to use

Options:

gpt-3.5-turbo: Fast, cheap, good quality
gpt-4o: Best quality, more expensive
gpt-4o-mini: Balanced option
claude-3-5-sonnet-20241022: Creative writing
deepseek-chat: Alternative option

AI-Instructions

Purpose: Base instructions for all AI operations

Example:

              AI-Instructions: You are a professional email writer. Create natural, engaging emails.
            

AI-Instructions-Generic

Purpose: Instructions for emails WITHOUT first names

Critical: Must NOT include {First_Name} placeholder

Example:

              AI-Instructions-Generic: Write 15 professional emails without using any names. Start with generic greetings like "Hello" or "Hi there". Make each email unique and engaging.
            

AI-Instructions-Custom

Purpose: Instructions for emails WITH first names

Critical: MUST include {First_Name} placeholder

Example:

              AI-Instructions-Custom: Write 15 personalized emails using {First_Name} placeholder. Start with "Hi {First_Name}" or "Hello {First_Name}". Make them warm and personal.
            

Critical: If AI-Instructions-Custom doesn't produce emails with {First_Name}, personalization will fail!

Campaign Targeting Keywords

Campaign-Targeting-Keywords

Purpose: Keywords to INCLUDE in campaigns

Format: Campaign-Targeting-Keywords: manager, director, ceo, owner

How it works: Only records containing these keywords are added to campaigns

Set to None: Adds all records (no filtering)

API-Blocked-Words

Purpose: Keywords to EXCLUDE from campaigns

Format: API-Blocked-Words: spam, test, demo, fake

Priority: Blocked words override approved words

Use case: Filter out unwanted records before approval check

Tip: Use blocking for broad exclusions (like "test") and approval for specific inclusions (like job titles).

Date Filtering Settings

Search-By-Year

Purpose: Filter results by year range in source descriptions

Format: Search-By-Year: True

Search-By-Year-Start & Search-By-Year-Stop

Purpose: Define year range for filtering

Format:

              Search-By-Year-Start: 2020
              Search-By-Year-Stop: 2024
            

How it works: Looks for years in database leak descriptions

Example: "LinkedIn Database 2023" would match if 2023 is in range

Include-Undated-Results

Purpose: What to do with results that have no year

Format: Include-Undated-Results: True

True: Include results without years

False: Only include results with years in range

Bounce Detection Settings

Gmail-Bounce-Check

Purpose: Enable automatic bounce email detection

Format: Gmail-Bounce-Check: True

How it works: Scans inbox for delivery failure notifications

Gmail-Bounce-Check-Frequency

Purpose: How many days back to check for bounces

Format: Gmail-Bounce-Check-Frequency: 1

Range: 1-30 days

Recommendation: 1-3 days for active campaigns

Bounce detection automatically removes failed emails from future sends and deletes bounce notifications.

ZeroBounce Email Validation

ZeroBounce-API-Key

Purpose: API key for email validation service

Cost: ~$0.008 per email validation

ZeroBounce-Enable-Sanitization

Purpose: Validate emails before sending

Format: ZeroBounce-Enable-Sanitization: True

Benefits: Prevents sending to invalid emails, protects sender reputation

ZeroBounce-Revalidate-Days

Purpose: How long validation results remain valid

Format: ZeroBounce-Revalidate-Days: 60

Details: Cached results save API credits

Validation Results:

Valid: Email exists and can receive mail
Invalid: Email doesn't exist or has errors
Catch-all: Domain accepts all emails (risky)
Spamtrap: Known spam trap address (don't send!)
Abuse: Known to report spam
Do-not-mail: Suppression list

Batch Search Configuration

API-Batch-Search

Purpose: Enable automatic batch searching

Format: API-Batch-Search: True

API-Batch-Search-Targets

Purpose: List of search queries to run automatically

Format: API-Batch-Search-Targets: john smith | jane doe | manager london

Separator: Use pipe (|) character

API-Batch-Search-Total

Purpose: Records to collect per search

Format: API-Batch-Search-Total: 100 or * for all

Complete Workflow

Configure settings.txt

Set up all required configurations including API tokens, proxy settings, and email templates.

Run main.py

Execute python main.py to start the main menu.

Collect Data (Option 'y')

Query the API for data based on your search terms. Data is saved to main_master.db and text files.

Build List (Option 'y')

Filter collected data using keywords, create targeted campaigns, validate emails if configured.

Run Gmail Script (Option 'y')

Automate email sending through Gmail with AI-generated variations and bounce detection.

Data Collection Module

Search Query Input

When prompted "Enter search query:", you can enter:

Names: "john smith", "jane doe"
Emails: "user@domain.com"
Phone numbers: "+1234567890"
Keywords: "manager", "london", "developer"
Combinations: "john manager london"

Query Complexity & Cost

1 word queries

Complexity: 1

Cost Factor: Lowest

Example: "john"

2 word queries

Complexity: 5

Cost Factor: Medium

Example: "john smith"

3 word queries

Complexity: 16

Cost Factor: High

Example: "john smith london"

4+ word queries

Complexity: 40

Cost Factor: Very High

Example: "john smith manager london"

Record Limit Options

When asked "How many records do you want to save?":

Number (e.g., "100"): Collects exactly 100 records
"all": Activates multi-threaded mode, collects until no more data

Warning: Using "all" can collect massive amounts of data. Monitor your API credits!

Multi-Threading Mode

Activated when selecting "all" records:

Uses number of threads from API-Total-Threads
Much faster data collection
Higher API credit consumption
Automatic retry on failures
Stops when no new data for 5 consecutive attempts

Data Output

Database Storage

All data saved to main_master.db with automatic deduplication.

Text Files

Human-readable format in saved_results/Query_Name/

Deduplication

Automatic removal of duplicate records across all sources.

Year Filtering During Collection

If Search-By-Year: True, the system:

Scans each data source description for years
Only includes sources with years in your range
Optionally includes undated sources based on settings
Shows statistics: accepted vs filtered records

List Builder Module

Campaign Creation Workflow

The system uses a multi-stage filtering approach to create highly targeted campaigns from collected data:

1. Data Source Selection

Select which queries to include from main_master.db. View total records, email counts, and SMS counts for each source. Combine multiple sources with "1,2,3" syntax.

2. Campaign Naming

Choose descriptive names like "Crypto CEOs 2024" or "Luxury Real Estate Brokers". Names must be unique among active campaigns.

3. Filtering & Targeting

Apply sophisticated filters using keywords, regex, column selection, and validation to create precision-targeted lists.

Campaign Creation Options

Creating a New Campaign

Select Data Sources: Choose which queries to include (1,2,3 or 1 for single)
Name Your Campaign: Descriptive name like "UK Managers June 2024"
Choose Targeting Options: Multiple filtering methods available

Working with Existing Campaigns

View all campaigns with email/phone counts
Select by number (1, 2, 3, etc.)
Delete campaigns with "DELETE" command
Campaigns persist across sessions

Targeting Options Menu

The system provides 8 powerful targeting options that can be combined for precise filtering:

1. Import from CSV

Add external email lists. Place CSV files in import_data/ folder.

Required columns: email (others optional: name, phone, city)

Duplicates: Automatically skipped

2. Query Surname Columns

Targets: full_name, first_name, last_name fields only

Use for: Name-based campaigns

Combinable: With option 3 for name+email targeting

3. Query Email Columns

Targets: email, email1-5 fields only

Use for: Email pattern matching (e.g., @company.com)

Special: Uses email-specific pattern matching

4. Manual Column Selection

Choose specific columns from a numbered list

Flexibility: Target any combination of fields

Shortcut: "100" selects name/email/social columns

5. Block Words

Exclude records containing specific keywords

Example: Block "test", "demo", "sample"

Priority: Blocks override approvals

6. Query JSON String

Search the entire raw record as text

Use for: Finding data in unmapped fields

Processes: original_record_json column

7. No Filtering

Add ALL records to campaign

Warning: Can create huge campaigns!

Bypasses: All keyword filtering

8. Regex Search

Use regular expressions for complex pattern matching

Example: ^[A-Z]{2}\d{4}$ for ID patterns

Testing: Test patterns before applying

Phase 1: Blocking Keywords (Applied First)

Purpose

Exclude unwanted records before approval phase. Higher priority than approvals - blocks always win.

Common Examples

"noreply", "no-reply", "test", "demo", "spam", "fake", "student", "intern", "assistant", ".gov", "police", "agent", "officer", "detective", "donotreply", "do-not-reply"

Settings.txt

Configure as API-Blocked-Words: word1, word2, word3

Phase 2: Approval Keywords (Applied to Non-Blocked)

Purpose

Only include records containing these keywords. Applied after blocking phase.

Common Examples

"manager", "director", "ceo", "founder", "president", "owner"

Settings.txt

Configure as Campaign-Targeting-Keywords: word1, word2

Keyword Matching Options

Exact Match vs Partial Match

Exact Match (y) - "manager"

✓ Will Match: "manager"

✗ Won't Match: "managers", "management"

Best for: Precise titles, specific terms

Partial Match (n) - "manager"

✓ Will Match: "manager", "managers", "management"

✗ Won't Match: "manage"

Best for: Catching variations

Exact Match (y) - "smith"

✓ Will Match: "smith"

✗ Won't Match: "John Smith", "blacksmith"

Best for: Surnames only

Partial Match (n) - "smith"

✓ Will Match: "smith", "John Smith", "blacksmith"

✗ Won't Match: "smit"

Best for: Name variations

Special Email Pattern Matching

Email columns use special pattern: keyword(?:[^a-zA-Z]|$)
This matches the keyword followed by a non-letter or end of string.
Example: "john" matches "john@company.com" and "john123@company.com" but NOT "johnson@company.com"

Special Column Selection Options

Option 100: Quick select name/email/social columns (full_name, first_name, last_name, email, nickname, etc.)
Option *: Select all columns
Multiple selection: "1,5,8,12" to select specific columns
Column counts: Each column shows record count to help prioritize

Additional Filtering Options

Email Filter

Only includes records with valid email addresses. Checks for @ symbol and proper format. Essential for email campaigns.

SMS Filter

Only includes records with phone numbers. Validates minimum 7 digits. Use for SMS campaigns.

Year Filtering

Filter by data source year. Set Search-By-Year: True in settings. Control date ranges.

Campaign Processing Pipeline

Source Selection: Choose data sources from main_master.db
Option Selection: Pick targeting options (1-8)
Column Selection: Choose which fields to search
Blocking Phase: Remove unwanted records
Approval Phase: Select matching records
Email/SMS Filtering: Apply contact filters
Deduplication: One record per email address
Email Validation: ZeroBounce verification (optional)
Name Standardization: AI-powered name cleaning
Variation Generation: Create email templates

Deduplication Process

After filtering, the system ensures data quality:

Groups records by email (case-insensitive)
Keeps the "best" record based on name completeness score
Prioritizes records with: full_name + first_name + last_name
Removes all duplicates to ensure one record per email
Shows statistics: total duplicates removed

Email Validation Process

If ZeroBounce is enabled, the system validates emails before adding to campaigns:

Checks for cached validation results (saves credits)
Validates new emails in real-time
Shows validation statistics and costs
Only adds "valid" status emails to campaign
Skips: invalid, spamtrap, abuse, do_not_mail
Saves results for future use (configurable expiry)

Credit Management: System stops validation when credits run out, only adding validated emails. Purchase credits at zerobounce.net

Name Standardization

AI-powered name cleaning includes:

Parsing full names into first/middle/last components
Fixing "LASTNAME, FIRSTNAME" format to "FIRSTNAME LASTNAME"
Removing numbers and special characters (Mike09876 → Mike)
Proper capitalization (mcdonald → McDonald, o'connor → O'Connor)
Handling titles (Dr., Mr., Jr., III, etc.)
Removing emoji and unicode symbols
Deduplicating repeated names

Email Variation Generation

After campaign creation, the system generates unique email templates:

With Names: Uses AI-Instructions-Custom (must have {First_Name})
Without Names: Uses AI-Instructions-Generic (no placeholders)
Generates extras to ensure sufficient variations
Stores in database for reuse across campaigns
Shows sample variations during generation
Automatic cleanup of overused variations (>3 uses)

Real-World Examples: Domain Broker Campaigns

These examples show how domain brokers can use the system to find end-users for premium .com domains:

Example 1: Finding End-Users for Crypto/Fintech Domains

Target Domains

Crypto.com, DeFi.com, BlockchainBank.com, CryptoExchange.com

Search Strategy

              Search queries: "cryptocurrency", "bitcoin", "blockchain", "crypto exchange"
              Options: 3,4,5 (email columns + manual selection + block words)
              Columns: job_title, company, work, email
              Approval keywords: ceo, founder, president, cto, blockchain, cryptocurrency, bitcoin, defi
              Block keywords: student, intern, journalist, blogger, enthusiast
              Exact match: No (to catch variations)
              Email filter: Yes
            

Expected Results

Creates a campaign of C-level executives and founders in the cryptocurrency/blockchain space, excluding hobbyists and media personnel.

Example 2: Targeting Real Estate Professionals for Premium Property Domains

Target Domains

Homes.com, LuxuryEstates.com, PremiumProperties.com, RealEstate.com

Search Strategy

              Search queries: "real estate", "realtor", "property", "broker"
              Options: 2,3,5 (surname + email columns + block words)
              Approval keywords: broker, realtor, realty, properties, estate, luxury, premium
              Block keywords: assistant, secretary, rental, apartment, student
              Regex pattern (Option 8): (luxury|premium|elite).*(real.*estate|properties|realty)
              Email filter: Yes
            

Expected Results

Identifies high-end real estate brokers and luxury property firms who would value premium real estate domains.

Example 3: Insurance Industry for Insurance.com Category Domains

Target Domains

Insurance.com, AutoInsurance.com, LifeInsurance.com, HealthInsurance.com

Search Strategy

              Search queries: "insurance", "underwriter", "insurance ceo"
              Options: 3,5,6 (email columns + block words + JSON search)
              Approval keywords: insurance, underwriter, actuary, claims, policy, insurtech
              Block keywords: agent, sales, customer, support, claim, adjuster
              Email pattern matching: Yes
              Target domains: @[major insurance companies].com
            

Expected Results

Filters for decision-makers at insurance companies, excluding front-line agents and support staff.

Example 4: Gaming Industry for Games.com or Casino.com Types

Target Domains

Games.com, Casino.com, Betting.com, OnlinePoker.com, Sportsbook.com

Search Strategy

              Search queries: "gaming executive", "casino", "igaming", "online gaming"
              Options: 4,5 (manual columns + block words)
              Selected columns: company, job_title, email, work
              Approval keywords: gaming, casino, igaming, betting, sportsbook, gambling, ceo, cto, vp
              Block keywords: player, user, support, moderator, tester, affiliate
              Exact match: No
            

Expected Results

Targets gaming industry executives and decision-makers, excluding players and support staff.

Example 5: Healthcare Sector for Medical Domain Names

Target Domains

Doctor.com, Medical.com, Healthcare.com, Telehealth.com, Hospital.com

Search Strategy

              Search queries: "healthcare ceo", "medical director", "hospital administrator"
              Options: 3,4,5,8 (email + manual + blocks + regex)
              Columns: job_title, company, work_description
              Regex pattern: (chief|director|president|vp).*(medical|healthcare|hospital|clinic)
              Approval keywords: healthcare, medical, hospital, clinic, pharma, biotech
              Block keywords: patient, nurse, assistant, student, resident
              Year filter: 2020-2024 (recent data only)
            

Expected Results

Identifies healthcare executives with purchasing authority for premium medical domains.

Example 6: E-commerce Leaders for Premium Commerce Domains

Target Domains

Shop.com, Store.com, Marketplace.com, Buy.com, Sell.com

Search Strategy

              Search queries: "ecommerce", "online retail", "marketplace"
              Options: 3,5 (email columns + block words)
              Email domains focus: @shopify, @amazon, @ebay, @etsy, @alibaba
              Approval keywords: ecommerce, marketplace, retail, shopping, store, commerce
              Block keywords: customer, review, seller, vendor, affiliate, dropship
              Email pattern: Yes (to catch "john@shopify" not "johnson@shopify")
            

Expected Results

Targets e-commerce platform executives who understand the value of premium commerce domains.

Example 7: Travel Industry for Travel.com Category

Target Domains

Travel.com, Hotels.com, Flights.com, Vacation.com, Cruise.com

Search Strategy

              Search queries: "travel agency", "hotel chain", "airline executive"
              Options: 2,3,4,5 (all name/email columns + blocks)
              Approval keywords: travel, hotel, airline, tourism, hospitality, resort, cruise
              Block keywords: agent, desk, support, booking, reservation, concierge
              Company size filter: Use manual selection to include company_size field
              Target: Companies with 100+ employees only
            

Expected Results

Finds decision-makers at major travel companies with budgets for premium domain acquisitions.

Example 8: Legal Sector for Law-Related Domains

Target Domains

Lawyer.com, Law.com, Attorney.com, LegalAdvice.com, LawFirm.com

Search Strategy

              Search queries: "law firm partner", "attorney", "legal counsel"
              Options: 4,5,8 (manual + blocks + regex)
              Columns: job_title, company, email
              Regex: (partner|managing|senior).*(attorney|counsel|law)
              Approval keywords: attorney, lawyer, counsel, legal, law, firm, partner
              Block keywords: paralegal, clerk, assistant, student, intern
              Email validation: Enable ZeroBounce to ensure deliverability
            

Expected Results

Creates campaigns for law firm partners with authority to invest in premium legal domains.

Example 9: Finance Executives for Money.com Type Domains

Target Domains

Money.com, Invest.com, Wealth.com, Trading.com, Finance.com

Search Strategy

              Search queries: "investment banker", "hedge fund", "private equity"
              Options: 3,5,6 (email + blocks + JSON search)
              Approval keywords: investment, equity, capital, fund, wealth, asset, portfolio
              Block keywords: analyst, associate, junior, intern, assistant
              JSON search: Include to catch titles in unstructured data
              Email domains: Focus on @goldmansachs, @jpmorgan, @blackrock, etc.
            

Expected Results

Targets high-level finance executives who understand domain value as digital assets.

Example 10: Tech Startups for Innovative Domain Names

Target Domains

AI.com, Cloud.com, Data.com, App.com, Tech.com, or vertical-specific domains

Search Strategy

              Search queries: "startup founder", "tech ceo", "entrepreneur"
              Options: 2,3,5 (names + emails + blocks)
              Approval keywords: founder, ceo, cto, startup, tech, ai, saas, cloud
              Block keywords: employee, developer, engineer, designer, marketing
              Year filter: 2022-2024 (recent startups only)
              Special focus: Look for "stealth", "seed", "series a" in company descriptions
            

Expected Results

Identifies startup founders who might pay premium for perfect brand domain matches.

Example 11: Influencers and Content Creators for Personal Brand Domains

Target Domains

FirstnameLastname.com, BrandName.com, Lifestyle.com, Beauty.com, Fitness.com

Search Strategy

              Search queries: "influencer", "content creator", "youtuber", "instagram"
              Options: 2,3,4,5,6 (names + emails + manual + blocks + JSON)
              Columns: full_name, username, instagram_id, facebook_id, email
              Approval keywords: influencer, creator, youtuber, blogger, vlogger, coach, guru
              Block keywords: fan, follower, assistant, manager, agency, pr, marketing
              JSON search: Yes (to find follower counts, verified status in unmapped fields)
              Regex (Option 8): (\d{6,})\s*(followers|subscribers) (find 100k+ following)
              Special: Look for verified badges, high engagement metrics
            

Expected Results

Identifies high-profile influencers and content creators who need personal brand domains. Perfect for FirstnameLastname.com or niche domains matching their content vertical.

Pro Tips

Focus on influencers with 100k+ followers (use regex to find)
Target those without .com domains already (check website fields)
Look for "verified" status in JSON data
Prioritize business emails over personal (indicates monetization)

Pro Tips for Domain Brokers

Best Practices:

Use Year Filtering: Focus on recent data (2022-2024) as older contacts may be outdated
Enable ZeroBounce: Validate emails before outreach to protect sender reputation
Leverage Regex: Create patterns to find specific title + company combinations
Email Pattern Matching: Ensures you get "john@company" not "johnson@company"
Multiple Campaigns: Create separate campaigns for each domain category/vertical
Block Wisely: Exclude job seekers, students, and low-level employees
JSON Search: Catches data in unmapped fields like LinkedIn URLs or bios
Name Standardization: AI cleans names for professional outreach
Test First: Run small test campaigns before scaling up

Gmail Automation Module

Login Process

Profile Management

Creates persistent Chrome profiles per email account. Stores cookies for faster login.

Automated Login

Handles email/password entry with human-like typing. Manages 2FA challenges if needed.

Cookie Persistence

Saves session cookies to skip login on future runs (unless incognito mode).

Email Reading Behavior

Between sending emails, the bot:

Checks Primary inbox for unread emails
Falls back to Promotions if Primary is empty
Opens and "reads" emails for 30-60 seconds (Primary) or 8-12 seconds (Promotions)
Randomly scrolls through content
Detects and processes bounce notifications
Marks non-bounce emails as unread (except in Promotions)

Email Sending Process

1. Recipient Selection

Loads unsent recipients from campaign
Checks for multiple email addresses per person
Skips bounced emails from current session
Validates email format

2. Compose Window

Waits 3-6 seconds before clicking compose
Handles popup dismissal
Types recipient email
Waits 3-15 seconds before subject

3. Email Variation Selection

The bot intelligently selects variations based on recipient data:

Has first name: Uses variation with {First_Name} placeholder
No first name: Uses generic variation without placeholder

4. Typing Behavior

Human-like typing speed (~90 WPM)
Makes typos every 30-50 words
Pauses to "correct" typos
Variable delays between characters

5. Sending Methods

Tries multiple methods in order:

Ctrl+Enter keyboard shortcut
Click Send button
Tab+Enter as fallback

Bounce Detection System

Automatic Detection

Identifies bounces by keywords:

"mail delivery failed"
"550 5.1.1"
"user unknown"
"mailbox unavailable"
"does not exist"

Bounce Processing

Extracts recipient email from bounce message
Marks as bounced in campaign database
Adds to session bounce list
Deletes the bounce notification
Skips this email in future sends

Final Bounce Check

After campaign completion:

Searches all emails from last N days
Processes each for bounce detection
Updates campaign database
Shows summary statistics

Session Statistics

Tracks and displays:

Start/end times
Total emails sent
Emails read
Bounces detected
Time elapsed

Database Structure

main_master.db

Central repository for all collected data.

Table: records_master

        PRIMARY KEY: id
        UNIQUE KEY: record_hash (prevents duplicates)
        Core Fields:

        - source_name: Which leak/database
        - source_description: Leak details
        - source_year: Extracted year (if date filtering enabled)
        - query_used: Search term that found this record
        - date_added: When collected
        Identity Fields:
        - full_name, first_name, middle_name, last_name
        - username, nickname, suffix
        Contact Fields:
        - email, email1-5
        - phone, phone1-6, phone_home, phone_mobile
        Location Fields:
        - address, street, city, state, country, zip_code
        - latitude, longitude, continent
        Personal Fields:
        - gender, age, birth_date, relationship_status
        - education, language, hobby, interested_in
        Employment Fields:
        - job_title, work, company, industry, income
        Social Media:
        - facebook_id, instagram_id, linkedin_url, telegram_id
        Technical Fields:
        - ip_address, user_agent, operating_system
        Authentication:
        - password, password_hash, salt
        Special Fields:
        - additional_data: JSON for unmapped fields
        - add_to_list: 'yes'/'no' for filtering
      

campaigns_master.db

Manages all email campaigns and variations.

Table: campaigns

        - campaign_id: Primary key
        - campaign_name: User-defined name
        - working_directory: Associated data source
        - creation_date: When created
        - total_records: Record count
        - emails_sent: Tracking
        - active: Boolean (soft delete)
      

Table: campaign_data

        Core Fields:
        - id, campaign_id (foreign key)
        - email, phone, full_name, first_name, last_name
        - city, state, country
        Email Tracking:
        - sender_email: Which account sent
        - receiver_email: Recipient
        - email_subject: What was sent
        - email_body: Content
        - time_sent: Timestamp
        - total_sent: Count (handles resends)
        - bounced: 'yes'/NULL
        Status Fields:
        - in_use: Prevents concurrent sending
        - original_record_id: Link to main_master.db
      

Table: email_variations

        - id: Primary key
        - email_subject, email_body: Content
        - record_hash: Deduplication
        - has_placeholder: Boolean (contains {First_Name})
        - used_count: Usage tracking
        - time_generated, time_last_used: Timestamps
      

Table: email_sanitization

        - record_id: Link to campaign_data
        - email: Validated address
        - status: valid/invalid/catch-all/etc
        - sub_status: Detailed reason
        - score: Quality score
        - sanitization_date: When checked
        - zerobounce_credits_used: Cost tracking
      

master_stats.db

Global email tracking across all campaigns.

Table: campaign_stats

Mirrors campaign_data but aggregates all sends globally.

Table: bounce_tracking

        - message_hash: Unique email identifier
        - processed_date: When checked
        - is_bounce: Boolean result
      

Individual Campaign Databases

Each campaign can also export to:

saved_results/Campaign_Name/Campaign_Name_stats.db
Contains campaign-specific statistics

Email Variations System

How Email Variations Work

The system generates unique email variations to avoid sending identical emails:

Personalized Variations

Contains {First_Name} placeholder

Used when recipient has a first name

Example: "Hi {First_Name}, I wanted to reach out..."

Generic Variations

No name placeholders

Used when recipient lacks first name

Example: "Hello, I wanted to reach out..."

Generation Process

Count Recipients: System counts how many have/lack first names
Check Existing: Looks for unused variations in database
Generate New: Creates more if needed using AI
Validate: Ensures personalized have placeholder, generic don't
Store: Saves to database for future use

AI Generation Settings

Critical: Your AI instructions MUST produce the correct variation type:

AI-Instructions-Custom: MUST include {First_Name} in outputs
AI-Instructions-Generic: Must NOT include {First_Name}

Example AI-Instructions-Custom

        Write 15 unique email variations for cold outreach. 
        IMPORTANT: Every email MUST use {First_Name} placeholder at least once.
        Start emails with greetings like "Hi {First_Name}" or "Hello {First_Name}".
        Make them professional but friendly. Include:
        - A personalized greeting with {First_Name}
        - A value proposition
        - A soft call to action
        Return as JSON array with 'subject' and 'body' fields.
        Use \n for line breaks in body.
      

Example AI-Instructions-Generic

        Write 15 unique email variations for cold outreach.
        IMPORTANT: Do NOT use any names or name placeholders.
        Start with generic greetings like "Hello" or "Hi there".
        Make them professional but friendly. Include:
        - A generic but warm greeting
        - A value proposition  
        - A soft call to action
        Return as JSON array with 'subject' and 'body' fields.
        Use \n for line breaks in body.
      

Email Variation Usage Logic

Recipient Has First Name: Yes

Example: "John"

Variation Type: Personalized with {First_Name}

Result: "Hi John, I wanted to..."

Recipient Has First Name: No

Example: empty/null

Variation Type: Generic without placeholder

Result: "Hello, I wanted to..."

Fallback Scenario

Situation: Has name but no personalized variations available

Variation Type: Falls back to generic

Result: "Hello, I wanted to..."

Variation Management

Used Count: Tracks how many times each variation was sent
Auto-cleanup: Variations used >3 times are deleted
Deduplication: Prevents identical variations via hash
Batch Generation: Creates 15 at a time to minimize API calls

Tip: Pre-generate variations by running List Builder without sending emails. This ensures variations are ready when you start emailing.

Common Usage Scenarios

Scenario 1: Cold Email Campaign to Managers

Goal

Email managers in London about your service

Settings Configuration

              Search-By-Year: True
              Search-By-Year-Start: 2020
              Search-By-Year-Stop: 2024
              Include-Undated-Results: False
              Campaign-Targeting-Keywords: manager, director, head, chief
              API-Blocked-Words: test, demo, student, junior
              ZeroBounce-Enable-Sanitization: True
              Max-Daily-Send: 30
              Gmail-Send-Delay: 120-300
            

Step-by-Step Process

Data Collection:
- Search: "manager london"
- Limit: "all" (multi-threaded)
- Let it run until no new data
List Building:
- Create new campaign: "London Managers 2024"
- Options: 3,4,5 (email filter + manual columns + block words)
- Select columns: job_title, work, company
- Approval keywords: manager, director
- Exact match: No (to catch variations)
Email Automation:
- System validates emails via ZeroBounce
- Generates personalized variations
- Sends 30 emails with 2-5 minute delays
- Reads random emails between sends
- Detects and removes bounces

Expected Results

Filtered dataset of managers only
Valid email addresses only
Personalized emails using first names
Bounce rate under 5%
Natural sending pattern

Scenario 2: Targeted Outreach to Specific Companies

Goal

Contact employees of specific companies

Settings Configuration

              Campaign-Targeting-Keywords: microsoft, google, amazon, apple
              API-Blocked-Words: contractor, intern, former, ex-
              Use-Proxy-For-API: True
              API-Proxy-Host: your.proxy.com
              API-Proxy-Port: 8080
              Gmail-Bounce-Check: True
              Gmail-Bounce-Check-Frequency: 1
            

Data Collection Strategy

Search 1: "@microsoft.com"
Search 2: "@google.com"
Search 3: "microsoft employee"
Collect 500 records each

List Building Approach

Select option 3 (email columns only)
Approval keywords: microsoft, google, amazon
Use exact match: No
Email filter: Yes (only records with emails)

Special Considerations

Corporate emails may have stricter spam filters
Use longer delays (300-600 seconds)
Keep daily sends low (20-30)
Monitor bounce rate closely

Scenario 3: Geographic Targeting Campaign

Goal

Reach people in specific cities/regions

Search Queries

"new york" (broad search)
"NYC 10001" (ZIP code)
"manhattan broker"
"queens restaurant"

List Building Strategy

Options: 4,5 (manual columns + block words)
Select columns: city, state, zip_code, address
Approval keywords: york, manhattan, queens, brooklyn
Block words: jersey, connecticut (neighboring states)

Email Personalization

Enhance AI instructions with location context:

              AI-Instructions-Custom: Write emails for {First_Name} living in New York. 
              Reference local topics like NYC traffic, subway, or weather.
              Make the email feel locally relevant.
            

Scenario 4: Industry-Specific B2B Campaign

Goal

Target specific industries or job roles

Search Strategy

              Searches:
              - "real estate agent"
              - "realtor license"
              - "property manager"
              - "real estate broker"
            

Advanced Filtering

Use option 8 (regex search)
Pattern: (real\s*estate|realtor|property|broker)
Target columns: job_title, work, company

Industry-Specific AI Instructions

              AI-Instructions-Custom: Write emails for real estate professionals named {First_Name}.
              Reference market trends, property values, or client acquisition.
              Use industry terminology appropriately.
            

Campaign Optimization

Send during business hours
Avoid weekends and holidays
Use professional subject lines
Include value propositions relevant to real estate

Scenario 5: Re-engagement Campaign

Goal

Re-contact previous campaign recipients who didn't bounce

Process

Export Previous Campaign:
- Access campaigns_master.db
- Export non-bounced emails to CSV
Create New Campaign:
- Option 1: Import from CSV
- Place file in import_data/
- System skips duplicates automatically
Different Email Templates:
AI-Instructions-Custom: Write follow-up emails for {First_Name}. Reference that you've reached out before. Provide new information or a different angle. Be respectful of their time.

Best Practices

Wait at least 2 weeks between campaigns
Change email subject significantly
Provide new value, don't just repeat
Honor any unsubscribe requests

Scenario 6: Multi-Language Campaign

Goal

Send emails in different languages based on location

Data Collection

Search by country: "spain", "mexico", "argentina"
Filter by language field if available

Campaign Setup

Create separate campaigns per language
Campaign 1: "Spanish Speakers 2024"
Campaign 2: "English Speakers 2024"

Language-Specific AI Instructions

              AI-Instructions-Custom: Write professional emails in Spanish for {First_Name}.
              Use formal Spanish business language.
              Include proper Spanish email etiquette.
            

Important Considerations

Gmail interface must be in English for automation
Email content can be any language
Test special characters (ñ, á, é, etc.)
Consider time zones for sending

Scenario 7: High-Volume Data Collection

Goal

Collect maximum data for future campaigns

Batch Search Configuration

              API-Batch-Search: True
              API-Batch-Search-Targets: john | mary | david | michael | sarah | jessica
              API-Batch-Search-Total: *
              API-Total-Threads: 5
              Search-By-Year: True
              Search-By-Year-Start: 2022
              Search-By-Year-Stop: 2024
            

Execution Strategy

Run overnight or during off-hours
Monitor API credit consumption
Use terminal clearing (automatic after 500 lines)
Check saved_results/ for text files

Resource Management

Each search creates separate folder
Database handles millions of records
Text files for human review
Automatic deduplication

Post-Collection

Don't try to create one massive campaign
Segment data into targeted campaigns
Use different approval keywords for each
Spread sending over multiple days

Scenario 8: Avoiding Spam Filters

Conservative Settings

              Max-Daily-Send: 20
              Gmail-Send-Delay: 300-600
              Read-Random-Emails: True
              Read-Random-Amount: 3-5
              Gmail-Bounce-Check: True
              Gmail-Bounce-Check-Frequency: 1
              ZeroBounce-Enable-Sanitization: True
            

Email Variation Strategy

Generate 100+ variations upfront
Ensure high uniqueness between emails
Avoid spam trigger words
Keep emails under 150 words

AI Instructions for Deliverability

              AI-Instructions-Custom: Write emails for {First_Name} that:
              - Are under 150 words
              - Sound natural and conversational
              - Avoid sales language and urgency
              - Don't use ALL CAPS or excessive punctuation
              - Include a clear but soft call-to-action
              - Feel like a genuine human wrote them
            

Sending Best Practices

Warm up new accounts: Start with 5-10 emails/day
Gradually increase: Add 5-10 more each week
Mix activities: Read emails, send replies
Use business hours: 9 AM - 5 PM recipient time
Skip weekends: Monday-Friday only
Monitor metrics: Stop if bounce rate >5%

Troubleshooting Guide

API Connection Issues

Error: "API request failed with status 504"

API server is overloaded
Reduce thread count to 1-2
Wait 3 minutes and retry
Check API status page

Error: "All proxy tests failed"

Verify proxy is running
Check proxy credentials
Test proxy with curl/browser first
Ensure proxy allows HTTPS
Try without authentication first

Error: "No more data available from API"

Normal when search exhausted
Try different search terms
Broaden search (fewer words)
Remove year restrictions

Gmail Automation Issues

Cannot Find Compose Button

Gmail interface may have changed
Try refreshing the page
Clear browser cache
Delete Chrome profile and re-login
Disable Gmail labs features

Login Failures

Enable "Less secure app access" (if available)
Use app-specific password with 2FA
Try incognito mode first
Complete CAPTCHA manually when prompted
Check for security alerts in account

Emails Not Sending

Check compose window actually closed
Verify recipient email format
Look for Gmail sending limits
Check spam folder for bounces
Reduce sending speed

High Bounce Rate

Enable ZeroBounce validation
Check data source quality
Filter older data sources
Verify email format thoroughly
Test with known-good emails first

Database Issues

Database Locked Errors

Close other programs accessing DB
Kill zombie processes: pkill -f sqlite3
Restart the script
Check file permissions

Duplicate Records

System prevents duplicates via hash
Check if filtering is too broad
Duplicates in text files are visual only
Database has unique constraints

Missing Columns

Script adds columns automatically
Check SQLite version (3.8+)
Verify write permissions
Try creating fresh campaign

Performance Issues

Slow Data Collection

Normal for single-threaded mode
Use "all" for multi-threading
Increase thread count (carefully)
Check network speed
Disable proxy if not needed

Terminal Freezing

Automatic clearing after 500 lines
Redirect output: python main.py > log.txt
Use headless mode for Gmail
Increase terminal buffer size

High Memory Usage

Process data in smaller batches
Limit records per search
Close Chrome between campaigns
Clear old email variations

Email Variation Issues

No Variations Available

Check AI-Instructions-Generic exists
Check AI-Instructions-Custom exists
Verify AIMLAPI-Token is valid
Look for generation errors in output
Manually check variations table

Wrong Variation Type Used

Verify Custom instructions include {First_Name}
Verify Generic instructions exclude {First_Name}
Check AI model following instructions
Review generated variations manually

AI Not Following Instructions

Make instructions more explicit
Try different AI model
Add examples to instructions
Reduce instruction complexity
Check for conflicting requirements

Common Error Messages

"No module named 'seleniumbase'"

Cause: Missing dependency

Solution: pip install seleniumbase

"API-Token not found"

Cause: Missing settings.txt entry

Solution: Add API-Token: your-key to settings.txt

"Chrome not reachable"

Cause: Chrome crashed or not installed

Solution: Install Chrome, kill zombie processes

"Permission denied"

Cause: File permission issue

Solution: chmod 755 main.py

"Out of credits"

Cause: ZeroBounce limit reached

Solution: Buy more credits or disable validation

"No campaigns found"

Cause: Haven't run List Builder yet

Solution: Create campaign with List Builder first