OpenLeads

pipx install "openleads[all]"          # or: pip install "openleads[all]", or: npx openleadsopenleads find "dentists in Austin"    # ten leads, every email labeledopenleads web                          # the workspace at http://127.0.0.1:8787

_{The local dashboard on the demo workspace (openleads demo, invented data).}

Every email says how we know it

Most free finders call a first.last@ guess "valid". OpenLeads labels each address with where it came from, then decides separately whether it is safe to send:

Seven checks decide the tier, and most of them work without port 25, which home internet providers block: two DNS-over-HTTPS resolvers that must agree on the mail server, SPF and DMARC, disposable/role/free-mail lists, Gravatar, published addresses, learned company patterns, and SMTP with catch-all detection when port 25 is open. How the scoring works.

Measured against live data every night

Unit tests can't tell you whether "dentists in Austin" returns dentists, so a GitHub Action runs the same real searches against the live sources every night, asks for ten leads each, and commits what came back to BENCHMARK.md, empty nights included. Run it yourself with openleads bench.

What you can search

One sentence fans out across the sources that fit it. You never have to pick one, but -s name pins a source.

Companies are turned into named people from their team and about pages. When a search comes back short, OpenLeads says which source failed or ran out of time and what to try next. Need a source we don't have? A source is one Python file.

Work your leads

Everything you find lands in a local workspace: the same data in the dashboard, the terminal and your AI assistant.

openleads people --fit A --never-contacted                 # best untouched leadsopenleads lists add "Q4 dentists" --where dentalopenleads seq enroll "Q4 outbound" --list "Q4 dentists"openleads tasks --bucket todayopenleads import apollo-export.csv --list "Imported"

Workspace guide  |  Sequences guide  |  Moving from Apollo

Use it from Python

import openleads
leads = openleads.find("gyms in Sydney", count=20)for lead in leads:    print(lead.email, lead.evidence, lead.tier)leads.write("gyms.csv")            # .csv, .json or .jsonlprint(leads.report.summary())      # which sources ran, what failed, why it stopped

Python API

Use it from Claude, Cursor or Claude Code

OpenLeads is an MCP server. Your assistant can find and verify leads mid-conversation, and work your lists, tasks and sequences:

claude mcp add openleads -- openleads mcp

{ "mcpServers": { "openleads": { "command": "openleads", "args": ["mcp"] } } }

"Find 10 law firms in London with emails we can actually send to, save them to a list called London law, and give me a call task for each partner."

The assistant can search and edit your workspace, but it never sends email itself.

Automate it

Workflows are n8n-style node graphs you draw in the dashboard: triggers (schedule, new leads, a reply), find, verify, filter and split by tier, write email, wait, send, add to a list or sequence, create tasks, and export. Test runs never send; every run shows what each node did. Sends stay inside your daily cap, warmup ramp and business hours, and stop for anyone who replies.

openleads workflow templates                       # 7 ready-made workflowsopenleads workflow new dentists --from local-business-outreach   # arrives pausedopenleads workflow run dentists      # a test run: finds and writes, never sends

openleads recipe add miami "marketing agencies in Miami" --every "weekdays 9am" --sendopenleads watch add new-dentists "dentists in Austin"     # tell me only about new matchesopenleads schedule on      # one agent: launchd, cron or Windows Task Scheduleropenleads runs             # what ran, what it found, what failed

Workflows  |  Writing emails  |  Timed runs. Exports go to CSV, Google Sheets, Notion, Airtable, HubSpot or any webhook. There is also a GitHub Action:

- uses: Samyrrrrrr990/[email protected]  with: { query: "marketing agencies in Miami", count: 50 }

Install

pipx install "openleads[all]"     # recommendedpip install openleads             # minimal: the standard-library engine and CLInpx openleads                     # Node: sets up a private Python environment on first run

openleads doctor    # checks your setup: DNS, port 25, mailboxopenleads demo      # the dashboard on an invented workspaceopenleads           # chat: type what you want

Python 3.8 or newer on macOS, Linux or Windows. Full walkthrough: quickstart.

Commands

# findopenleads find "50 fintech founders, verified only" -o leads.csvopenleads find "accountants in Toronto" --explain     # the plan, each source's status, hintsopenleads company stripe.com                           # tech stack, socials, phones, peopleopenleads enrich my-list.csv                           # your names and companies, emails labeledopenleads verify [email protected]
# reach out (a dry run unless you add --live)openleads write "rust developers in Berlin" --variants 2 --explain   # drafts, scored, with the briefopenleads run "rust developers in Berlin"
# the workspaceopenleads people | companies | lists | seq | tasks | dealsopenleads import | export | dedupe | stats | backup
# set up and automateopenleads init | config | doctor | web | mcp | benchopenleads recipe | watch | schedule | runs

openleads --help lists every command by group.

How it works

flowchart LR    Q["'dentists in Austin'"] --> P[Query parser]    P --> F[Planner<br/>picks the sources]    F --> S1[OpenStreetMap]    F --> S2[YC, HN, GitHub, Hugging Face,<br/>OpenAlex, EDGAR, Wikidata, NPI]    S1 & S2 --> D[People from team pages<br/>+ real-name check]    D --> E[Email checks<br/>harvest, pattern, MX, SMTP, Gravatar]    E --> L[Leads with evidence and tier]    L --> W[Workspace, sequences, exports]    E <--> DB[(Local SQLite<br/>learned patterns, workspace)]

The engine is Python standard library only. Requests that fail transiently are retried, a search returns within its time budget with whatever finished, and every run produces a report of which sources answered, which fell back and why. Your leads, drafts, mailbox credentials, learned patterns and the whole workspace live in ~/.openleads. There is no hosted backend, no account and no telemetry. Architecture.

Responsible use

OpenLeads is for legitimate prospecting, recruiting and research. You are responsible for anti-spam law (CAN-SPAM, GDPR, CASL) and each source's terms. It ships the guardrails: dry runs by default, a suppression list, one-click unsubscribe, warmup caps and no tracking pixels. Responsible use.

License

Open source under AGPL-3.0. Using OpenLeads is free, including at your company. If you embed it in a closed-source product, or run a modified version as a service without publishing your changes, you need a commercial license.

Contributing

The most useful contribution is a new source (guide); the next is a query that openleads bench scores badly, with the fix. See CONTRIBUTING.md. Thanks to everyone who has sent a pull request, including @xmejl, @harrisonoconnorhover and @Shalinipks for 5.1.

Thanks

OpenStreetMap contributors, OpenAlex, yc-oss/api, Hugging Face, the NPI Registry, SEC EDGAR, Wikidata, Gravatar, and the US Social Security Administration for its given-name data. The dashboard and website use Atkinson Hyperlegible by the Braille Institute.