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

GET /v1/finder/email_runs/quote says who would be looked up and the most it can cost.
POST /v1/finder/email_runs starts the run and returns an id.
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.

Was this page helpful?