Email Waterfall and Verification Orchestrator

Finds a work email for each contact by chaining several finder providers, verifies every result, and returns real per-provider spend instead of hiding it behind a credit abstraction.

Bring your own keys. You supply your own Findymail, Prospeo, Icypeas, Reoon and BounceBan keys. We supply none, we never see your credits, and you pay your providers directly at your own rates.

Why this exists

Clay's Work Email waterfall works, and it hides what each provider cost you behind Clay credits. That is the top recorded complaint about its pricing. This returns the per-provider detail: which entry answered, what it consumed, how long it took, and what your balance actually moved by.

Two things Clay structurally does not do, and this does:

• Real per-provider attribution. Units per provider per endpoint, every attempt logged, plus your observed balance movement read from each provider's own account endpoint before and after the run.
• A per-provider circuit breaker. A provider that runs out of credit or fails auth is disabled once for the rest of the run instead of being retried on every contact.

What you get back

One row per input contact, always, including the ones where nothing was found, plus a run summary row.

Field	What it is
email	The work email found, or null
email_status	valid, catch_all, catch_all_resolved, unknown, unverified, invalid, not_found and a few run states
found_by	The registry entry that answered, for example findymail.search_business_profile#linkedin_url. The identifier binding is part of the id on purpose
chain_position	Which position in your order returned it
verification_source	Which verifier's answer stands
verification_degraded	True when the primary verifier failed and the chain fell back
providers_attempted	Every entry tried, with binding, outcome, latency and units consumed
provider_units_used	Credits this row consumed from your accounts

invalid appears only when a verification provider actually looked and said the address will not deliver. A verifier that failed, timed out or was out of credit never produces invalid, because a verification failure is not evidence that an address is dead.

Give it a LinkedIn URL if you have one

Measured on 300 contacts, one key, one hour:

Input	Hit rate
LinkedIn URL	13.7%
Full name plus company domain	9.3%

14 of the hits were unique to the LinkedIn binding and 1 to name plus domain. Same provider, same hour, only the input field changed. Supply every identifier you have; the chain uses the best one each provider accepts and never wastes a call on a provider whose required field you did not supply.

Hit rates are cohort dependent. Those numbers are from one B2B cohort and yours will differ.

Input

{
  "contacts": [
    {
      "id": "your-own-id",
      "full_name": "Satya Nadella",
      "company_domain": "microsoft.com",
      "linkedin_url": "https://www.linkedin.com/in/satyanadella/"
    }
  ],
  "providerKeys": { "findymail": "...", "prospeo": "...", "bounceban": "..." },
  "maxProviderUnits": 500
}

A single contact is an array of one. contacts and providerKeys are also accepted as JSON strings, because Clay sends every input as a string.

Set maxProviderUnits. It is a hard ceiling on the provider credits a run may consume from your accounts. This actor spends your money, not ours.

Supply providerRates with your own per-unit costs and the summary reports dollars at your rates. Leave it out and it reports units only. With your own keys we do not know your plan tier or your negotiated rate, and we will not assume one.

The default chain

1. findymail.search_business_profile#linkedin_url
2. findymail.search_name#name_domain
3. prospeo.enrich_person#any

Then verification, after each finder that returns an address rather than once at the end, because providers do not agree on what "found" means.

Icypeas is included but off by default. In 300 independent contacts it returned zero hits that Findymail had not already found, and its result-read endpoint is limited to 30 calls per minute, which puts a floor of roughly 33 minutes under a 1,000-row batch. Add icypeas.email_search#name_domain to providerOrder if you want it; its bulk path is implemented and is much faster for large batches.

No regional presets ship. We have no regional accuracy data, and shipping presets without it would be inventing them.

Consensus threshold

Default 0, matching Clay's default. Worth knowing: Clay's "threshold for duplicate results" is not a consensus vote. Clay's own documentation describes it as an early-exit cost control that stops the waterfall when the same address keeps failing validation across providers. They are different features and should not be confused.

No provider keys?

The actor still runs, pushes a summary row explaining which capabilities were unavailable, charges nothing and exits cleanly. It never treats a missing key as a crash.

Every key you do supply is validated for free before any paid call. A provider whose key is missing, invalid or out of credit is dropped from the chain and reported, rather than failing per contact.

Cost

Compute is negligible for this shape because it waits on APIs rather than crawling: measured at well under a tenth of one percent of a typical per-result price in batch. Your real cost is your own provider credits, which is exactly what the summary reports.

Personal email

Out of scope. This finds work emails only.

Built by Mamba Labs.