Find and verify emails for HubSpot prospects using Apollo and Hunter with a Claude Code skill

mkdir -p .claude/skills/find-emails/{templates,references}

.claude/skills/find-emails/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── field-mapping.md              # HubSpot field mapping for email results
└── references/
    ├── apollo-people-match.md        # Apollo People Match API patterns
    ├── hunter-email-verifier.md      # Hunter Email Verifier API patterns
    └── hubspot-contacts-api.md       # HubSpot CRM Search + Update patterns

---
name: find-emails
description: Find and verify work emails for HubSpot contacts missing email addresses using Apollo and Hunter
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Find HubSpot contacts that are missing email addresses, look up their work email via Apollo's People Match API, verify deliverability with Hunter's Email Verifier API, and write verified emails back to HubSpot.
 
## Configuration
 
Read these environment variables:
 
- `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token (required)
- `APOLLO_API_KEY` — Apollo API key (required)
- `HUNTER_API_KEY` — Hunter.io API key (required)
 
Default behavior: find all contacts missing an email that have both a first name and company. The user may request a different filter, a specific list, or a dry-run mode.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Search HubSpot for contacts matching the criteria (missing email, has name and company). See `references/hubspot-contacts-api.md` for the Search API.
3. For each contact, call Apollo's People Match endpoint with first name, last name, and company. See `references/apollo-people-match.md`.
4. If Apollo returns an email with `email_status: "verified"`, skip Hunter verification.
5. For unverified Apollo emails, call Hunter's Email Verifier. See `references/hunter-email-verifier.md`.
6. Write results to HubSpot using the mapping in `templates/field-mapping.md`. Only write verified or deliverable emails. Flag risky emails.
7. Print a summary: how many found, verified, risky, and not found.
 
## Important notes
 
- Apollo charges 1 credit per People Match call even when no person is found. Clean data (accurate names, correct company names) improves match rates.
- Apollo's match rate is significantly better with a company domain than a company name. If the contact has a `domain` property, use it.
- Hunter returns `unknown` for catch-all domains. Treat these as unverified but potentially valid.
- Apollo rate limit: 5 requests/second on Basic. Add 0.5-second delays between calls.
- Hunter rate limit: 15 requests/second. No delay needed for small batches.
- Use the `requests` library for HTTP calls. Install with pip if needed.

# Apollo People Match API Reference
 
## Find a person by name and company
 
**Request:**
 
```
POST https://api.apollo.io/api/v1/people/match
x-api-key: <APOLLO_API_KEY>
Content-Type: application/json
```
 
**Body (name + company):**
 
```json
{
  "first_name": "Jane",
  "last_name": "Doe",
  "organization_name": "Acme Corp"
}
```
 
**Body (name + domain — higher accuracy):**
 
```json
{
  "first_name": "Jane",
  "last_name": "Doe",
  "domain": "acme.com"
}
```
 
**Response shape (matched):**
 
```json
{
  "person": {
    "email": "jdoe@acme.com",
    "email_status": "verified",
    "title": "VP of Engineering",
    "organization": {
      "name": "Acme Corp"
    }
  }
}
```
 
**email_status values:**
- `verified` — confirmed deliverable by Apollo (safe to skip Hunter)
- `guessed` — pattern-matched, not confirmed (needs Hunter verification)
- `unavailable` — no email found
- `null` — status unknown
 
**Response shape (no match):**
 
```json
{
  "person": null
}
```
 
## Notes
 
- Rate limit: 5 requests/second on Basic, 10/sec on Professional.
- 1 credit per call regardless of match result.
- Using `domain` instead of `organization_name` significantly improves match rates.

# Hunter Email Verifier API Reference
 
## Verify a single email
 
**Request:**
 
```
GET https://api.hunter.io/v2/email-verifier?email=<EMAIL>&api_key=<HUNTER_API_KEY>
```
 
**Response shape:**
 
```json
{
  "data": {
    "result": "deliverable",
    "score": 95,
    "email": "jdoe@acme.com",
    "regexp": true,
    "gibberish": false,
    "disposable": false,
    "webmail": false,
    "mx_records": true,
    "smtp_server": true,
    "smtp_check": true,
    "accept_all": false,
    "block": false
  }
}
```
 
**result values:**
- `deliverable` — safe to send to
- `risky` — might bounce (catch-all domain, accept_all=true)
- `undeliverable` — will bounce
- `unknown` — couldn't determine (common with catch-all domains)
 
## Notes
 
- Rate limit: 15 requests/second.
- 1 credit per verification on paid plans.
- Free plan: 25 verifications/month. Starter: $49/mo for 1,000.
- `accept_all: true` means the domain accepts all addresses — verification can't confirm a specific mailbox exists.

# HubSpot Contacts API Reference
 
## Search for contacts missing email
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/contacts/search
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
**Body:**
 
```json
{
  "filterGroups": [
    {
      "filters": [
        { "propertyName": "email", "operator": "NOT_HAS_PROPERTY" },
        { "propertyName": "firstname", "operator": "HAS_PROPERTY" },
        { "propertyName": "company", "operator": "HAS_PROPERTY" }
      ]
    }
  ],
  "properties": ["firstname", "lastname", "company", "domain"],
  "limit": 100
}
```
 
- Filters within the same `filterGroup` are ANDed together.
- `limit` max is 100. Use `paging.next.after` to paginate.
 
## Update a contact
 
```
PATCH https://api.hubapi.com/crm/v3/objects/contacts/<CONTACT_ID>
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
**Body:**
 
