MailForge

Client Windows install? Read client.md, place the client's indus-license*.json file beside Client-Install-MailForge.bat, then double-click Client-Install-MailForge.bat.

Developer/new PC setup? Follow SETUP.md or run npm run setup:new-pc after cloning.

• Live SMTP verification — syntax, MX, disposable/role checks, real RCPT dialog
• Strict SMTP validity — 550/553/503 rejections and IP-block responses are never marked valid; blocked checks show as unknown
• Backend bulk jobs — upload CSV/XLSX, verification runs on the server; switch tabs freely
• Pause / resume / stop — control long-running verify jobs without losing progress
• Download while running — export completed rows or valid-only rows before a long job finishes
• Recent job downloads — Bulk Verify loads recent jobs immediately and can download saved or in-progress results
• Bulk CSV / XLSX — finds emails in any column; exports keep original columns first and append verification fields

• Verify → send pipeline — auto-redirect to campaign creator when verification completes (toggle in Settings)
• Create from verified lists — valid-only recipients with original CSV columns preserved
• Multi-Gmail rotation — delays, retries, warm-up, bulk sender import
• Editable senders — update email username, display name, app password, SMTP/IMAP hosts, daily limits, warm-up day, and today's send count
• Create & start — launch a campaign in one click from the wizard

• 10 Freight Outreach templates — imported from the original Auto Emailer (INDUS Transports)
• Combined freight pack — all 10 subjects + 10 bodies in one template for random rotation
• Merge fields — {Name}, {Email}, {State}, {SENDER_NAME}, {SENDER_EMAIL}, {COMPANY_NAME}
• AI template generator — Groq (free), OpenRouter, or OpenAI for spam-safe copy
• Edit & manage — full CRUD from the Templates page or inline in campaign create

• Unified inbox — view all sender accounts together or filter by one Gmail account
• Reply from inbox — send threaded replies from the same sender account (In-Reply-To headers)
• Unread / Starred / Important — filter pills and toggle on each message
• Per-account sync — sync a single mailbox or all accounts at once
• JWT auth, dark mode, per-user settings

• Suppression list — block bounces, unsubscribes, and manual blocks from all campaigns
• Auto bounce suppression — failed sends with bounce-like SMTP errors are added automatically
• Unsubscribe links — optional footer in every campaign email with one-click opt-out page
• Scheduled campaigns — set a future start time; background scheduler launches them automatically
• Campaign analytics — reply rate, replies over time, performance by sender account
• Sender health dashboard — sent today vs daily limit per Gmail account
• Onboarding checklist — guided setup on first login

• Docker full stack — docker compose -f docker-compose.full.yml up -d (MongoDB + app)
• CI pipeline — Node tests + Go build on every push
• Screenshot script — node scripts/capture-screenshots.js for README assets

• Mongo persistence banner — warns when running on in-memory dev database (data lost on restart)
• Partial verify save — pause/stop saves progress to History as a partial bulk job
• List hygiene score — duplicates, age, valid ratio from History → heart icon
• Re-verify lists — one-click re-run verification on saved bulk jobs
• Dedupe on campaign create — remove duplicate emails when building a campaign
• Export presets — download all or valid-only CSV from History API

• Thread view — group messages by conversation in unified inbox
• Lead tags — mark replies as Lead, Follow up, or Not interested (auto-suppresses)
• Quick reply templates — one-click reply snippets in inbox
• Bounce detection — IMAP sync flags bounces and adds to suppression list

• Hourly send cap — limit sends per hour across a campaign
• Sender auto-pause — pause sender when failure rate exceeds threshold
• CAN-SPAM footer — optional physical address footer on campaign emails
• Save partial on pause — toggle in Settings for verify job behavior

• Health API — GET /api/health reports DB persistence and uptime
• Backup export — GET /api/backup/export downloads user data JSON
• Bulk job utils tests — hygiene, dedupe, export covered in CI

• One-click Windows installer — Client-Install-MailForge.bat installs production deps, builds the Go verifier, downloads embedded MongoDB, and creates Desktop/Start Menu shortcuts
• INDUS license gate — subscription license verified at startup (indus-license*.json in app root or ./data); local cache tolerates short offline periods after first online check
• Portable package — copy the full folder with MailForge.exe, verifier.exe, and data/mongodb to another PC (see PORTABLE_PACKAGE_NOTES.txt)
• Embedded MongoDB mode — MAILFORGE_DB_MODE=embedded stores data locally without Docker or Atlas

• Faster bulk verify — configurable concurrency via BULK_CONCURRENCY (default 15, max 50)
• Hardened verifier runtime — improved Go verifier startup, dependency pinning, and bulk worker error handling
• Serialized progress saves — bulk verification progress is saved safely during pause/stop

