Icypeas
Find and verify emails in bulk, without babysitting it.
Icypeas is a contact enrichment tool, and one of the 52 tools hyreflow connects to Claude, ChatGPT and other AI assistants. Through hyreflow, an AI agent can run 4 actions, all of which look something up. Paid Icypeas actions cost 0.1 to 0.5 credits per result or per request, from your hyreflow credit balance, so you need no Icypeas account.
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.
What can you ask Claude or ChatGPT to do with Icypeas?
With hyreflow connected, you ask for the outcome in plain language and the assistant runs Icypeas for you. For example:
Which Icypeas actions can an AI agent run through hyreflow?
Through hyreflow, an AI agent can run 4 Icypeas actions, all of which look something up. Paid Icypeas actions cost 0.1 to 0.5 credits per result or per request, from your hyreflow credit balance, so you need no Icypeas account.
| Icypeas action | What it does | Cost through hyreflow |
|---|---|---|
| Domain search | Looks something up | 0.5 credits per request |
| Email search | Looks something up | 0.5 credits per result |
| Email verification | Looks something up | 0.1 credits per request |
| Read results | Looks something up | free |
One credit is priced on the pricing page. The full price list for every tool is in the pricing tables.
Which hyreflow skills use Icypeas?
One hyreflow skill calls Icypeas as part of the run. A skill is a whole pipeline your agent already knows, end to end.
How does an AI agent know how to use Icypeas?
hyreflow ships a written playbook for Icypeas, 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: headerAuthorization: <API_KEY>(envICYPEAS_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-> pollread_resultsby_idfor the final email. - Verify before sending: run email verification (~0.1 credit); treat
NOT_FOUNDandDEBITED_NOT_FOUNDas 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).ping() -> dict— BYOK key-verification probe. Icypeas' subscription endpoint requires the account email, so this launches a minimal email-search (returns a job id) to confirm the key authenticates — ICYPEAS credits are charged on a found result, so a junk lead is typically free vendor-side, but NOT guaranteed. hyreflow charges 0 for this probe (unit: free).read_results(payload: dict) -> dict— POST /bulk-single-searchs/read — poll results for launched searches (by id/filters).subscription_information(email: str | None = None) -> dict— POST /a/actions/subscription-information — plan + remaining credits: {plan, status, credits, quotas: {daily}, currency} on the caller's own Icypeas account; requires the workspace's own Icypeas key. Requires that account's email in the body — a wrong email 401s.
Questions about Icypeas and hyreflow
Can I use Icypeas inside Claude or ChatGPT?
Yes. hyreflow is a connector for Claude, ChatGPT and other AI assistants. Once hyreflow is connected, you ask for the outcome in plain language and the assistant calls Icypeas for you. hyreflow exposes 4 Icypeas actions this way.
Do I need my own Icypeas account to use it with hyreflow?
No. hyreflow holds the Icypeas account and bills each action from your hyreflow credits.
What does Icypeas cost through hyreflow?
Paid Icypeas actions cost 0.1 to 0.5 credits per result or per request, from your hyreflow credit balance, so you need no Icypeas account. 1 action is free. hyreflow can show the cost of a paid action before it runs.
How do I connect Icypeas to an AI agent over MCP?
Add the hyreflow MCP server to your assistant and sign in. hyreflow calls the Icypeas API directly and exposes its actions as tools the assistant can run, so there is no separate Icypeas server to install.
Put Icypeas to work from one prompt
Connect hyreflow to Claude or ChatGPT and ask for the outcome. It reads the playbook above before it makes a single call.