Email Lookup

Email Lookup lets a deployed agent find a professional address, assess a known address, or discover addresses associated with a company domain. Agent steps call the typed ctx.sapiom.search.emailSearch capability; Sapiom supplies the authenticated cloud connection when the deployed agent runs.

Choose the lookup

What the agent already knows	Recommended operation
A person’s name and company or domain	`emailSearch.findEmail(...)`
A complete email address	`emailSearch.verifyEmail(...)`
A company domain and optional role filters	`emailSearch.domainSearch(...)`

Finding and verifying answer different questions. findEmail looks for a likely address; verifyEmail assesses an address the agent already has. Neither grants permission to contact the person.

Find, then assess, an address

findEmail requires an organization—domain or company—and a person—fullName or both firstName and lastName:

const found = await ctx.sapiom.search.emailSearch.findEmail({
  fullName: input.fullName,
  domain: input.companyDomain,
});

if (!found.email) {
  return { found: false };
}

const assessment =
  await ctx.sapiom.search.emailSearch.verifyEmail({
    email: found.email,
  });

return {
  found: true,
  email: found.email,
  findScore: found.score ?? null,
  status: assessment.status ?? null,
  result: assessment.result ?? null,
  verificationScore: assessment.score ?? null,
  smtpCheck: assessment.smtpCheck ?? null,
  acceptAll: assessment.acceptAll ?? null,
  disposable: assessment.disposable ?? null,
  webmail: assessment.webmail ?? null,
};

findEmail returns email: null when it has no match. Its optional score is 0–100 and can be accompanied by person, company, profile, and verification metadata. Treat absent fields as unknown.

Verification is an assessment at one point in time, not a delivery guarantee. In particular, an accept-all domain makes a positive SMTP result weaker, and mailbox state can change after the lookup.

Search a company domain

Use domain search when the agent needs a filtered set of known addresses rather than one named person:

const result = await ctx.sapiom.search.emailSearch.domainSearch({
  domain: input.companyDomain,
  limit: 20,
  type: "personal",
  seniority: ["senior", "executive"],
  department: ["engineering"],
});

return {
  domain: result.domain,
  organization: result.organization ?? null,
  pattern: result.pattern ?? null,
  acceptAll: result.acceptAll ?? null,
  people: result.emails,
};

limit defaults to 10 and accepts up to 100. Domain results can include type, confidence, name, position, department, and seniority, but every enrichment field is optional.

Test the behavior locally

Local Run replaces all three email lookup methods with deterministic fixture data. It does not query or verify an address. Override the exact paths for the branches the step exercises:

{
  "version": 1,
  "steps": {
    "enrich-contact": {
      "search.emailSearch.findEmail": {
        "email": "[email protected]",
        "score": 91,
        "firstName": "Ada",
        "lastName": "Lovelace",
        "company": "Example"
      },
      "search.emailSearch.verifyEmail": {
        "email": "[email protected]",
        "status": "valid",
        "result": "deliverable",
        "score": 95,
        "smtpCheck": true,
        "acceptAll": false,
        "disposable": false,
        "webmail": false
      }
    }
  }
}

Test the not-found, uncertain, and accept-all branches with separate fixtures. After each run, assert the terminal output and require both unusedStubs and stubWarnings to be empty. A passing Local Run proves the decision against fixture data, not that an address exists or can receive mail.

Manage usage and result quality

Avoid calling all three operations when one answers the task. Cache only as long as your privacy and freshness policy allows, keep the lookup evidence with the decision, and send only after the agent’s messaging policy approves the recipient.

Use the signed-in capability catalog for current availability, limits, and pricing rather than copying a per-request rate into the agent.

Use capabilities in a step Work from the installed ctx.sapiom TypeScript contract.

Test locally Exercise match, miss, and uncertainty branches with fixtures.

Deploy an agent Build an immutable cloud version before making real lookups.

Inspect a run Review lookup failures without logging personal data.