MailForge uses truemail-go as the primary engine — it performs a real SMTP RCPT dialog and captures the server response text (550, 250, etc.). Results are post-processed so reject codes like 550 5.7.1 Service unavailable or 553 TSS09 are not counted as valid.

Set in .env:

VERIFIER_ENGINE=auto

Optional Reacher (Docker):

docker compose up -d

For a client handoff, MailForge is delivered like a local SaaS-style desktop app: the browser UI runs at http://localhost:5000, MongoDB data stays inside the installed app folder, and the client starts it from a Desktop or Start Menu shortcut.

Give the client:

• The full MailForge folder from the latest GitHub main.
• Their INDUS license file named indus-license*.json.
• The setup guide: client.md.

Client install steps:

1. Extract or copy the full MailForge folder to the Windows PC.
2. Put indus-license*.json in the MailForge folder, next to Client-Install-MailForge.bat.
3. Double-click Client-Install-MailForge.bat.
4. Let the installer finish.
5. Open MailForge from the Desktop shortcut, Start Menu, or MailForge.exe.
6. Use http://localhost:5000 in the browser.

The installer prepares production Node packages, the Go SMTP verifier, embedded MongoDB binaries, local persistent data, Desktop/Start Menu shortcuts, and an uninstall entry. Docker and MongoDB Atlas are not required for the client desktop install.

The app verifies the INDUS subscription license at startup. For client deliveries, do not enable INDUS_SKIP_LICENSE; that flag is only for local developer QA.

Full developer guide: SETUP.md | Client installer guide: client.md | New machine: npm run setup:new-pc

• Node.js 18+
• Go 1.22+ (for truemail-go verifier)

For a client PC, use the guided Windows installer after placing the client license file beside it:

Client-Install-MailForge.bat

It checks Node.js, Go, and npm; offers winget installs for missing tools; creates .env; installs production dependencies; prepares embedded MongoDB; builds the Go verifier; creates shortcuts; and opens MailForge.

Manual install:

cd MailForge
copy .env.example .env
npm run setup
npm start

Open http://localhost:5000 → register → start verifying.

docker compose -f docker-compose.full.yml up -d

This starts MongoDB and the MailForge app on port 5000. Run truemail-go on the host at :8082, or add the Reacher profile:

docker compose -f docker-compose.full.yml --profile reacher up -d

Atlas blocks connections unless your IP is whitelisted. For local dev, use Docker MongoDB on your PC — data survives restarts and Compass works at mongodb://127.0.0.1:27017/mailforge.

Easiest start (pick one):

npm run mongo:up          # MongoDB only (if app already running)
npm start                 # app only
npm run build:exe         # rebuild MailForge.exe launcher

MongoDB Compass: connect with mongodb://127.0.0.1:27017 → database mailforge.

Optional Atlas cloud backup: uncomment MONGO_URI in .env only when Network Access allows your IP.

One-command start (Node + Go verifier on Windows):

npm run start:all

Groq (free tier, recommended) — get a key at console.groq.com:

AI_PROVIDER=groq
GROQ_API_KEY=gsk_your_key_here

Also supports OpenRouter (free models) and OpenAI. Configure in Settings → AI & workflow or via .env.

flowchart LR
    A[Upload CSV/XLSX] --> B[Bulk Verify]
    B --> C[Valid-only list]
    C --> D[Create Campaign]
    D --> E[Multi-sender SMTP]
    E --> F[Unified Inbox]
    F --> G[Read replies]

1. Bulk Verify — upload your list; pause/resume as needed
2. Auto-redirect — when done, opens Create Campaign with the verified list loaded
3. Templates — pick a starter template or generate spam-safe copy with AI
4. Senders — add Gmail accounts (App Passwords), bulk import, or edit account details and warm-up limits later
5. Create & Start — launch the campaign
6. Inbox — sync and read replies

You can also go History → plane icon → Create Campaign at any time.

Browser → Node.js + Express (:5000)
              ├── MongoDB (or in-memory dev)
              ├── truemail-go (:8082) — SMTP verification
              ├── Reacher Docker (:8081) — optional fallback
              ├── nodemailer — campaign sending
              ├── imapflow — inbox sync
              └── OpenAI API — optional AI templates

See .env.example for all options.

Per-user overrides (verifier URLs, OpenAI key, auto-redirect after verify) are available in Settings.

https://github.com/mafzalkalwardev/mailforge

We welcome contributions! See CONTRIBUTING.md for:

• Fork and PR workflow
• Development setup
• Issue and PR templates
• Code guidelines

Good first contributions: docs, tests, bug fixes, UI polish.

MIT — see LICENSE.