@agent-native/core 0.122.4 → 0.123.0

package/corpus/core/docs/content/template-mail-agent.mdx

@@ -0,0 +1,114 @@
+---
+title: "Mail: Talking to the Agent"
+description: "What the agent can see and do in Mail, useful prompts by task, and when it reaches past the built-in actions to a raw Gmail, Calendar, or HubSpot API call."
+---
+
+# Talking to the Agent
+
+Mail's agent reads and acts through the same actions the UI uses, so anything you can click, you can also ask for. This page covers what the agent sees automatically, prompts organized by task, and the cases where it needs to reach further than a built-in action — useful whether you're a day-to-day user or building on top of Mail.
+
+## How the agent sees your screen
+
+The agent knows which view you're in, which thread is open, and which message is focused on every turn — you don't have to describe "this email" or "the current thread." If you're mid-reply and ask "help me word this," it reads your open compose draft (including subject and body-in-progress) before answering, and writes the update back so you see it appear live in the compose panel. If you're on the draft queue, it sees the queue and whichever request is selected.
+
+## Useful prompts by task
+
+**Triage**
+
+- "Summarize my unread emails."
+- "Find the latest thread from Alice about the budget."
+- "Archive all Netlify bot emails older than a week."
+- "Mark everything in my inbox as read except anything from my manager."
+
+**Draft and reply**
+
+- "Draft a reply that politely declines."
+- "Make this draft more formal."
+- "Send this Friday at 9am instead of now."
+- "Ask Jane if Thursday works, using my usual signature."
+
+**Search and context**
+
+- "Who is this, and what deals do they have open?" (pulls HubSpot context on the sender)
+- "Did they open the proposal I sent last week?"
+- "What did we agree to in the last thread with Acme?"
+
+**Automate**
+
+- "Auto-archive anything from newsletters I don't reply to."
+- "Add a Gmail filter that stars anything from my biggest client."
+- "Queue a draft asking Marcus for the Q3 numbers — he can send it himself."
+
+## Selection-aware edits
+
+Select text in an open email or draft and hit `Cmd+I` — that selection travels with your next message, so "make this punchier" or "translate just this paragraph" operates on exactly what you highlighted, not the whole thread.
+
+## When the agent reaches past a built-in action
+
+Mail's built-in actions cover the common cases: read, search, draft, send, star, archive, schedule, automate. When the exact Gmail endpoint, search operator, HubSpot object, or Google Calendar field a built-in action doesn't expose is what you actually need, the agent can call the real provider API directly — the same escalation path exists for Gmail, Google Calendar, and HubSpot.
+
+<Diagram id="doc-block-mail7" title="Escalating past a built-in action" summary={"When a canned action can't express the exact endpoint or filter, the agent looks up the real API shape and calls it directly, staging large results instead of pasting them into the conversation."}>
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-node">
+    Built-in action isn't enough<br /><small class="diagram-muted"
+      >missing filter, endpoint, or field</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent"
+      >provider-api-catalog · provider-api-docs</span
+    ><small class="diagram-muted">looks up the real API shape</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">
+    provider-api-request<br /><small class="diagram-muted"
+      >Gmail · Calendar · HubSpot</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">
+    Large result? stageAs<br /><small class="diagram-muted"
+      >query-staged-dataset instead of pasting the dump</small
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
+Not every provider the sidebar shows is reachable this way: Gong, Pylon, and Apollo integrations are read-only UI sidebar panels in Mail today — the agent can pull HubSpot data through this path, but not those three, even though they're wired in for other Agent-Native apps.
+
+<Callout tone="info">
+
+**Sending is the one place the agent always stops and asks.** Drafting, editing, scheduling, and queuing all happen freely; the moment the agent is about to actually send an email, it pauses for your explicit approval first. See [Drafting, Scheduling & the Draft Queue](/docs/template-mail-drafts-and-queue) for the full send flow.
+
+</Callout>
+
+## Extensions: adding a custom widget to Mail
+
+Mail has a slot in the email contact sidebar (below the built-in CRM panels) where an installed extension can render its own widget — a sandboxed mini-app with access to the same actions and app data. Build or install one from **Settings → Extensions**; see the [extensions](/docs/extensions) docs for how to write one.
+
+## What's next
+
+- [**Inbox, Search & Automations**](/docs/template-mail-inbox) — the full shortcut list and automation rules
+- [**Drafting, Scheduling & the Draft Queue**](/docs/template-mail-drafts-and-queue) — composing, scheduling, and the queue in detail
+- [**Developer Guide**](/docs/template-mail-developers) — every action referenced above, and how to add your own
+- [**Mail overview**](/docs/template-mail) — back to the app summary

