Contacts And Crm

---
name: contacts-and-crm
description: >-
  Resolve a name or partial address to a real email and enrich a thread with
  CRM/contact context (HubSpot, Apollo) before drafting or triaging. Use
  when the user names a person instead of an email, or asks "who is this"
  / "what deals/tickets does this contact have".
---

# Contacts and CRM

## Resolving a recipient

Use `find-contact` before asking the user for someone's email address, and
before guessing a pattern like `firstinitiallastname@company.com`.

`find-contact` is backed by `loadContactsForEmail`, which merges Google People
API "connections" (boosted `count += 5`) and "other contacts" with real
send/receive history. Because it sees actual interaction history, it is strictly
better than guessing an address pattern.

- `find-contact --query="<name or partial email>" --limit=5` matches
  case-insensitively against name and email, splitting the query into
  whitespace-separated terms that must ALL match (`"jacqueline lamb"` requires
  both terms present).
- Results are sorted by `count`, an interaction-frequency score. Google People
  API "connections" (explicitly saved contacts) start at `count: 5`; "other
  contacts" (people the user has emailed but not saved) start lower. Sending
  or receiving mail increments a real `sendCount`/`receiveCount` in the
  `contact_frequency` SQL table, so the top match is usually the person the
  user actually means.
- If `find-contact` returns zero matches, tell the user — do not invent an
  email address. A wrong guess either bounces or, worse, silently reaches the
  wrong inbox.
- Results are cached per-owner for a few minutes (`contactCache` in
  `server/handlers/emails.ts`). A contact added in Google Contacts moments ago
  may not appear immediately; that's expected, not a bug to route around.

## CRM enrichment

- `get-hubspot-contact --email=<address>` is the only first-class CRM action.
  It returns contact fields (name, phone, company, title, lifecycle stage,
  lead status) plus up to 5 associated deals and up to 5 associated tickets,
  reading the user's own HubSpot API key configured in Settings. If no key is
  configured it returns `{ error: "HubSpot API key not configured" }` —
  surface that plainly rather than treating it as "no CRM data exists."
- **Gong, Pylon, and Apollo are UI-only in Mail.** They have server route
  handlers (`server/handlers/gong.ts`, `pylon.ts`, `apollo.ts`) that power the
  CRM sidebar panel in the email view, each reading its own per-session API
  key from `appStateGet`. None of the three is registered in Mail's
  `MAIL_PROVIDER_API_IDS` (see `listProviderApiIdsForTemplateUse("mail")` in
  `server/lib/provider-api.ts`, which currently resolves to `gmail`,
  `google_calendar`, and `hubspot` only). This means:
  - There is no agent action for Gong calls, Pylon tickets, or Apollo person
    lookups in Mail.
  - `provider-api-request` will refuse `provider: "gong"`, `"pylon"`, or
    `"apollo"` in this app even though those provider ids exist in the shared
    catalog — they're enabled for other templates (e.g. Analytics), not Mail.
  - If the user asks the agent to pull a Gong call or Pylon ticket from Mail,
    say plainly that integration is visible in the UI sidebar only today; do
    not fabricate a result or imply `provider-api-request` can reach it.
- **Provider API-key connections are Settings-UI only.** Gong, Pylon, Apollo,
  and HubSpot keys are saved through raw `/api/*` routes from the Settings UI —
  there are no `save-*-key` actions. The agent can read HubSpot data via
  `get-hubspot-contact` but cannot configure any of these connections on the
  user's behalf; ask the user to add the key in Settings.
- For HubSpot data outside contact lookup (deals search, ticket creation,
  property metadata), use `provider-api-catalog` / `provider-api-docs` with
  `provider: "hubspot"`, then `provider-api-request` — `get-hubspot-contact`
  only covers the single "lookup by email" shape.

## Related Skills

- `email-drafts` — use resolved contacts and CRM context when composing.
- `draft-queue` — resolving the right `ownerEmail` teammate uses
  `list-org-members`, a separate lookup from `find-contact`.
- `actions` — the shared provider API pattern for `provider-api-request`.