# Finding emails from an agent

Find emails for one person, many, a whole list or the first campaign, from the API or an assistant, with a daily limit per key.

An assistant or a script can find emails the same way the app does. A lookup costs one email credit only when an address comes back. If nothing is found, the credit is refunded.

## Find many

`POST /v1/finder/email_lookups` takes up to 100 prospect ids. In the MCP, use `recruit_find_emails`. Send `save_first: true` to save unsaved people first, which is free, so one call saves and finds.

With a background job runner, the people are queued and the call answers at once. Without one, the call looks up as many as fit in its time and lists the rest in `not_started`. Ask again for those.

Anyone who isn't on your account, who asked to be removed, or who you've marked off-limits is skipped. Nobody skipped is charged.

## A whole list or saved filter

1. `GET /v1/finder/email_runs/quote` says who would be looked up and the most it can cost.
2. `POST /v1/finder/email_runs` starts the run and returns an id.
3. `GET /v1/finder/email_runs/{id}` says how it is going, for example `Found 31 of 50. 19 credits refunded.` You can read it from a later conversation.

In the MCP, `recruit_find_emails_for_filter` shows the quote as its card, and `recruit_email_run` reads the run.

## The first campaign

`POST /v1/finder/first_campaign/find_emails` (MCP: `recruit_find_first_campaign_emails`) looks up the people the draft left out for lack of an address, at most 20. It sends nothing.

## Type one in, or choose between two

`POST /v1/finder/prospects/{id}/add_email` puts an address you already know on a person. It's free and stored as unverified. `POST /v1/finder/prospects/{id}/choose_email` picks which of their addresses every send goes to. That's free too.

## A daily limit on a key

A key can carry a daily limit on email lookups and on searches, so a runaway loop stops. A lookup that finds nothing still counts, because we still looked. At the limit the API answers 429 `key_daily_cap_reached` with a `Retry-After` for when the count starts again at 00:00 UTC. A founder sets the limit on the key in RecruitAffiliates.ai. `GET /v1/finder/credits/key_cap` shows the limit and today's use.

## When credits run out

The answer says which credits ran out and when they refill. Nothing was charged.