package/corpus/core/docs/content/template-mail-developers.mdx

@@ -0,0 +1,356 @@
+---
+title: "Mail: Developer Guide"
+description: "Actions, data model, routes, and customization points for the Mail template — everything you need to fork or extend the agent-native Gmail client."
+---
+
+# Developer Guide
+
+This page is for anyone forking the [Mail](/docs/template-mail) template or extending it: the action inventory, data model, route map, and the places to start when you want to change how Mail works.
+
+## Quick start
+
+Create a new workspace with the Mail template:
+
+```bash
+npx @agent-native/core@latest create my-mail --standalone --template mail
+```
+
+See [Getting Started](/docs/getting-started) for the rest of the local setup (`cd`, `pnpm install`, `pnpm dev`).
+
+To connect Gmail in dev, you need a Google OAuth client:
+
+1. Open [Google Cloud Console](https://console.cloud.google.com/) and create a project.
+2. Enable the **Gmail API** under APIs & Services → Library.
+3. Create OAuth 2.0 credentials (type: Web application). Add `http://localhost:8085/_agent-native/google/callback` as an authorized redirect URI.
+4. Copy the Client ID and Client Secret into the Settings page of the running app, then click **Connect Google account**.
+
+Tokens are stored in the framework `oauth_tokens` SQL table and refresh automatically. You can connect multiple Gmail accounts once the first is set up.
+
+## Action inventory
+
+Every operation is a TypeScript file in `templates/mail/actions/`, auto-mounted at `POST /_agent-native/actions/:name`. Actions marked **UI-only** are still real actions — the frontend calls them through `useActionQuery`/`useActionMutation` — but are declared `agentTool: false`, so the agent cannot call them as a tool.
+
+**Reads & triage**
+
+- `list-emails` / `search-emails` — query mail by view or Gmail search syntax
+- `get-email` / `get-thread` — full body/metadata for a message or thread
+- `find-contact` — resolve a name/partial address to a real email from Google Contacts + interaction history
+- `view-screen` — what the user is currently looking at (navigation, email list, open thread, draft queue)
+- `view-composer` — list all open compose drafts
+- `refresh-list` — make the UI refetch after a mutation
+
+**Message state**
+
+- `star-email` / `archive-email` / `unarchive-email` / `trash-email` / `untrash-email` / `move-email`
+- `mark-read` (bulk `scope: "all-unread"` cleanup) / `mark-thread-read`
+- `bulk-archive` — date-based archive, local demo mailbox only
+- `export-emails` — export a view as JSON, local demo mailbox only
+
+**Drafting & sending**
+
+- `manage-draft` — create/update/delete a `compose-{id}` draft
+- `send-email` — real Gmail send; `needsApproval: true`
+- `create-attachment-upload` — short-lived owner-bound upload URL for a local attachment
+- `manage-snippets` — saved reply snippets for the compose slash menu
+- `get-mail-settings` / `update-mail-settings` — signature and writing style
+- `import-gmail-signature` — convert the user's Gmail HTML signature to Markdown
+- `get-mail-preferences` / `update-mail-preferences` — UI-only, the broader preferences object (appearance, reading, tracking, drafting) backing Settings
+
+**Scheduling**
+
+- `send-scheduled-email-now` / `cancel-scheduled-email` — agent-callable
+- `create-scheduled-job` / `list-scheduled-jobs` / `update-scheduled-job` — UI-only, back the Scheduled view and snooze/send-later flow
+
+**Draft queue**
+
+- `list-org-members` — resolve valid `ownerEmail` values
+- `queue-email-draft` — create a queued draft for a member to review; returns `reviewUrl`
+- `list-queued-drafts` / `update-queued-draft` / `open-queued-draft` / `send-queued-drafts`
+
+**Automations & Gmail filters**
+
+- `manage-automations` / `trigger-automations` — agent-facing natural-language triage rules
+- `create-automation` / `list-automations` / `update-automation` / `delete-automation` — UI-only, back the Settings automations list (same `automation_rules` table)
+- `get-automation-settings` / `update-automation-settings` — UI-only, the engine/model used to evaluate rules
+- `manage-gmail-filters` — native Gmail filters (list/create/replace/delete); Gmail has no update endpoint, so `replace` creates a new filter and deletes the old one
+
+**CRM & contacts**
+
+- `get-hubspot-contact` — the only first-class CRM action; Gong, Pylon, and Apollo are read-only UI sidebar panels only
+- `get-integration-statuses` — UI-only, which optional sidebar integrations are configured (no credential values)
+
+**Tracking**
+
+- `get-tracking` — open/click stats for a sent message by Gmail message ID
+
+**Aliases (UI-only)**
+
+- `create-alias` / `list-aliases` / `update-alias` / `delete-alias` — all `agentTool: false`; manage aliases from Settings
+
+**Navigation & calendar**
+
+- `navigate` — move the UI to a view, thread, settings section, queued draft, or compose draft
+- `respond-calendar-invite` — accept/decline/tentative a Google Calendar invite from Mail
+
+**Provider API escalation**
+
+- `provider-api-catalog` / `provider-api-docs` / `provider-api-request` — raw Gmail, Google Calendar, and HubSpot API calls (`MAIL_PROVIDER_API_IDS` resolves to exactly these three providers)
+- `list-staged-datasets` / `query-staged-dataset` / `delete-staged-dataset` — manage and query large `stageAs` scan results
+
+## Data model
+
+Email itself lives in Gmail (or the local `getSetting("local-emails")` fallback when no account is connected) — Mail's own SQL tables hold what Gmail doesn't: scheduling, contact ranking, automation rules, tracking, snippets, and the queue.
+
+<DataModel
+  id="doc-block-mail8"
+  title="Mail SQL tables"
+  summary={
+    "Email itself lives in Gmail. Mail's own SQL tables hold scheduled jobs, contact interaction frequency, automation rules, send-tracking events, snippets, and the queued-draft workflow. OAuth tokens are a framework table."
+  }
+  entities={[
+    {
+      id: "scheduled_jobs",
+      name: "scheduled_jobs",
+      note: "Snoozes and scheduled sends",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "type", type: "enum", note: "snooze | send_later" },
+        { name: "ownerEmail", type: "string" },
+        { name: "emailId", type: "string", nullable: true },
+        { name: "threadId", type: "string", nullable: true },
+        { name: "accountEmail", type: "string", nullable: true },
+        { name: "payload", type: "json" },
+        { name: "runAt", type: "datetime", note: "epoch ms to run at" },
+        {
+          name: "status",
+          type: "enum",
+          note: "pending | processing | done | cancelled",
+        },
+      ],
+    },
+    {
+      id: "contact_frequency",
+      name: "contact_frequency",
+      note: "Interaction-frequency ranking behind find-contact",
+      fields: [
+        { name: "id", type: "id", pk: true, note: "ownerEmail:contactEmail" },
+        { name: "ownerEmail", type: "string" },
+        { name: "contactEmail", type: "string" },
+        { name: "contactName", type: "string" },
+        { name: "sendCount", type: "integer" },
+        { name: "receiveCount", type: "integer" },
+        { name: "lastContactedAt", type: "datetime" },
+      ],
+    },
+    {
+      id: "automation_rules",
+      name: "automation_rules",
+      note: "Natural-language triage rules",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "ownerEmail", type: "string" },
+        { name: "domain", type: "string", note: '"mail" | "calendar"' },
+        { name: "name", type: "string" },
+        { name: "condition", type: "string", note: "natural language" },
+        { name: "actions", type: "json", note: "AutomationAction[]" },
+        { name: "enabled", type: "boolean" },
+      ],
+    },
+    {
+      id: "queued_email_drafts",
+      name: "queued_email_drafts",
+      note: "Teammate/Slack-requested drafts awaiting owner review",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "orgId", type: "string" },
+        {
+          name: "ownerEmail",
+          type: "string",
+          note: "org member who reviews/sends",
+        },
+        { name: "requesterEmail", type: "string" },
+        { name: "toRecipients", type: "string" },
+        { name: "subject", type: "string" },
+        { name: "body", type: "markdown" },
+        { name: "source", type: "enum", note: "agent | slack | ui | api" },
+        {
+          name: "status",
+          type: "enum",
+          note: "queued | in_review | sent | dismissed",
+        },
+        { name: "sentMessageId", type: "string", nullable: true },
+      ],
+    },
+    {
+      id: "email_tracking",
+      name: "email_tracking",
+      note: "Open-pixel events for sent messages",
+      fields: [
+        { name: "pixelToken", type: "string", pk: true },
+        { name: "messageId", type: "string" },
+        { name: "ownerEmail", type: "string" },
+        { name: "opensCount", type: "integer" },
+        { name: "firstOpenedAt", type: "datetime", nullable: true },
+        { name: "lastOpenedAt", type: "datetime", nullable: true },
+      ],
+    },
+    {
+      id: "email_link_tracking",
+      name: "email_link_tracking",
+      note: "Link-click events for sent messages",
+      fields: [
+        { name: "clickToken", type: "string", pk: true },
+        { name: "pixelToken", type: "string", fk: "email_tracking.pixelToken" },
+        { name: "url", type: "string" },
+        { name: "clicksCount", type: "integer" },
+      ],
+    },
+    {
+      id: "snippets",
+      name: "snippets",
+      note: "Saved reply snippets for the compose slash menu",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "ownerEmail", type: "string" },
+        { name: "name", type: "string" },
+        { name: "body", type: "string" },
+      ],
+    },
+    {
+      id: "mail_inventory_cursors",
+      name: "mail_inventory_cursors",
+      note: "Short-lived continuation state for MCP inventory reads (metadata only, no bodies or credentials)",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "ownerEmail", type: "string" },
+        { name: "queryFingerprint", type: "string" },
+        { name: "state", type: "json" },
+        { name: "expiresAt", type: "datetime" },
+      ],
+    },
+    {
+      id: "oauth_tokens",
+      name: "oauth_tokens",
+      note: "Framework table — one row per connected Google account",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "provider", type: "string", note: '"google"' },
+        { name: "accountEmail", type: "string" },
+        { name: "accessToken", type: "string" },
+        { name: "refreshToken", type: "string" },
+      ],
+    },
+  ]}
+  relations={[
+    {
+      from: "email_tracking",
+      to: "email_link_tracking",
+      kind: "1-n",
+      label: "click events",
+    },
+  ]}
+/>
+
+Settings and ephemeral state live outside these tables: `getSetting("local-emails")` (fallback mailbox), `getSetting("labels")`, `getUserSetting(email, "mail-settings")` (signature, writing style, tracking preferences), `getUserSetting(email, "aliases")`, and the `application_state` table (`navigation`, `navigate`, `compose-{id}`, `refresh-signal`).
+
+Emails flowing through the API have the shape `{ id, threadId, from, to, cc, subject, snippet, body, date, isRead, isStarred, isArchived, isTrashed, labelIds, accountEmail, attachments }`.
+
+<FileTree
+  id="doc-block-mail9"
+  title="Mail template layout"
+  entries={[
+    {
+      path: "actions/",
+      note: "defineAction operations — the single source of truth",
+    },
+    { path: "app/routes/", note: "React Router file routes" },
+    { path: "app/components/email/", note: "Inbox, thread, and compose UI" },
+    { path: "app/components/layout/", note: "App shell and navigation" },
+    {
+      path: "app/pages/SettingsPage.tsx",
+      note: "Aliases, automations, tracking, Slack intake",
+    },
+    {
+      path: "app/pages/DraftQueuePage.tsx",
+      note: "Queue list and detail view",
+    },
+    {
+      path: "server/db/schema.ts",
+      note: "Drizzle schema for Mail's own tables",
+    },
+    {
+      path: "server/lib/",
+      note: "Gmail/Calendar/HubSpot clients, jobs, queued-drafts",
+    },
+    { path: ".agents/skills/", note: "Agent guidance for each Mail subsystem" },
+  ]}
+/>
+
+<AnnotatedCode
+  id="doc-block-mail10"
+  title="A short action: star-email.ts"
+  filename="templates/mail/actions/star-email.ts"
+  language="ts"
+  code={
+    'export default defineAction({\n  description: "Star or unstar one or more emails.",\n  schema: z.object({\n    id: z.string().optional().describe("Email ID(s), comma-separated"),\n    unstar: z.coerce.boolean().optional(),\n    accountEmail: z.string().optional(),\n  }),\n  run: async (args) => {\n    const ids = args.id?.split(",").map((s) => s.trim()).filter(Boolean);\n    if (!ids || ids.length === 0) throw new Error("--id is required");\n    const isStarred = args.unstar !== true;\n\n    // Bulk path: one Gmail batchModify call per account instead of\n    // one modify call per message when Gmail is connected.\n    if (ids.length > 1 && (await isConnected(ownerEmail))) {\n      const { succeeded, failed } = await gmailBatchModifyByAccount(...);\n      // ...\n    } else {\n      for (const id of ids) {\n        await toggleStar({ id, ownerEmail, isStarred, accountEmail });\n      }\n    }\n\n    await writeAppState("refresh-signal", { ts: Date.now() });\n    return `${isStarred ? "Starred" : "Unstarred"} ${succeeded}/${ids.length} email(s)`;\n  },\n});'
+  }
+  annotations={[
+    {
+      lines: "1-6",
+      label: "One file, three surfaces",
+      note: "This file is simultaneously an agent tool, a CLI command (`pnpm action star-email`), and a typed frontend hook (`useActionMutation`).",
+    },
+    {
+      lines: "10-13",
+      label: "Bulk vs. one-by-one",
+      note: "Multiple ids against a connected Gmail account batch into one API call per account instead of one call per message — the same pattern archive-email and mark-read use.",
+    },
+    {
+      lines: "18",
+      label: "Refresh after mutating",
+      note: "Mail mutations write refresh-signal so the UI refetches; actions that already signal internally (mark-thread-read, move-email) skip this.",
+    },
+  ]}
+/>
+
+## Routes reference
+
+- `/_index.tsx` — redirects to the default inbox view
+- `/$view.tsx` — a list view (`inbox`, `starred`, `sent`, `drafts`, `scheduled`, `archive`, `trash`, etc.)
+- `/$view.$threadId.tsx` — a list view with a specific thread open
+- `/email` — the embedded thread preview used in agent chat
+- `/agent` — a full-page Agent tab (`AgentTabsPage`)
+- `/draft-queue` and `/draft-queue/:id` — the draft queue list and detail view
+- `/settings` — account connections, tracking, automations, aliases, Slack intake
+- `/team` — redirects to `/settings?section=team`
+- `/extensions` — installed extension widgets (redirects to `/settings#extensions` when no extension id is given)
+
+## Customizing it
+
+Mail is yours to change. Everything important lives in a handful of places — start there.
+
+**Adding an agent capability.** Add a new file under `templates/mail/actions/` using `defineAction`. Your action becomes an agent tool, a CLI command (`pnpm action <name>`), and a typed frontend hook surface through `useActionQuery` / `useActionMutation`. Look at `templates/mail/actions/star-email.ts` for a short example or `templates/mail/actions/manage-automations.ts` for one with multiple sub-actions. See the [actions](/docs/actions) docs for the full pattern.
+
+**Changing the UI.** Routes are in `templates/mail/app/routes/` and components in `templates/mail/app/components/email/` and `templates/mail/app/components/layout/`. The app uses shadcn/ui primitives from `app/components/ui/` and Tabler Icons — stick to those.
+
+**Changing how the agent behaves.** Agent guidance lives in `templates/mail/AGENTS.md` and the skills in `templates/mail/.agents/skills/` (`inbox-reads-and-triage`, `email-drafts`, `draft-queue`, `contacts-and-crm`, `mail-backends`, `inbox-automations`, `provider-api-scans`, and others). Agent behavior is changed by editing markdown — not code.
+
+**Changing data or settings.** Mail's own schema is in `templates/mail/server/db/schema.ts`. Settings reads and writes go through `readSetting`/`writeSetting` (or the per-user `getUserSetting`/`putUserSetting`) from `@agent-native/core/settings`. Application state (navigation, drafts, one-shot commands) uses `readAppState`/`writeAppState` from `@agent-native/core/application-state`.
+
+**Adding a new automation action type.** Extend the action schema in `templates/mail/actions/manage-automations.ts` and the executor in `templates/mail/actions/trigger-automations.ts`.
+
+**Adding a sidebar CRM integration.** Follow the pattern in `server/handlers/gong.ts`, `pylon.ts`, or `apollo.ts` for a read-only sidebar panel, or register a new provider in `MAIL_PROVIDER_API_IDS` (`server/lib/provider-api.ts`) to make it reachable through `provider-api-request` as well.
+
+**Changing keyboard shortcuts.** Keybind handlers live in `templates/mail/app/components/email/` — search for `useHotkeys` or `addEventListener("keydown"` to find where each key is wired.
+
+Ask the agent to make any of these changes for you. The agent can edit its own source — see [Self-Modifying Code](/docs/key-concepts#agent-modifies-code).
+
+## What's next
+
+- [**Mail overview**](/docs/template-mail) — the app summary
+- [**Inbox, Search & Automations**](/docs/template-mail-inbox) — the user-facing triage and automation flows
+- [**Drafting, Scheduling & the Draft Queue**](/docs/template-mail-drafts-and-queue) — the user-facing drafting flow
+- [**Talking to the Agent**](/docs/template-mail-agent) — prompts and the provider-API escalation path
+- [**Actions**](/docs/actions) — the action system this page's inventory is built on
+- [**Extensions**](/docs/extensions) — building a widget for Mail's contact-sidebar slot
+- [**Automations**](/docs/automations) — the event-triggered engine mail's auto-triage rules build on

package/corpus/core/docs/content/template-mail-drafts-and-queue.mdx

@@ -0,0 +1,103 @@
+---
+title: "Mail: Drafting, Scheduling & the Draft Queue"
+description: "Compose, schedule, and send email in Mail, queue a draft for a teammate to review before it sends, and track opens and clicks on what you send."
+---
+
+# Drafting, Scheduling & the Draft Queue
+
+This page covers writing and sending email in [Mail](/docs/template-mail): composing and replying, scheduling a send or snoozing a message, letting a teammate or Slack request queue a draft for you to approve, and checking whether a sent email was opened. It's written for anyone using Mail, not just developers.
+
+## Composing and replying
+
+Ask the agent to draft or reply, or hit `C` to compose yourself. A few things shape what gets written:
+
+- **Your signature.** If you've configured one in Settings → Drafting, it's appended automatically and used exactly as written — the agent never invents one from your name or profile.
+- **Your writing style.** An optional style note in Settings steers the agent's tone toward how you actually write.
+- **Snippets.** Save a canned response once and insert it from the compose slash menu any time — "add my pricing blurb" works whether you or the agent wrote the snippet.
+- **Attachments.** Attach a file you've already uploaded in the compose panel; the agent only attaches what you've explicitly provided, never something it invents or fetches on your behalf.
+
+The agent never sends without asking first. Drafting and editing happen freely; the moment it's time to actually send, Mail pauses for your explicit go-ahead — this is one of the few places in the app that works this way, because sending mail is hard to undo.
+
+## Scheduling a send or snoozing a message
+
+Ask to "send this Monday at 9am" or "snooze this until tomorrow afternoon" and Mail schedules it rather than sending immediately. Scheduled sends and snoozes both show up under the Scheduled view, where you can fire one off early or cancel it before it runs.
+
+## Queuing a draft for a teammate to review
+
+Teammates — and people messaging your team's Slack — can ask the agent to prepare an email on your behalf without ever sending it themselves. The request lands in your **draft queue** at `/draft-queue`, where you review, edit, and send it yourself.
+
+<WireframeBlock id="doc-block-mail6">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='display:flex;flex-direction:column;min-height:480px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px;padding:14px 16px;border-bottom:1.4px solid var(--wf-line)'><strong>Draft queue</strong><span class='wf-pill'>Review</span><span class='wf-pill'>Requested</span><div style='flex:1'></div><button class='primary'>New request</button></div><div style='display:grid;grid-template-columns:280px 1fr;gap:0;flex:1;min-height:0'><div style='display:flex;flex-direction:column;gap:6px;padding:10px;border-right:1.4px solid var(--wf-line)'><div class='wf-box' style='display:flex;flex-direction:column;gap:4px;padding:8px'><span class='wf-pill accent' style='width:fit-content'>queued</span><strong>Follow up with Acme</strong><span class='wf-muted'>from Priya Mehta</span></div><div class='wf-box' style='display:flex;flex-direction:column;gap:4px;padding:8px'><span class='wf-pill' style='width:fit-content'>in review</span><strong>Reschedule kickoff</strong><span class='wf-muted'>from #sales-slack</span></div><div class='wf-box' style='display:flex;flex-direction:column;gap:4px;padding:8px'><span class='wf-pill' style='width:fit-content'>sent</span><strong>Thanks for the intro</strong><span class='wf-muted'>from Marcus Tang</span></div></div><div style='display:flex;flex-direction:column;gap:10px;padding:16px'><div class='wf-muted'>To: acme-team@acme.com</div><div class='wf-muted'>Subject: Follow up with Acme</div><div class='wf-card' style='min-height:120px'>Hi team, following up on last week's call...</div><div style='display:flex;gap:8px'><button>Edit in compose</button><button class='primary'>Send</button><button>Dismiss</button></div></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+<Diagram id="doc-block-mail5" title="Draft queue lifecycle" summary={"A teammate or Slack request never sends directly — it queues a draft that only the owner can edit and send."}>
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-node">
+    Teammate or Slack request<br /><small class="diagram-muted"
+      >"ask the agent to draft..."</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">queued</span
+    ><small class="diagram-muted">queued_email_drafts row</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">
+    Owner opens /draft-queue<br /><small class="diagram-muted">in_review</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">
+    Owner edits and sends<br /><small class="diagram-muted">sent</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
+A few things worth knowing about the queue:
+
+<Callout tone="warning">
+
+Only the draft's **owner** — or an org owner/admin — can edit or send a queued draft. The person who requested it cannot edit or send their own request, even though they created it. Once a draft is sent, it's frozen; ask for a new one instead of editing a sent draft.
+
+</Callout>
+
+Requests from Slack verify the requester's real email address before queuing anything — if that verification isn't set up, Slack intake won't guess an address from a display name, and the request won't queue.
+
+## Tracking opens and clicks
+
+If you've turned on open or click tracking in Settings, every email you send after that gets a tracking pixel and per-link click tokens. Ask "did they open my email?" and the agent reports open count and per-link click stats. Emails sent before you turned tracking on simply report as untracked — that's expected, not an error.
+
+## Aliases: sending from a different address
+
+Configure aliases — named groups of email addresses you can send as — from Settings → Aliases. Aliases are managed from that Settings page directly; the agent can read and use an alias you've set up, but adding or editing one is a manual step in Settings today.
+
+## What's next
+
+- [**Inbox, Search & Automations**](/docs/template-mail-inbox) — triaging what arrives before you reply
+- [**Talking to the Agent**](/docs/template-mail-agent) — prompts for drafting, scheduling, and the queue
+- [**Developer Guide**](/docs/template-mail-developers) — the draft, scheduling, and queue action reference
+- [**Mail overview**](/docs/template-mail) — back to the app summary