shivohamshiv/cold-outreach-tool

Cold Outreach Tool — 100% free, no system dependencies

A self-contained web app for service providers (performance marketing, SEO, virtual CMO/CTO, custom dev) doing cold outreach. Find target companies + their founders, track every prospect, and send templated emails.

This build needs no local system software. No Chrome, no Selenium, no Ollama, no paid APIs, no captcha-solver subscriptions. It's pure Python and runs anywhere Python runs.

Two discovery engines (pick with SEARCH_ENGINE)

SeleniumBase runs headless in the background (no window). It's free software — the catch is it launches a real Chrome, so it needs the Chromium binary and ~1 GB+ RAM. On a 512 MB free web tier it will be OOM-killed, so there it automatically falls back to the web engine. To use the browser engine, install the extras and set the env var:

pip install -r requirements-selenium.txt
SEARCH_ENGINE=selenium python app.py

…or use the included Dockerfile, which bakes in Chromium and defaults to SEARCH_ENGINE=selenium (run it on a host/instance with enough RAM).

Run locally

Prerequisite: Python 3.10+

python3 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt
python app.py

Open http://localhost:5000

That's it — no other installs, no API keys.

Deploy for free

The app is a single process. It must run with one worker (discovery and the email scheduler use an in-process background thread + JSON files), so always use --workers 1. A Procfile, Dockerfile, and render.yaml are included.

Render (free plan) — easiest

1. 1.Push this repo to GitHub.
2. 2.In Render: New + → Blueprint → pick this repo. Render reads the included render.yaml automatically and deploys. Done.
3. 3.Prefer manual? New + → Web Service, build pip install -r requirements.txt, start gunicorn app:app --workers 1 --threads 8 --timeout 120 --bind 0.0.0.0:$PORT.

The free plan (512 MB) runs the `web` engine only. To use the headless `selenium` browser engine on Render, deploy with the Docker runtime (the included Dockerfile) on an instance with ≥ 1 GB RAM (a paid plan), and it'll set SEARCH_ENGINE=selenium for you.

Railway / Fly / Heroku-style

The included Procfile works as-is:

web: gunicorn app:app --workers 1 --threads 8 --timeout 120 --bind 0.0.0.0:${PORT:-5000}

Docker (any host)

docker build -t cold-outreach .
docker run -p 5000:5000 -v $(pwd)/data:/data cold-outreach

Mounting a volume at /data (the default DATA_DIR) keeps your profile and tracker between restarts.

Configuration (all optional)

Everything works with zero config. Override defaults via env vars — see `.env.example`:

Data persistence: the app writes profile.json, tracker.json, job_state.json, and scheduled_queue.json to DATA_DIR. On free hosting without a persistent disk these reset when the instance recycles — use the Export CSV/JSON buttons to back up, or point DATA_DIR at a mounted disk.

The 3-tab workflow

Tab 1 — Profile (set once)

Your name, city, one-line pitch, services, portfolio URL, a real case-study line, and your message templates. Templates support placeholders: {owner_name}, {company_name}, {your_name}, {portfolio_url}.

To send emails, add your Gmail address + a 16-char App Password (https://myaccount.google.com/apppasswords). Free, and credentials stay in your own data file.

Tab 2 — Discovery

Pick a service, industry, and location, then run. The tool searches the web for matching companies, then for each one searches again to pull out founders/owners (name, LinkedIn, email, phone where public). Pause/resume anytime — state is saved. There's also a Hiring mode and a Local businesses mode (OpenStreetMap) for small-business prospecting.

Tab 3 — Tracker & Outreach

Every prospect is a card: company + founder details, status badge, notes, generated message, one-tap WhatsApp link, and (if Gmail is set up) send / schedule. Filter by status. Export to CSV/JSON anytime.

Honest expectations

• —Free web search is best-effort. DuckDuckGo may occasionally return thin results or rate-limit you (you'll see search miss in the logs). Raise SLEEP_BETWEEN_QUERIES and re-run — it resumes where it left off.
• —OpenStreetMap has good coverage of business names/addresses but phone numbers are hit-or-miss compared to Google Maps. It's free and keyless.
• —Cold-outreach reply rates are 1–3%. The biggest lever is your offer + portfolio, not the tool. Get those solid before sending volume.
• —Gmail sending is rate-limited on purpose (20/day, 30s apart) so you don't get your account flagged.

Files the app creates (in DATA_DIR)

• —profile.json — your outreach profile
• —tracker.json — all prospects + statuses + messages
• —job_state.json — current discovery job (pause/resume)
• —scheduled_queue.json — scheduled email queue

Safe to back up. Safe to delete (resets that piece).