06-resolution-email-person

Resolution - Email + Person

Turn {domain (required), optional person_name, optional job_title} into a verified, send-safe email.

The one principle that governs every decision here: bounce rate, not find rate, is the signal that matters. A found-but-undeliverable email is worse than no email - it burns sender reputation. So this skill optimizes for deliverable contacts at minimum credit cost, and it never spends enrichment credit without the user's explicit go-ahead.

domain is the one mandatory input across every tool. Everything else can be asked for, inherited from upstream, or derived.

Provider + auth setup

Each provider reads its API key from an environment variable - AIARK_API_KEY, PROSPEO_API_KEY, BLITZ_API_KEY, FINDYMAIL_API_KEY, ZEROBOUNCE_API_KEY - never hardcode a key. This skill calls the providers with curl, and a .env file is not visible to curl - load it into the shell in the same command as the call, otherwise an empty auth header comes back as a provider auth error rather than a missing-key one:

set -a; [ -f .env ] && . ./.env; set +a

An exported variable or a secrets manager takes precedence and needs no prelude. The skill runs with as few as one key set: at startup, detect which keys are present, use only those rungs, and skip the rest (log which rungs were skipped and why). Read references/providers.md for endpoints, request shapes, billing rules, and rate limits before making any call.

• AI Ark - rung 0, conditional: runs only if AIARK_API_KEY is set. Two modes. (a) Passthrough: a row that already carries an AI Ark-verified email (source flag ai_ark/pre_verified, or the caller says the list is an AI Ark export) is accepted as-is - don't re-find what's already verified. (b) Finder: POST /people/export/single turns a LinkedIn profile URL or AI Ark person id (not name+domain) into a BounceBan-verified email - 1 credit per valid email, 0 on a miss. Strong on SMB operators where Prospeo is weak. The POST /people search bills separately (~0.5 credit per returned profile), so keep searches tightly filtered and prefer /people/export/single.
• Prospeo - title-first finder, strong on mid-market + enterprise. Charged only when a request returns results (misses are free).
• Blitz - domain-first finder, strong on SMB. Free on Blitz's Unlimited plan (verify your own plan before treating it as free). Two steps: domain-to-linkedin → employee-finder (native job_level/job_function filters); returns the person but not the email.
• Findymail - email finder by name+domain (POST /api/search/name - NOT /api/find, which 405s; see references/providers.md).
• ZeroBounce - independent email validation (GET /v2/validate). If its key isn't set, fall back to the finding provider's bundled verdict. Explicit catch-all status (no false "ok" on catch-all domains), and unknown results consume no credit.