Email Lookup API: Define the Contract for a Name-to-Address Match

Name and company-domain inputs

Hunter’s Email Finder documentation, checked September 2026, supports a company domain with first_name and last_name, or full_name. It also accepts company as an alternative to domain. Hunter gives the domain precedence when both are supplied. Your input record should preserve what the caller actually selected, rather than replace the original company with whichever organization appears later.

Anymail Finder documents a similar name-and-company route, using domain or company_name. Start your adapter with a small input contract: a person identifier in your own system, the submitted name, the requested company domain, and whether a different employer is allowed. These are proposed application fields, not a vendor request schema. They let you distinguish searching a particular account from finding a person wherever they now work.

Do you already know the email domain? Prefer that to a loosely entered organization name. Hunter explicitly describes the domain input as avoiding company-name conversion. If you only have a company name, retain that uncertainty instead of presenting the resolved domain as something the user confirmed.

Lookup versus mailbox verification

A lookup begins before you have an address. Mailbox verification begins with an address to evaluate. Some lookup responses contain a verification result, but that extra information does not remove the original matching question: did the search return this person at the company you requested?

For a workflow alongside OKKI Go, define that destination record first. The useful output is an address associated with the intended account under a stated rule. An address string on its own leaves the application unable to distinguish a successful account match from a broader person search.

Provenance, confidence labels, and freshness

Hunter documents sources for an address found publicly online. Within those sources, extracted_on marks the first discovery date and last_seen_on the most recent discovery date. Neither definition says when a person joined the requested company. Store the source date as an observation date; if your application needs current employment, leave that requirement unresolved until you have evidence for it.

Hunter’s Email Finder reference describes score as an estimated probability of validity for accept-all addresses. That is a conditional meaning, not a company-match score. You should not convert it into a universal probability that the requested person works at the submitted account. A threshold can only answer the question the score was designed to measure.

Anymail Finder’s person response documents person_company_name, person_full_name, and person_job_title as LinkedIn-derived fields, populated when the email was found through LinkedIn. Otherwise they are null. This is useful context for a fallback result, but a null company field should not become an invented company match. Keep the distinction between a supplied input and a returned profile attribute.

The practical comparison is therefore field by field: what was requested, what was returned, where supporting context came from, and what each date or label describes. Missing context may still be acceptable for a human-assisted search. You have a weaker basis for automatically attaching that address to a fixed account.

No-match and error responses

Anymail Finder defines email as the discovered address or null when none is found, and email_status includes not_found. Its valid_email field is populated only for a valid result. Use the documented outcome to distinguish a completed search with no address from a response that still contains a candidate. Do not populate your address field with a guessed pattern after a no-match response.

A missing result needs its own application outcome, such as “search completed; no address returned.” That wording leaves room to correct the input or investigate elsewhere. It does not claim the person has no work email. Anymail Finder also documents blacklisted as a request or policy restriction; preserve that reason instead of collapsing every empty address into the same no-match bucket.

Missing sources, changed employers, and rate limits

If you requested a specific employer, keep the fallback result outside the accepted address field until the association is resolved. Record the returned company context where available and the reason for the hold. If your task explicitly permits any employer, the same result can remain eligible under that broader rule. Do not silently switch between those rules based on whether the response contains an email.

Can you explain a missing source? Treat that gap just as explicitly. Hunter promises source URLs when an address is publicly found; that does not make an absent URL evidence of a current employer. If you require a public citation, hold an uncited result for review. A rule that permits other discovery methods should say so, without relabeling the result as publicly sourced.

You also need to separate lookup failures from company mismatches. Hunter documents invalid name and domain parameters, plus a claimed_email restriction. Correct a malformed request at the input layer; preserve a processing restriction as a reason to stop. Neither is a discovery result that can fill your contact record.

Have you received the result, or just an acknowledgment? Completion depends on delivery mode. Anymail Finder’s webhook documentation says the immediate response supplies a request_id. The later webhook carries the correlation value in x-request-id and the equivalent synchronous status in x-response-status. Store the pending request before you wait for its result. You have not found an address merely because the server acknowledged the request.

When you design the queue, size concurrency against the selected endpoint’s current published limits rather than a generic assumption about lookup APIs. Hunter’s documented Finder limit is 15 requests per second and 500 per minute. Track requests still pending separately from searches completed without a match; otherwise operational delay becomes indistinguishable from missing contact data.

Store the reason for acceptance with the address

You need two related records: the lookup attempt and the accepted address association. For the attempt, retain your local request identifier, submitted name and company, endpoint/version, time requested, and original provider outcome. Add the vendor request identifier when the delivery mode supplies one. You recorded when you asked. That timestamp cannot tell you when the underlying address was observed.

When you accept an association, record the address, the account it belongs to under your rule, the available provenance, and a short acceptance reason. For a held result, record the missing condition instead. These are application design recommendations. They do not imply either vendor exposes every item as a response field.

• Accept: the completed result meets the requested person/company constraint and required evidence is present.
• Hold: an address was returned, but the employer association is unexplained.
• No match: the provider completed the lookup without an address; leave the address field empty.
• Pending: an asynchronous acknowledgment arrived; wait for the correlated result.

Which measure will tell you this works? Count accepted account matches, held company mismatches, completed no-matches and pending requests separately. You can use these proposed categories to assess your integration; they are not claimed vendor performance figures. They show whether the integration is completing the intended discovery task instead of merely accumulating nonempty strings.

If you inspect each result yourself, you can tolerate more missing context. Automatic account enrichment needs a stricter acceptance rule. Choose an email lookup API whose documented response lets you express that rule, and preserve the explanation with the address. If the explanation is unavailable, keep the result unresolved rather than manufacture certainty in your adapter.