enrich-emails

A Claude Code plugin that resolves a CSV of email addresses to real people — name, LinkedIn, GitHub, personal site, Twitter — via a cost-aware waterfall.

Pipeline

Python pass 1 (free)                    Claude (free, on misses)         Python pass 2 (paid)
─────────────────────                   ─────────────────────            ─────────────────────
1. GitHub commits                →      4. Blog WebFetch          →      5. Apollo on remaining
   └→ /users/{handle} +                 5. Targeted web search            misses only
      /social_accounts                     (tiered confidence)
2. Gravatar
3. GitHub handle cross-check
   (skipped if we already have a handle)

Default mode (loose) counts a row as a hit when it has a name plus at least one identity URL (LinkedIn, GitHub, personal website, or Twitter). strict mode requires name + LinkedIn specifically.

Install

/plugin install <your-org>/enrich-emails

Or clone into your plugins directory manually:

git clone https://github.com/<your-org>/enrich-emails.git ~/.claude/plugins/enrich-emails

Then copy the example env file and fill in your keys:

cd ~/.claude/plugins/enrich-emails/skills/enrich-emails
cp .env.example .env
# edit .env — add GITHUB_TOKEN (required) and APOLLO_API_KEY (optional)

API keys

key	required?	purpose
GITHUB_TOKEN	yes	Search + profile lookups. Without it, GitHub rate-limits hard. public_repo scope is enough. Create one at https://github.com/settings/tokens.
APOLLO_API_KEY	optional	Used only for the paid --only apollo final pass. Get one at https://app.apollo.io/#/settings/integrations/api.

Gravatar needs no key.

Usage

Just ask Claude Code: "enrich these emails", "find the people behind these emails", or give it a CSV and say "who are these".

Claude will run the Python script, handle the web search pass, apply tiered confidence rules to promote hits, and produce:

• <output_dir>/enriched.csv — resolved rows
• <output_dir>/misses.csv — unresolved rows with notes

Direct CLI use

If you want to run the Python step without Claude:

cd ~/.claude/plugins/enrich-emails/skills/enrich-emails
python3 enrich.py path/to/input.csv path/to/output_dir

Options:

• --mode loose|strict|name-only (default: loose)
• --only apollo — run only the Apollo pass (use on a misses.csv after the free waterfall + web search)
• --only github_commits | gravatar | github_profile | github_handle | github — run a single phase for debugging

Input CSV must have an email column (case-insensitive). Any other columns pass through to the output.

Known limits

• X/Twitter bio is not readable. X killed anonymous profile access — when a miss has a Twitter handle but no blog/LinkedIn, the note check twitter bio manually is added. Users often put their personal site URL in their X profile, which often links to LinkedIn.
• Role mailboxes (noreply@, info@, support@, etc.) are flagged and skipped — they're not people.
• Rate limits. Script paces at ~7 req/sec. GitHub search endpoint is ~30/min authenticated. For very large lists (500+), expect minutes.

License

MIT — see LICENSE. Built by Cache.