📧 Bulk Email Verifier

Self-hosted bulk email verification — free forever. No paid APIs.

Syntax · MX records · live SMTP dialog · CSV export

---

Screenshots

See the portfolio demos page for project previews. Run locally and capture with demo data:

npm start
# Open http://localhost:5000 — use sample emails only

🏆 Why this project?

	Paid SaaS (Hunter, etc.)	This app
Cost	💸 Per email	✅ $0
Data privacy	Sent to third parties	✅ Stays on your PC
SMTP proof	Yes	✅ Yes (truemail-go / Reacher)
Bulk CSV	Yes	✅ Any column

---

✨ Features

• 🔍 Single verify — verify-email.org style checklist + SMTP server text
• 📂 Bulk CSV / XLSX — finds emails in any column
• ✅ Valid-only export — download clean list with original columns
• 🔄 Resume bulk jobs — switch tabs; open Bulk Verify again to continue
• 🔐 JWT auth + validation history
• 🌙 Dark mode

---

🛠 Tech stack

┌─────────────────────────────────────────────────────────┐
│  Browser  →  Node.js + Express (:5000)  UI + API        │
│                    │                                     │
│         ┌──────────┴──────────┐                          │
│         ▼                     ▼                          │
│  truemail-go (:8080)    Reacher Docker (:8081) optional │
│  SMTP + MX + 550 text   Industry-grade (Gmail-safe)     │
└─────────────────────────────────────────────────────────┘

Layer	Technology
Frontend	HTML5, Bootstrap 5, JavaScript
API	Node.js, Express, JWT
Database	MongoDB or in-memory (dev)
Verifier A	truemail-go (Go) — built-in
Verifier B	Reacher (Rust/Docker) — optional, recommended for huge lists
Misc lists	AfterShip email-verifier (disposable / role)

---

🚀 Quick start

Prerequisites

• Node.js 18+
• Go 1.22+ (for truemail-go)
• Docker Desktop (optional, recommended)

Install

git clone https://github.com/mafzalkalwardev/bulk-email-verifier.git
cd bulk-email-verifier
cp .env.example .env
npm install

Run (truemail-go only)

npm start

Open http://localhost:5000 → register → verify emails.

Run (with Reacher — best for Gmail / bulk)

docker compose up -d
npm start

In .env:

VERIFIER_ENGINE=auto

auto uses truemail-go first (fast). Reacher is used if Go is down. Set VERIFIER_ENGINE=reacher to force Docker engine.

---

🔬 Verification engines

Engine	Speed	Gmail	When to use
truemail-go	⚡ ~10–20s	Good SMTP 550	Default — no Docker
Reacher	🐢 can be slow	Headless checks	Huge lists, hard providers

Reacher timeout? Gmail via Docker can exceed 60s. The app falls back to truemail-go automatically.

See docs/ENGINES.md for details.

---

📖 Result columns

Column	Meaning
domain_valid	Syntax + MX OK
mailbox_verified	yes / no / no_smtp
valid	yes only when SMTP confirms mailbox

---

🖥 UI

• http://localhost:5000 — web app (only URL for browser)
• :8080 / :8081 — internal APIs (do not open for UI)

---

⚙️ Environment

Variable	Default	Description
PORT	5000	Web UI
JWT_SECRET	—	Change in production
VERIFIER_ENGINE	auto	auto | truemail | reacher
GO_VERIFIER_URL	http://localhost:8080	truemail-go
REACHER_URL	http://localhost:8081	Reacher Docker
REACHER_TIMEOUT_MS	60000	Reacher timeout before fallback
BULK_CONCURRENCY	3	Parallel emails per batch
MONGO_URI	empty	In-memory DB if empty

---

📁 Project structure

bulk-email-verifier/
├── backend/go/          # truemail-go API
├── lib/                 # Vendored Go libraries
├── public/              # Web UI
├── controllers/         # REST handlers
├── utils/               # CSV parser, engines
├── docker-compose.yml   # Reacher (optional)
└── docs/                # REQUIREMENTS, ENGINES

---

🚢 Publish to GitHub

git add .
git commit -m "feat: self-hosted bulk email verifier"
git branch -M main
git remote add origin https://github.com/mafzalkalwardev/bulk-email-verifier.git
git push -u origin main

Never commit .env (already in .gitignore).

---

🐛 Troubleshooting

Issue	Fix
ECONNREFUSED on register	Wait for In-Memory MongoDB ready before signing up
Reacher timeout	Uses truemail-go fallback; or set VERIFIER_ENGINE=truemail
Bulk lost on tab switch	Return to Bulk Verify — job resumes from sessionStorage
All no_smtp	Port 25 blocked — try Docker Reacher
docker not found	Install Docker Desktop, restart PC

---

Compliance and Responsible Use

This project is intended for lawful, permission-based email workflows only. Users must follow CAN-SPAM, GDPR, and other applicable anti-spam and privacy laws, SMTP provider terms, opt-out/unsubscribe requirements, and recipient consent rules.

Do not use this software for phishing, spam, unsolicited bulk mail, purchased lists without permission, or deceptive sender identity. Verify only contacts you are authorized to validate or contact.

The maintainers are not responsible for misuse of this software.

Status: Client-ready · self-hosted · demo data recommended for screenshots

---

📄 License

MIT — LICENSE. Third-party code in lib/ has its own licenses.

---

⭐ Star this repo if it saved you from paid verification APIs

Made for developers who need real SMTP checks without a subscription.