Enrichment

Icypeas

Find and verify emails in bulk, without babysitting it.

Icypeas runs email searches and verifications as background jobs, so a long list does not hold anything up. You hand it the list, it works through it, hyreflow collects the results when they land.

Icypeas is the volume option. Reach for it when the list is long enough that throughput matters more than per-row cleverness.

things you can ask for

“Find emails for all 400 of these and validate the results with Enrichley”
“Take this longlist csv from Apollo and resolve every address”
“Get every email at this domain, then load the good ones into Lemlist”

works well with Icypeas

Apollo
the upstream list Icypeas works through
Enrichley
a second opinion on the risky and catch-all verdicts
Lemlist
run email and LinkedIn once the list is clean

What your agent reads before it touches Icypeas

Every tool ships with a written playbook, and the agent loads it before the first call. Auth, rate limits, what each call costs, which actions need your approval, and the mistakes worth avoiding. It is the difference between an agent that knows the tool and one that guesses at it.

Read the Icypeas docs →

Show the raw playbookwritten for the agent

HOW in lib/icypeas.py. Docs cached at reference/docs/icypeas/raw/.

Auth & config

Base URL: https://app.icypeas.com/api · Auth: header Authorization: <API_KEY> (env ICYPEAS_API_KEY; never hardcode). Rate limit ~30 req/min.
⚠️ Signature mode: Icypeas also documents an HMAC-signed auth (API key + secret → per-request signature). This adapter uses the simple Authorization-key mode shown in getting-started; if your account requires signing, add the signature header (see api-doc.icypeas.com/category/api-authorization). Confirm which mode your key needs on the first live pilot.

Async flow

email_search / email_verification / domain_search launch a job (return an id) → poll read_results (POST /bulk-single-searchs/read) or use a webhook.

Handoff

Email-finding/verification layer. Launch searches for a shortlist → poll → validate → ATS/sequencer.

Field notes (production experience)

Field-shape note: these are vendor-native operational notes. The client returns the raw vendor JSON and uses the method names in this file — read field shapes accordingly (no normalized-wrapper / result.data. prefix).

Email search is async: returns SCHEDULED + an _id -> poll read_results by _id for the final email.
Verify before sending: run email verification (~0.1 credit); treat NOT_FOUND and DEBITED_NOT_FOUND as non-deliverable.

Callable surface — `lib/icypeas.py`

Import: from lib.icypeas import Icypeas → instantiate Icypeas() (reads key from env). Base: https://app.icypeas.com/api. Generic passthrough: request(method, path, *, params, json).

domain_search(payload: dict) -> dict — POST /domain-search — find emails for a domain (async).
email_search(payload: dict) -> dict — POST /email-search — launch an email-finder search (async). Returns a job id.
email_verification(payload: dict) -> dict — POST /email-verification — verify an email (async).
read_results(payload: dict) -> dict — POST /bulk-single-searchs/read — poll results for launched searches (by id/filters).