Prospector

Turn job postings into qualified outreach — for any domain.

Prospector monitors job boards for hiring signals that indicate a company needs what you sell. It enriches leads with company and decision-maker data, scores them by fit, drafts personalized cold emails using AI, and sends them on autopilot — with follow-ups.

Out of the box it's configured for IT services outreach, but everything is customizable: swap the search queries, scoring signals, email templates, and target titles to prospect in any vertical.

How it works

Job Boards (Indeed, Google Jobs, ZipRecruiter)
    ↓  scrape hiring signals
Apollo.io
    ↓  enrich with company data + find decision-makers
Scoring Engine
    ↓  rank by industry, size, pain signals, tooling
Claude AI
    ↓  generate personalized email hooks
Gmail API
    ↓  send with daily caps + threading
Follow-up
    ↓  auto re-engage after 3+ days of silence

Quick start

git clone https://github.com/your-org/prospector.git
cd prospector
pip3 install -r requirements.txt

cp .env.example .env
# Fill in your API keys (see Configuration below)

python3 main.py scrape          # scrape → enrich → score → draft → Google Sheets
python3 main.py send --preview  # preview emails before sending
python3 main.py send            # send emails via Gmail
python3 main.py followup        # follow up on unanswered leads

Commands

scrape — Find and qualify leads

Scrapes job boards, enriches via Apollo, scores leads, drafts emails, and outputs to Google Sheets or CSV.

python3 main.py scrape                     # full pipeline → Google Sheets
python3 main.py scrape --csv               # full pipeline → CSV
python3 main.py scrape --dry-run           # scrape only, save raw JSON
python3 main.py scrape --no-claude         # skip AI hooks, use generic fallback
python3 main.py scrape --max-per-query 30  # limit results per search query

send — Send emails

Loads the latest leads CSV and sends via Gmail API with daily caps and deduplication.

python3 main.py send --preview  # dry run — see what would be sent
python3 main.py send            # actually send
python3 main.py send --cap 10   # override daily limit (default: 25)

followup — Re-engage silent leads

Checks for leads who haven't replied after N days and sends a follow-up in the same Gmail thread.

python3 main.py followup --preview  # dry run
python3 main.py followup            # send follow-ups
python3 main.py followup --days 5   # wait 5 days instead of default 3

Configuration

Copy .env.example to .env and fill in:

Variable	Required	Description
APOLLO_API_KEY	Yes	Apollo.io API key for company/contact enrichment
ANTHROPIC_API_KEY	No	Anthropic API key for AI-generated email hooks
GOOGLE_SHEETS_CREDS_FILE	No	Path to Google service account JSON (for Sheets output)
GOOGLE_SHEET_NAME	No	Name of the Google Sheet to write to
GMAIL_OAUTH_CREDS_FILE	Yes	Path to Gmail OAuth client credentials JSON

Google setup

1. Gmail (sending): Create an OAuth 2.0 Client ID (Desktop app) in Google Cloud Console. Download the JSON and save as gmail_credentials.json. On first run, a browser window opens for consent.

2. Google Sheets (optional): Create a service account, download the JSON, and share your target spreadsheet with the service account email.

Adapting to your domain

Prospector ships with an IT services config, but you can retarget it to any vertical by editing a few files:

File	What to customize
src/config.py → SEARCH_QUERIES	Job titles to scrape (e.g. "marketing manager", "data engineer")
src/config.py → TITLE_INCLUDE_KEYWORDS	Which job titles count as relevant
src/config.py → PAIN_SIGNALS	Keywords in job descriptions that signal a need for your product
src/config.py → PRIORITY_INDUSTRIES	Industries to prioritize in scoring
src/config.py → DM_TITLES	Decision-maker titles to look up on Apollo
src/config.py → EXCLUDE_KEYWORDS	Companies to skip (staffing firms, etc.)
src/email_drafter.py	Email template, AI prompt, and sender name
src/scorer.py	Scoring weights and thresholds

Example: To prospect for a recruiting SaaS, you'd change SEARCH_QUERIES to HR/recruiting roles, PAIN_SIGNALS to things like "applicant tracking", "time to hire", and DM_TITLES to "VP of People", "Head of Talent", etc.

Automation

Prospector includes a GitHub Actions workflow (.github/workflows/daily-outreach.yml) that runs the full pipeline on a daily schedule. See the workflow file for required secrets.

Project structure

prospector/
├── main.py                 # CLI entry point
├── src/
│   ├── config.py           # All configuration and constants
│   ├── scraper.py          # Job board scraping (JobSpy)
│   ├── enrichment.py       # Apollo.io API integration
│   ├── scorer.py           # Lead scoring engine
│   ├── email_drafter.py    # AI-powered email generation
│   ├── sender.py           # Gmail sending + tracking
│   └── sheets.py           # Google Sheets output
├── .github/workflows/
│   └── daily-outreach.yml  # Daily automation
├── .env.example            # Environment template
└── requirements.txt        # Python dependencies

Requirements

• Python 3.11+
• API keys: Apollo.io (required), Anthropic (optional)
• Google Cloud project with Gmail API and Sheets API enabled

License

MIT — see LICENSE.