Gmail Lead Desk ( gmail-lead-desk) 📧#

Gmail Lead Desk — standalone sales and customer-support Gmail workflows via the AISA gateway.

One skill: connect Gmail, run whitelisted tools, triage inbox, draft replies, archive deals — no other skill required.

Quick start#

bash

export AISA_API_KEY="your-key"   # get at https://aisa.one

Pre-flight checks (do first, stop if fails):

1. AISA_API_KEY is set — if not, ask the user to set it before any API call.
2. user_id is known — use the Gmail address the user provides. If not yet known, ask: "What Gmail address should I use as your identity?"
3. Gmail is ACTIVE — run Workflow 0 if connected_account_id is missing or not ACTIVE.

• Base URL: https://api.aisa.one
• Auth: Authorization: Bearer $AISA_API_KEY
• Windows: use curl.exe

OAuth and tools/execute: references/connect_and_execute.md

When to use#

• Connect or reconnect Gmail via OAuth
• Scan unread leads needing follow-up
• Summarize inquiry/support threads (CRM format)
• Draft replies from sales templates (default: do not send)
• Archive won deals with labels
• User mentions: unanswered, follow-up, inquiry, quote, draft, archive, lead, connect Gmail

When NOT to use#

• Non-Gmail apps (Slack, GitHub, etc.) — out of scope
• Proactive new-mail automation — not MVP; see references/workflows.md § Future
• Bulk permanent delete, filter creation — disabled unless user explicitly requests

Intent → Workflow Quick Reference#

User intentWorkflowReferenceConnect Gmail / OAuth / authorize0 Connect Gmailreferences/connect_and_execute.mdUnanswered / follow-up / unreadA Unread lead scanreferences/workflows.md § ASummarize / summary / summarize threadB Thread summaryreferences/workflows.md § BReply for me / draft reply / write emailC Draft (no send)references/workflows.md § CConfirm send / send nowC-send Send after confirmreferences/workflows.md § C-sendArchive / deal closedD Label and archivereferences/workflows.md § D

Run Workflow 0 first if Gmail is not connected ( ACTIVE connected_account_id).

---

Workflow 0 — Connect Gmail (summary)#

1. GET /auth_configs?toolkit_slug=gmail → auth_config_id
2. GET /connected_accounts?toolkit_slugs=gmail&user_ids={user_id} — reuse ACTIVE if present
3. Else confirm, then POST /connected_accounts/link → user opens redirect_url
4. Poll every 3–5 s until status is ACTIVE; save connected_account_id
   • Timeout after ~2 min (24 polls): stop polling, tell user "OAuth not completed — please try again or check the browser tab."
   • DISCONNECTED / REVOKED: re-run from step 3.

Full steps: references/connect_and_execute.md

---

Core Workflows (summary)#

A — Unread lead scan#

1. Resolve connected_account_id (Workflow 0).
2. GMAIL_FETCH_EMAILS with sales default query — see workflows.md.
3. Table: Sender | Subject | Days waiting | thread_id | Suggested action.
4. Do not send at end of this workflow.

B — Thread summary (CRM-ready)#

1. GMAIL_FETCH_MESSAGE_BY_THREAD_ID; sort by internalDate.
2. Fixed sections: customer, need, budget/timeline, next action, attachments ( unverified when inferred).

C — Template draft (default: no send)#

1. Load thread (B); confirm recipient, tone, quote/link.
2. GMAIL_REPLY_TO_THREAD or GMAIL_CREATE_EMAIL_DRAFT; empty subject when thread_id set.
3. Return draft_id + preview.

C-send — Send only on explicit request#

• User says send / confirm send / send now.
• Show full To/Cc/subject/body; confirm; then GMAIL_SEND_DRAFT or GMAIL_SEND_EMAIL.

D — Archive and label#

1. GMAIL_LIST_LABELS → Label_* IDs only.
2. GMAIL_CREATE_LABEL if needed (confirm).
3. Sample ≤5 messageIds + count → GMAIL_BATCH_MODIFY_MESSAGES.

Never guess tool_slug. Whitelist: references/tool_whitelist.md.

---

Safety#

ActionRuleDefault after A/B/CDraft only — no auto-sendOAuth link / create auth configConfirm with userCreate draftConfirm recipient and threadSendExplicit user request + show To/CcBatch label/archive≤5 sample IDs + total countBatch delete / filtersRefuse in MVP unless explicit cleanup requestPrivacyNo uploading full mailbox externally; attachments need consentRate limitsConcurrency ≤10; backoff on 429

Gmail pitfalls: references/gmail_gotchas.md.

---

Reference routing#

NeedFileAPI key, OAuth, executereferences/connect_and_execute.mdSales workflows A–Dreferences/workflows.mdmessage_id, labels, draftsreferences/gmail_gotchas.mdAllowed tool slugsreferences/tool_whitelist.md

Lookup order: intent → Workflow 0 if needed → workflows.md → tool_whitelist.md → GET /tools/{tool_slug} → POST /tools/execute/{tool_slug}.

---

Troubleshooting#

SymptomActionAISA_API_KEY not setAsk user to run export AISA_API_KEY="..." before any API calluser_id unknownAsk "What Gmail address should I use as your identity?"No Gmail connectionWorkflow 0 in connect_and_execute.mdOAuth poll timeout (>2 min)Tell user to check browser tab; re-run Workflow 0 step 3Invalid id valueSee gmail_gotchas.mdLabel not appliedUsed display name — GMAIL_LIST_LABELS for idNew thread on replySubject set on draft — leave subject emptysuccessful: false``connect_and_execute.md §4 + re-fetch tool schemaDeprecated GMAIL_LIST_MESSAGESUse GMAIL_FETCH_EMAILS