LeadHunter Documentation

Everything you need to install, configure, and use the LeadHunter lead generation and email marketing platform.

Overview

LeadHunter is a complete lead generation and email marketing system consisting of two main components:

Chrome Extension (Manifest V3) — The client-side scraping engine that extracts email leads from Google, Facebook, LinkedIn, X (Twitter), and Instagram.
Next.js Dashboard & API — The backend API for authentication, lead storage, email campaigns, template building, and email validation.

Installation

Backend Setup

Clone the repository and start the Next.js backend:

cd backend
npm install
npm run dev

The API and dashboard will be available at http://localhost:3000.

Docker Setup (Optional)

You can also run the entire stack with Docker Compose:

docker-compose up --build

Quick Start

Start the backend server with npm run dev
Install the Chrome extension (see below)
Register an account via the extension popup
Open the extension dashboard and configure your scraping criteria
Hit "Start Scraping" and watch the leads flow in

Installing the Chrome Extension

The Chrome extension is distributed as a zip file. Follow these steps:

Download leadhunter-extension.zip from the home page
Unzip the file to any directory on your computer
Open Chrome and navigate to chrome://extensions
Enable Developer mode using the toggle in the top-right corner
Click Load unpacked and select the unzipped extension folder

Tip: Make sure the backend server is running before you try to log in from the extension. The extension communicates with your local API at http://localhost:3000.

Click the LeadHunter icon in your Chrome toolbar to open the popup. If you don't have an account, click Register to create one with your email, username, and password. After registration, log in with your credentials. The extension stores your JWT tokens securely in Chrome's local storage.

Configuring Scraping

Open the extension dashboard by clicking Open Dashboard in the popup. Configure your search criteria:

Niche — The industry or topic (e.g., "digital marketing")
Professions — Target roles (e.g., "CEO", "Marketing Manager")
Locations — Geographic targets (e.g., "New York", "London")
Email Patterns — Domains to look for (e.g., "@gmail.com")
Platforms — Toggle Google, Facebook, LinkedIn, X, Instagram

Click Generate Search Terms to preview the combinatorial search queries, then click Start Scraping. You can pause, resume, or stop the scrape at any time.

Note: The extension uses your logged-in browser sessions for social platforms. Make sure you're logged into Facebook, LinkedIn, etc. for best results.

Managing Leads

As leads are scraped, they appear in the extension's Leads Library tab. You can filter by platform, email domain, or niche. Use the built-in export button to download your leads as a CSV file. Leads are automatically synced to the backend API for persistence.

Dashboard Overview

The web dashboard at /dashboard provides a comprehensive control center for managing your leads and email campaigns. It includes tabs for:

Leads — Browse, search, filter, and manage all collected leads
Email Builder — Visual drag-and-drop template editor
Campaigns — Create, schedule, and monitor email campaigns
Collections — Organize leads into named groups
Validation — Bulk verify email addresses
Settings — SMTP configuration and account preferences

Email Builder

The Elementor-style email builder lets you visually construct email templates using drag-and-drop blocks:

Header Block — Title, subtitle, background color, text alignment
Text Block — Rich HTML content with font size and color controls
Button Block — CTA button with customizable URL, color, and border radius
Image Block — Upload or link images with alt text
Footer Block — Company info, address, and unsubscribe link

Template Variables

Use dynamic placeholders in your templates to personalize each email:

{{firstName}}   — Recipient's first name
{{lastName}}    — Recipient's last name
{{email}}       — Recipient's email address
{{platform}}    — Source platform (Google, Facebook, etc.)
{{niche}}       — The niche/industry of the lead
{{company}}     — Company name (if available)

Spam Score Analysis

The builder includes a real-time spam score analyzer that checks your template against common spam filters. It flags trigger words, ALL CAPS subjects, excessive punctuation, and missing unsubscribe links. Aim for a score above 80 for optimal deliverability.

Email Campaigns

Create email jobs by selecting a template, choosing recipients (from leads or collections), and configuring sending options. Campaigns support per-domain throttling, send delays, and scheduling for future delivery. Monitor delivery status in real-time from the campaigns tab.

Collections

Collections let you organize leads into logical groups. Create a collection, then add leads manually or use filters. Collections can be used as recipient lists when creating email campaigns.

Email Validation

Validate email addresses before sending campaigns. LeadHunter integrates with Reacher (self-hosted) and ZeroBounce API to check:

Deliverability — Is the mailbox reachable?
Catch-all Detection — Does the domain accept all addresses?
Syntax Check — Is the email format valid?
Disposable Detection — Is it a throwaway email?

API — Authentication

All API routes are prefixed with /api. Authentication uses JWT tokens with access + refresh token flow.

POST/api/auth/register

Create a new user account. Body: { email, username, password }

POST/api/auth/login

POST/api/auth/refresh

Refresh an expired access token using a refresh token.

API — Leads

GET/api/leads

Retrieve all leads for the authenticated user. Supports query params for filtering by platform, niche, and validation status.

POST/api/leads

Create or bulk-insert new leads. Body: array of lead objects with email, name, platform, niche, etc.

DELETE/api/leads

Delete leads by ID or bulk delete all leads for the user.

API — Email Jobs

GET/api/email-jobs

List all email jobs (campaigns) for the user.

POST/api/email-jobs

Create a new email campaign with recipients, template, subject, and scheduling options.

API — Templates

GET/api/templates

Retrieve saved email templates for the user.

POST/api/templates

Save a new email template with blocks configuration.

API — Collections

GET/api/collections

List all lead collections for the user.

POST/api/collections

Create a new collection. Body: { name, description }

API — Validation

POST/api/email-validation

Validate a single email address or batch of emails via Reacher / ZeroBounce. Returns deliverability status, catch-all detection, and risk score.

Environment Variables

Configure these in your backend/.env file:

# MongoDB connection string
MONGODB_URI=mongodb://localhost:27017/leadhunter

# JWT Secrets
JWT_SECRET=your-jwt-secret-key
JWT_REFRESH_SECRET=your-jwt-refresh-secret-key

# SMTP Configuration
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASS=your-smtp-password

# Email Validation (optional)
VALIDATION_API_KEY=your-zerobounce-api-key
REACHER_API_URL=http://localhost:8080

Frequently Asked Questions

Do I need to keep the backend running for the extension to work?

Yes. The Chrome extension communicates with the backend API for authentication and lead storage. Make sure the Next.js server is running before using the extension.

Can I use this with a remote server instead of localhost?

Yes. Update the API base URL in the extension's configuration (popup settings or lib/api-client.js) to point to your deployed backend URL.

How many leads can I scrape at once?

There is no hard limit. However, the extension includes built-in rate limiting and randomized delays to avoid getting blocked by social platforms. For large-scale scraping, run over multiple sessions.

Is email validation free?

The Reacher integration (self-hosted) is free and included in the Docker Compose setup. ZeroBounce requires a separate API key and has its own pricing. You can use either or both.

What platforms are supported for scraping?

Google Search (SERP), Facebook, LinkedIn, X (Twitter), and Instagram. Each platform has a dedicated content script that extracts emails from profile pages and search results.

How does the spam score work?

The spam score analyzer checks your email template against a list of known spam trigger words, formatting issues (ALL CAPS, excessive punctuation), and best practices (presence of unsubscribe link). Each issue deducts points from a base score of 100.