```json
{
  "properties": {
    "email": "jdoe@acme.com",
    "email_source": "apollo+hunter",
    "email_verification_status": "verified"
  }
}
```
 
- Only include properties you want to update.
- Custom properties (`email_source`, `email_verification_status`) must exist in HubSpot first.

# Email Finder → HubSpot Field Mapping
 
| Source | HubSpot property | Notes |
|--------|-----------------|-------|
| Found email | `email` | Only write if verification result is "deliverable" or "verified" |
| Source attribution | `email_source` | "apollo" (if Apollo-verified) or "apollo+hunter" (if Hunter-verified). Custom property. |
| Verification result | `email_verification_status` | "verified", "risky", "undeliverable", or "not_found". Custom property. |
 
## Rules
 
- **Only write verified or deliverable emails** to the `email` field. Risky emails may be stored with a flag but should be reviewed before use.
- Set `email_verification_status` for every processed contact, even when no email was found (use "not_found") to prevent re-processing.
- Custom properties must be created in HubSpot before the script runs.

/find-emails

Searching for contacts without email addresses...
  Found 25 contacts with name + company but no email
 
Processing 25 contacts...
  Jane Doe @ Acme Corp → jdoe@acme.com (apollo-verified)
  Mike Chen @ WidgetCo → mchen@widgetco.io (hunter: deliverable)
  Sarah Kim @ BigCo → skim@bigco.com (hunter: risky)
  Tom Brown @ SmallShop → not found
  ...
 
Done. Verified: 18, Risky: 3, Not found: 4. Skipped Hunter for 8 Apollo-verified emails.

# Run daily at 6 AM
0 6 * * * cd /path/to/your/project && claude -p "Run /find-emails" --allowedTools 'Bash(*)' 'Read(*)'

name: Find and Verify Emails
on:
  schedule:
    - cron: '0 11 * * *'  # Daily at 6 AM ET
  workflow_dispatch: {}   # Manual trigger for testing
jobs:
  find:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /find-emails"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          HUBSPOT_ACCESS_TOKEN: ${{ secrets.HUBSPOT_ACCESS_TOKEN }}
          APOLLO_API_KEY: ${{ secrets.APOLLO_API_KEY }}
          HUNTER_API_KEY: ${{ secrets.HUNTER_API_KEY }}