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 MCP is available to the agent after connecting it from the CRM
sidebar. Users without a workspace can add a personal connection there. In
a workspace, shared setup is only shown to organization owners and admins;
Gong also requires its tech admin to register the MCP integration. Connected
Gong tools inherit the authorizing user's Gong permissions. Use those tools
when available for Gong questions.
- Gong, Pylon, and Apollo CRM sidebar panels still use server route handlers
(
server/handlers/gong.ts, pylon.ts, apollo.ts) that read their own
per-session API keys 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 first-party Mail action for Gong calls, Pylon tickets, or
Apollo person lookups.
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 for Gong data and no Gong MCP tools are connected, say
plainly that Mail has no first-party Gong action; do not imply
provider-api-request can reach it.
- App API-key connections are UI-only. Gong, Pylon, Apollo, and HubSpot
keys are saved through
/api/* routes; there are no save-*-key actions.
The agent can read HubSpot data via get-hubspot-contact but cannot
configure API-key connections on the user's behalf.
- 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.
1---2name: contacts-and-crm3description: >-4 Resolve a name or partial address to a real email and enrich a thread with5 CRM/contact context (HubSpot, Apollo) before drafting or triaging. Use6 when the user names a person instead of an email, or asks "who is this"7 / "what deals/tickets does this contact have".8metadata:9 source: https://skillmd.com/skills/builderio/contacts-and-crm10---1112# Contacts and CRM1314## Resolving a recipient1516Use `find-contact` before asking the user for someone's email address, and17before guessing a pattern like `firstinitiallastname@company.com`.1819`find-contact` is backed by `loadContactsForEmail`, which merges Google People20API "connections" (boosted `count += 5`) and "other contacts" with real21send/receive history. Because it sees actual interaction history, it is strictly22better than guessing an address pattern.2324- `find-contact --query="<name or partial email>" --limit=5` matches25 case-insensitively against name and email, splitting the query into26 whitespace-separated terms that must ALL match (`"jacqueline lamb"` requires27 both terms present).28- Results are sorted by `count`, an interaction-frequency score. Google People29 API "connections" (explicitly saved contacts) start at `count: 5`; "other30 contacts" (people the user has emailed but not saved) start lower. Sending31 or receiving mail increments a real `sendCount`/`receiveCount` in the32 `contact_frequency` SQL table, so the top match is usually the person the33 user actually means.34- If `find-contact` returns zero matches, tell the user — do not invent an35 email address. A wrong guess either bounces or, worse, silently reaches the36 wrong inbox.37- Results are cached per-owner for a few minutes (`contactCache` in38 `server/handlers/emails.ts`). A contact added in Google Contacts moments ago39 may not appear immediately; that's expected, not a bug to route around.4041## CRM enrichment4243- `get-hubspot-contact --email=<address>` is the only first-class CRM action.44 It returns contact fields (name, phone, company, title, lifecycle stage,45 lead status) plus up to 5 associated deals and up to 5 associated tickets,46 reading the user's own HubSpot API key configured in Settings. If no key is47 configured it returns `{ error: "HubSpot API key not configured" }` —48 surface that plainly rather than treating it as "no CRM data exists."49- **Gong MCP is available to the agent after connecting it from the CRM50 sidebar.** Users without a workspace can add a personal connection there. In51 a workspace, shared setup is only shown to organization owners and admins;52 Gong also requires its tech admin to register the MCP integration. Connected53 Gong tools inherit the authorizing user's Gong permissions. Use those tools54 when available for Gong questions.55- Gong, Pylon, and Apollo CRM sidebar panels still use server route handlers56 (`server/handlers/gong.ts`, `pylon.ts`, `apollo.ts`) that read their own57 per-session API keys from `appStateGet`. None of the three is registered in58 Mail's `MAIL_PROVIDER_API_IDS` (see59 `listProviderApiIdsForTemplateUse("mail")` in `server/lib/provider-api.ts`,60 which currently resolves to `gmail`, `google_calendar`, and `hubspot` only).61 This means:62 - There is no first-party Mail action for Gong calls, Pylon tickets, or63 Apollo person lookups.64 - `provider-api-request` will refuse `provider: "gong"`, `"pylon"`, or65 `"apollo"` in this app even though those provider ids exist in the shared66 catalog — they're enabled for other templates (e.g. Analytics), not Mail.67 - If the user asks for Gong data and no Gong MCP tools are connected, say68 plainly that Mail has no first-party Gong action; do not imply69 `provider-api-request` can reach it.70- **App API-key connections are UI-only.** Gong, Pylon, Apollo, and HubSpot71 keys are saved through `/api/*` routes; there are no `save-*-key` actions.72 The agent can read HubSpot data via `get-hubspot-contact` but cannot73 configure API-key connections on the user's behalf.74- For HubSpot data outside contact lookup (deals search, ticket creation,75 property metadata), use `provider-api-catalog` / `provider-api-docs` with76 `provider: "hubspot"`, then `provider-api-request` — `get-hubspot-contact`77 only covers the single "lookup by email" shape.7879## Related Skills8081- `email-drafts` — use resolved contacts and CRM context when composing.82- `draft-queue` — resolving the right `ownerEmail` teammate uses83 `list-org-members`, a separate lookup from `find-contact`.84- `actions` — the shared provider API pattern for `provider-api-request`.