How to Manage Leads

Kaname surfaces potential leads from synced mail using AI classification on every mailbox that writes to your thread store (Gmail or IMAP/SMTP). The CRM → Hot Leads view is a pipeline board: hot signals (threads flagged before you convert them) plus Kanban columns for leads by stage. CRM → Leads lists all leads; opening a lead shows notes, timeline, follow-ups, and thread links.

What is a lead in Kaname?

A lead is a contact (email) tied to a CRM product (one of your apps) and optionally to one or more threads. Leads can be:

• AI-captured — the classifier scores threads after new mail arrives and may create or update crm_lead rows and categorized-email rows (including the hot_leads lane).
• Manually added — use Add to CRM on a thread in the web inbox, or convert a signal on the Hot Leads board.

Thread and message IDs in the database may still be named gmail_* in places; they store the external provider thread/message id for Gmail or IMAP.

Navigating Hot Leads and Leads

• CRM → Hot Leads — Kanban or list: Signals column (hot categorized threads not yet leads), then stages New, Interested, Follow-up, Won, Lost. Drag a lead card between columns to update stage (maps to stored statuses new, contacted/replied, negotiation/stale, won, lost). Use smart chips (e.g. waiting for reply, follow-up today) and search to narrow the board. You can dismiss a false-positive signal so it stays hidden for you.
• CRM → Leads — Full lead list with optional search (q) and filters; archived leads stay out of the default list unless you include them.

There is no assignee field on leads in the current product; ownership is implicit (your account).

How AI lead capture works

After sync inserts email_message rows, a crm_classification_job may run and update CRM tables. Signals for Hot Leads come from categorized email rows (e.g. category hot_leads) produced in that pipeline — not from Gmail-only APIs on the classify path.

Manually adding a lead (web)

From a thread in Inbox:

1. Open the thread.
2. Use Add to CRM (product picker + upsert). A crm_conversation link is created when thread and mailbox are known.

From Hot Leads:

1. Find the thread under Signals.
2. Click Convert / save — posts to POST /api/crm/leads/upsert with product, contact email, external thread id, and mailbox.

Lead stages (PRD vs database)

The UI shows PRD names; the API persists existing enum values for compatibility with workers and mobile clients:

Dragging onto Interested from replied keeps replied (same column). The API also exposes prd_stage_label / prd_pipeline_column on lead JSON for consistent labels everywhere.

Following up on a lead

Follow-ups use POST/GET/PATCH /api/crm/follow-ups (thread + mailbox scoped). The body accepts mailboxId (preferred) or mailboxEmail (resolved to a mailbox for the signed-in user). The CRM → Follow-ups page lists pending items.

Due reminders: configure a cron job to call GET /api/cron/crm-follow-up-reminders with the Bearer secret CRM_FOLLOW_UP_NOTIFY_CRON_SECRET (or CRM_CLASSIFICATION_CRON_SECRET where configured as fallback). The handler sends deduplicated FCM notifications for due follow-ups.

Lead detail (web)

Open a lead from the board or list. You’ll see:

• Contact line, PRD stage pill, tags, urgency, optional deal value
• AI summary block when present
• Relationship — notes (add/delete), timeline (stage changes and link events), follow-ups for the lead

Closing / removing a lead

• Move the card to Won or Lost, or PATCH status via API.
• Remove from active pipeline: DELETE /api/crm/leads/[id] soft-archives (archived_at). Optional ?purge=1 hard-deletes where allowed.

IMAP / Gmail QA checklist (sign-off)

For one Gmail and one IMAP mailbox each, verify:

1. Hot signal appears on the board after relevant mail syncs.
2. Convert signal → lead appears in the correct column; crm_conversation exists.
3. Drag stage → PATCH persists; list and detail show the new stage label.
4. Create a follow-up → chip/due surfaces; open thread from lead link with mailboxId when present.
5. Suggested reply loads for that thread (IMAP + Gmail).
6. Dismiss signal → signal hidden after refresh.
7. Cron reminder path configured in staging/prod if you rely on push.

After you send (web)

When you send a reply through POST /api/mail/send in an existing thread, Kaname may enqueue “no reply” follow-ups for that thread’s linked lead if the CRM product has followup_after_send enabled and there is not already a pending follow-up for that thread (same behavior as the mobile pipeline).

Tips

Review Hot Leads regularly — convert real opportunities and dismiss noise so the classifier-backed view stays trustworthy.

Use notes on close — for Lost, a short note in the Relationship panel helps you spot patterns later.