@agent-native/core 0.88.0 → 0.90.1

package/corpus/templates/mail/.agents/skills/email-drafts/SKILL.md

@@ -1,3 +1,12 @@
+---
+name: email-drafts
+description: >-
+  Create, edit, and send email drafts through compose-{id} application state,
+  manage-draft, and send-email. Use when composing, replying, forwarding,
+  attaching files, applying signatures/writing style, or checking open/click
+  tracking on sent mail.
+---
+
 # Email Drafts
 
 Create, edit, and manage email drafts. Each draft is stored as an application state entry keyed `compose-{id}`. The UI refreshes through the framework polling/query invalidation path and updates the compose panel automatically.
@@ -68,35 +77,32 @@ Before creating or rewriting a draft, read the user's drafting settings with `pn
 
 The compose panel opens automatically when any compose draft exists. When the last draft is deleted, the panel closes.
 
-## Creating a New Draft
-
-Use the manage-draft script or write directly:
+## Use the `manage-draft` action, not raw `writeAppState`
+
+`manage-draft` is the real action surface for compose drafts (`action`:
+`create` | `update` | `delete` | `delete-all`). Prefer it over hand-writing
+`compose-{id}` state directly — it does things a raw write will not:
+
+- **Sanitizes the id.** IDs must match `/^[a-zA-Z0-9_-]{1,64}$/`
+  (`sanitizeDraftId`); an invalid id on create silently falls back to a
+  timestamp-based id instead of failing.
+- **Appends the signature automatically on create** via
+  `appendSignatureToBody(body, signature)`, reading the configured signature
+  from `mail-settings`. This is idempotent (no-ops if the signature text is
+  already in the body) and signature-aware of quoted content — it inserts the
+  signature before any `— On ... wrote:` or `— Forwarded message —` block, not
+  after it. `update` does NOT re-append the signature — only `create` does, so
+  edit calls should not need to touch the signature themselves.
+- **Returns a `deepLink`** (via `link()`) that opens the exact draft in the
+  real Mail compose UI (`embedApp`/`mcpApp` resource with contact autocomplete,
+  attachments, and send controls) — surface this link when running outside the
+  first-party UI (e.g. from an MCP host).
 
 ```bash
 pnpm action manage-draft --action=create --to=jane@example.com --subject="Quick question" --body="Hi Jane,\n\nJust wanted to follow up on..."
-```
-
-Or from code:
-```ts
-import { writeAppState } from "@agent-native/core/application-state";
-await writeAppState("compose-draft1", {
-  id: "draft1",
-  to: "jane@example.com",
-  subject: "Quick question",
-  body: "Hi Jane,\n\nJust wanted to follow up on...",
-  mode: "compose",
-});
-```
-
-## Editing an Existing Draft
-
-Read the current draft, modify it, write it back:
-
-```ts
-import { readAppState, writeAppState } from "@agent-native/core/application-state";
-const draft = await readAppState("compose-draft1");
-draft.body = "Hi Jane,\n\nI refined the draft as requested...";
-await writeAppState("compose-draft1", draft);
+pnpm action manage-draft --action=update --id=draft1 --body="Hi Jane,\n\nI refined the draft as requested..."
+pnpm action manage-draft --action=delete --id=draft1
+pnpm action manage-draft --action=delete-all
 ```
 
 ## Listing All Drafts
@@ -111,13 +117,6 @@ import { listAppState } from "@agent-native/core/application-state";
 const drafts = await listAppState("compose-");
 ```
 
-## Closing a Draft
-
-```ts
-import { deleteAppState } from "@agent-native/core/application-state";
-await deleteAppState("compose-draft1");
-```
-
 ## Attaching Files
 
 The `send-email` action accepts an optional `attachments` array. Each entry must reference a file that was previously uploaded via the media-upload endpoint (`/api/media/upload`). Pass the server-side `filename` (the key returned by the upload endpoint, e.g. `abc123.pdf`), and optionally `originalName` (display name for the recipient) and `mimeType`. The attachment plumbing resolves the file from the upload store (falling back to `data/uploads/`) and includes it as a MIME multipart attachment in the outgoing Gmail message. Files are never sent speculatively — only attach what the user has explicitly provided and confirmed.
@@ -134,6 +133,39 @@ Example:
 }
 ```
 
+Attachments are resolved eagerly, before Gmail is touched: if any referenced
+upload can't be read, `send-email` throws immediately (nothing is sent) rather
+than sending a partial message. If you see that error, the fix is re-uploading
+via the media endpoint, not retrying the same `filename`.
+
+## What Actually Happens on Send
+
+`send-email` requires explicit user intent to send — it is `needsApproval:
+true` and pauses for human approval before the real Gmail call happens. It
+branches on whether the user has a connected Google account:
+
+- **Connected:** resolves an access token (refreshing if the account's
+  `expiry_date` is within 60s), resolves reply threading (`inReplyTo` /
+  `References` headers) by fetching the original message metadata when
+  `replyToId` is set, resolves the sender display name via
+  `resolveGoogleSenderIdentity` (caching the result), builds the raw MIME
+  message, and calls the real Gmail send API.
+- **Not connected (no Google account):** synthesizes a fake sent message and
+  appends it to the user's `local-emails` setting so the UI still shows a
+  "Sent" item — this is a demo/fallback path, not a queued real send. Do not
+  tell the user the email left their real inbox in this mode.
+- **Open/click tracking:** if `mail-settings.tracking.opens` or `.clicks` is
+  enabled, `send-email` rewrites the outgoing body with a tracking pixel and
+  per-link click tokens before building the MIME message, and persists the
+  token map keyed by the real Gmail message id. `get-tracking --id=<messageId>`
+  reads back open count and per-link click stats for a previously sent
+  message; it returns `tracked: false` (not an error) for messages that were
+  sent before tracking was enabled or when tracking is off.
+- Multiple connected Google accounts: `send-email`'s optional `account` param
+  picks the sender; when replying, it also tries each connected account until
+  one can fetch the original message, and uses that account as the sender if
+  `account` wasn't explicit.
+
 ## Important Notes
 
 - The `id` field in the JSON MUST match the `{id}` in the key name (`compose-{id}`)
@@ -144,3 +176,12 @@ Example:
 - When the user asks you to "edit" or "improve" a draft, list drafts first, then read and update the relevant one
 - **When called from the compose Generate button:** the context tells you which draft to update (e.g. `compose-abc123`). Always update THAT entry — do NOT create a new one with a different ID. Read, modify, and write back to the same key.
 - **When drafting from scratch (no compose window open):** create a new entry with any unique ID
+
+- The `id` field in the JSON MUST match the `{id}` in the key name (`compose-{id}`)
+- The UI debounces writes by 300ms — if the user is actively typing, your write will be visible after a brief moment
+- Always use valid JSON with proper escaping (especially newlines in body: use `\n`)
+- Multiple drafts can exist simultaneously — each appears as a tab in the compose panel
+- When the user asks you to "draft" or "compose" an email, write a compose entry — don't use the send API directly
+- When the user asks you to "edit" or "improve" a draft, list drafts first, then read and update the relevant one
+- **When called from the compose Generate button:** the context tells you which draft to update (e.g. `compose-abc123`). Always update THAT entry — do NOT create a new one with a different ID. Read, modify, and write back to the same key.
+- **When drafting from scratch (no compose window open):** create a new entry with any unique ID

package/corpus/templates/mail/AGENTS.md

@@ -4,7 +4,8 @@ Mail is an agent-native inbox, drafting, triage, and draft-review app. The agent
 reads messages, helps prioritize, drafts replies, manages queued drafts, and
 updates mail state through actions and application state.
 
-Detailed draft, queue, storage, sync, and UI patterns live in `.agents/skills/`.
+Detailed draft, queue, and contact-resolution patterns live in
+`.agents/skills/`.
 
 ## Core Rules
 
@@ -12,30 +13,113 @@ Detailed draft, queue, storage, sync, and UI patterns live in `.agents/skills/`.
 - Use actions for email reads, labels, settings, drafts, queued drafts, filters,
   scheduling, refresh, and CRM context. Do not edit mail SQL directly unless a
   skill/action explicitly calls for it.
+- **Two mail backends, chosen automatically per user.** When the user has a
+  connected Google account (`isConnected(ownerEmail)`), actions call the real
+  Gmail API. When no account is connected, the same actions fall back
+  transparently to synthetic `local-emails` data stored via `getUserSetting` /
+  `putUserSetting`. Never assume Gmail is connected — actions like
+  `search-emails`, `list-emails`, `get-thread`, `get-email`, and `move-email`
+  branch on this internally, so call them the same way either way.
+- `find-contact` (backed by `loadContactsForEmail`, cached ~a few minutes) is
+  the correct way to resolve a name or partial address to an email before
+  drafting or sending. It merges Google People API "connections" (boosted
+  `count += 5`) and "other contacts" with real send/receive history, and is
+  strictly better than guessing a `firstinitiallastname@company.com` pattern.
+  Never guess an email pattern when `find-contact` returns zero matches — tell
+  the user instead.
+- `get-hubspot-contact` is the only first-class CRM action. Gong, Pylon, and
+  Apollo have server-side lookup handlers (used by the UI's CRM sidebar) but
+  are **not** wired to any agent action and are **not** in Mail's
+  `provider-api-request` catalog (`MAIL_PROVIDER_API_IDS` only resolves to
+  `gmail`, `google_calendar`, and `hubspot` — see `listProviderApiIdsForTemplateUse("mail")`
+  in `server/lib/provider-api.ts`). If the user asks about Gong calls or Pylon
+  tickets from the agent chat, say those providers are UI-only in Mail today;
+  do not claim `provider-api-request` can reach them.
 - Treat provider-specific actions as shortcuts, not capability limits. When the
-  exact Gmail, Google Calendar, or CRM endpoint/filter/pagination/API version
-  matters, use `provider-api-catalog`, `provider-api-docs`, and
+  exact Gmail, Google Calendar, or HubSpot endpoint/filter/pagination/API
+  version matters, use `provider-api-catalog`, `provider-api-docs`, and
   `provider-api-request` against the real provider API. For large scans, stage
-  results with `stageAs` and analyze them with `query-staged-dataset`.
-- Never send mail unless the user explicitly asks to send. Draft or queue review
-  by default.
-- When drafting, first read mail settings for signature and writing style. Use
-  the configured signature exactly when present; do not invent or duplicate it.
-- For teammate/Slack-originated send requests, queue a draft for the owner to
-  review instead of sending directly.
+  results with `stageAs` and analyze them with `query-staged-dataset`
+  (`list-staged-datasets` / `delete-staged-dataset` manage the scratch rows).
+- Never send mail unless the user explicitly asks to send. Draft or queue
+  review by default. `send-email` has `needsApproval: true` — it is the
+  canonical, intentionally rare use of the human-in-the-loop gate in this
+  framework; the loop pauses for approval on every real send. Drafting and
+  queueing are unaffected.
+- When drafting, first read `get-mail-settings` for signature and writing
+  style. Use `signature` exactly when present — draft-writing paths that build
+  a `compose-*` entry (`manage-draft`, `open-queued-draft`) call
+  `appendSignatureToBody` automatically, which is idempotent (skips if the
+  signature is already present) and inserts before any quoted reply/forward
+  content. Never derive a signature from the user's name or connected profile
+  when none is configured.
+- For teammate/Slack-originated send requests, use `queue-email-draft`
+  (`draft-queue` skill), not `send-email` directly. The requester and reviewer
+  must both be members of the active organization; Slack intake resolves the
+  sender's real email via `users.info` (requires `users:read.email` bot scope)
+  before it will queue anything.
 - Never edit the email store to change a draft the user is currently composing;
-  use `compose-{id}` application state or draft actions.
-- After backend mail mutations, refresh the list state/action path so the UI
-  updates.
+  use `manage-draft` or the `compose-{id}` application-state key described in
+  `email-drafts`.
+- After backend mail mutations (archive, trash, star, mark-read, move, send),
+  call `refresh-list` so the UI refetches. Actions that already write
+  `refresh-signal` internally (e.g. `mark-thread-read`, `move-email`,
+  `respond-calendar-invite`) don't need a second call.
 - Use `view-screen` when the active thread, selected message, draft, or queue
   item is unclear.
+- Aliases (Settings → Aliases) and provider API-key connections (Gong, Pylon,
+  Apollo, HubSpot) are managed only through raw `/api/*` routes from the
+  Settings UI — there are no `manage-aliases` or `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.
+
+## Action Map
+
+| Action                                                                                                                                 | Purpose                                                                                |
+| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `search-emails` / `list-emails`                                                                                                        | Query across Gmail or local-fallback data by view/query.                               |
+| `get-email` / `get-thread`                                                                                                             | Full body/metadata for one message or thread.                                          |
+| `find-contact`                                                                                                                         | Resolve a name/partial address to a real email.                                        |
+| `get-hubspot-contact`                                                                                                                  | CRM contact + deals + tickets by email (HubSpot only).                                 |
+| `manage-draft`                                                                                                                         | Create/update/delete a `compose-{id}` draft (signature-aware).                         |
+| `send-email`                                                                                                                           | Real send. `needsApproval: true` — always pauses for human approval.                   |
+| `queue-email-draft` / `list-queued-drafts` / `update-queued-draft` / `open-queued-draft` / `send-queued-drafts`                        | Teammate/Slack draft-review workflow — see `draft-queue`.                              |
+| `mark-read` / `mark-thread-read` / `star-email` / `archive-email` / `unarchive-email` / `trash-email` / `untrash-email` / `move-email` | Per-message or per-thread state changes; most call `refresh-list` internally.          |
+| `manage-gmail-filters`                                                                                                                 | Provider-native Gmail filters (create/replace/delete).                                 |
+| `manage-automations` / `trigger-automations`                                                                                           | Natural-language inbox automation rules.                                               |
+| `respond-calendar-invite`                                                                                                              | Accept/decline/tentative an invite found in Mail.                                      |
+| `get-mail-settings` / `update-mail-settings` / `import-gmail-signature`                                                                | Signature and writing-style settings.                                                  |
+| `manage-snippets`                                                                                                                      | List/create/update/delete saved reply snippets insertable from the compose slash menu. |
+| `get-tracking`                                                                                                                         | Open/click stats for a previously sent, tracked message.                               |
+| `provider-api-catalog` / `provider-api-docs` / `provider-api-request`                                                                  | Raw Gmail, Calendar, or HubSpot API calls beyond the canned actions.                   |
 
 ## Application State
 
 - `navigation` exposes inbox/thread/draft-queue views and selected ids.
-- `compose-{id}` entries represent open compose tabs and draft content.
-- `navigate` moves the UI.
-- Use `get-thread` or equivalent actions for full conversation context.
+- `compose-{id}` entries represent open compose tabs and draft content (see
+  `email-drafts`).
+- `navigate` moves the UI: `view` (`inbox`, `starred`, `sent`, `drafts`,
+  `scheduled`, `archive`, `trash`, `draft-queue`, `settings`), plus `threadId`,
+  `settingsSection` (`drafting`, `automations`, `gmail-filters`, `aliases`,
+  `tracking`, `slack`, `team`), `queuedDraftId`, or `composeDraftId`.
+- Use `get-thread` for full conversation context instead of relying on ambient
+  screen text.
+
+## Scheduling And Automations
+
+- Scheduled sends use job ids prefixed `scheduled-`; `send-scheduled-email-now`
+  and `cancel-scheduled-email` both strip that prefix internally before
+  looking up the job — pass the id as shown to the user either way.
+- `manage-automations` rules match new inbound mail against a natural-language
+  `condition` using AI, then apply `actions` (`label`, `archive`, `mark_read`,
+  `star`, `trash`). Rules run on a per-minute cron automatically;
+  `trigger-automations` forces immediate processing (debounced — a
+  just-triggered run may report "skipped, try again in 30 seconds").
+- Gmail filters (`manage-gmail-filters`) are a distinct, provider-native
+  mechanism from automation rules — filters run inside Gmail itself, apply
+  before automations, and support raw Gmail criteria/actions. Gmail has no
+  filter-update endpoint: the `replace` operation works by creating a new
+  filter and deleting the old one.
 
 ## Skills
 
@@ -43,5 +127,7 @@ Read the relevant skill before deeper work:
 
 - `email-drafts` for composing, signatures, style, replies, and scheduling.
 - `draft-queue` for org review/send workflows.
+- `contacts-and-crm` for resolving recipients and enriching a conversation
+  with CRM/contact context before drafting or triaging.
 - `actions`, `storing-data`, `real-time-sync`, `security`, `frontend-design`,
   and `shadcn-ui` for framework work.

package/corpus/templates/mail/actions/archive-email.ts

@@ -5,6 +5,11 @@ import { summarizeArchiveFailures } from "@shared/archive-errors.js";
 import { z } from "zod";
 
 import { archiveEmail } from "../server/lib/email-state.js";
+import {
+  gmailBatchModifyByAccount,
+  isConnected,
+} from "../server/lib/google-auth.js";
+import { invalidateThreadCache } from "../server/lib/thread-cache.js";
 
 function userFacingActionError(message: string, statusCode: number): Error {
   const error = new Error(message) as Error & { statusCode: number };
@@ -21,6 +26,12 @@ export default defineAction({
       .string()
       .optional()
       .describe("Specific connected account to use"),
+    accountEmails: z
+      .string()
+      .optional()
+      .describe(
+        "Per-id account emails, comma-separated and positionally matched to --id (bulk UI calls only)",
+      ),
     removeLabel: z
       .string()
       .optional()
@@ -31,6 +42,12 @@ export default defineAction({
       .string()
       .optional()
       .describe("Thread ID hint to skip an extra Gmail API round-trip"),
+    threadIds: z
+      .string()
+      .optional()
+      .describe(
+        "Per-id thread ID hints, comma-separated and positionally matched to --id (bulk UI calls only)",
+      ),
   }),
   run: async (args) => {
     const ids = args.id
@@ -45,20 +62,59 @@ export default defineAction({
     const ownerEmail = getRequestUserEmail();
     if (!ownerEmail) throw new Error("no authenticated user");
 
+    const threadIdList = args.threadIds?.split(",").map((s) => s.trim());
+    const accountEmailList = args.accountEmails
+      ?.split(",")
+      .map((s) => s.trim());
+    const threadIdFor = (i: number) => threadIdList?.[i] || args.threadId;
+    const accountEmailFor = (i: number) =>
+      accountEmailList?.[i] || args.accountEmail;
+
     const results: { id: string; success: boolean; error?: string }[] = [];
 
-    for (const id of ids) {
-      try {
-        await archiveEmail({
-          id,
-          ownerEmail,
-          accountEmail: args.accountEmail,
-          removeLabel: args.removeLabel,
-          threadId: args.threadId,
-        });
+    // Bulk path: one Gmail batchModify call per account instead of one
+    // modify call per message. Only applies when Gmail is connected and the
+    // caller isn't resolving a label-view removeLabel (that needs a
+    // per-message label lookup, see archiveEmail's reconciliation notes).
+    if (
+      ids.length > 1 &&
+      !args.removeLabel &&
+      (await isConnected(ownerEmail))
+    ) {
+      const targets = ids.map((id, i) => ({
+        id,
+        threadId: threadIdFor(i),
+        accountEmail: accountEmailFor(i),
+      }));
+      const { succeeded, failed } = await gmailBatchModifyByAccount(
+        ownerEmail,
+        targets,
+        undefined,
+        ["INBOX"],
+      );
+      const threadIdById = new Map(targets.map((t) => [t.id, t.threadId]));
+      for (const id of succeeded) {
+        const tid = threadIdById.get(id);
+        if (tid) invalidateThreadCache(ownerEmail, tid);
         results.push({ id, success: true });
-      } catch (err: any) {
-        results.push({ id, success: false, error: err?.message ?? "failed" });
+      }
+      for (const f of failed)
+        results.push({ id: f.id, success: false, error: f.error });
+    } else {
+      for (let i = 0; i < ids.length; i++) {
+        const id = ids[i];
+        try {
+          await archiveEmail({
+            id,
+            ownerEmail,
+            accountEmail: accountEmailFor(i),
+            removeLabel: args.removeLabel,
+            threadId: threadIdFor(i),
+          });
+          results.push({ id, success: true });
+        } catch (err: any) {
+          results.push({ id, success: false, error: err?.message ?? "failed" });
+        }
       }
     }
 

package/corpus/templates/mail/actions/manage-snippets.ts

@@ -0,0 +1,106 @@
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { eq, and, asc } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+const schema = z.object({
+  operation: z
+    .enum(["list", "create", "update", "delete"])
+    .default("list")
+    .describe("Snippet operation to perform"),
+  id: z.string().optional().describe("Snippet ID (for update/delete)"),
+  name: z
+    .string()
+    .optional()
+    .describe("Short name shown in the compose slash menu"),
+  body: z
+    .string()
+    .optional()
+    .describe("Snippet text inserted into the compose body"),
+});
+
+export default defineAction({
+  description:
+    "List, create, update, or delete reusable email snippets (canned responses) that can be inserted into a compose draft from the slash menu.",
+  schema,
+  run: async (args) => {
+    const { db, schema: dbSchema } = await import("../server/db/index.js");
+
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+
+    switch (args.operation) {
+      case "list": {
+        const rows = await db
+          .select()
+          .from(dbSchema.snippets)
+          .where(eq(dbSchema.snippets.ownerEmail, ownerEmail))
+          .orderBy(asc(dbSchema.snippets.name));
+        return { ok: true as const, snippets: rows };
+      }
+
+      case "create": {
+        if (!args.name?.trim() || !args.body?.trim()) {
+          throw new Error("name and body are required to create a snippet");
+        }
+
+        const now = Date.now();
+        const snippet = {
+          id: nanoid(12),
+          ownerEmail,
+          name: args.name.trim(),
+          body: args.body,
+          createdAt: now,
+          updatedAt: now,
+        };
+
+        await db.insert(dbSchema.snippets).values(snippet);
+        return { ok: true as const, snippet };
+      }
+
+      case "update": {
+        if (!args.id) throw new Error("id is required to update a snippet");
+
+        const updates: Record<string, unknown> = { updatedAt: Date.now() };
+        if (args.name !== undefined) {
+          if (!args.name.trim()) throw new Error("name cannot be empty");
+          updates.name = args.name.trim();
+        }
+        if (args.body !== undefined) updates.body = args.body;
+
+        const [snippet] = await db
+          .update(dbSchema.snippets)
+          .set(updates)
+          .where(
+            and(
+              eq(dbSchema.snippets.id, args.id),
+              eq(dbSchema.snippets.ownerEmail, ownerEmail),
+            ),
+          )
+          .returning();
+
+        if (!snippet) throw new Error("snippet not found");
+        return { ok: true as const, snippet };
+      }
+
+      case "delete": {
+        if (!args.id) throw new Error("id is required to delete a snippet");
+
+        await db
+          .delete(dbSchema.snippets)
+          .where(
+            and(
+              eq(dbSchema.snippets.id, args.id),
+              eq(dbSchema.snippets.ownerEmail, ownerEmail),
+            ),
+          );
+
+        return { ok: true as const, id: args.id };
+      }
+
+      default:
+        throw new Error(`Unknown operation "${args.operation}"`);
+    }
+  },
+});

package/corpus/templates/mail/actions/mark-read.ts

@@ -4,6 +4,10 @@ import { getRequestUserEmail } from "@agent-native/core/server";
 import { z } from "zod";
 
 import { markRead } from "../server/lib/email-state.js";
+import {
+  gmailBatchModifyByAccount,
+  isConnected,
+} from "../server/lib/google-auth.js";
 
 export default defineAction({
   description: "Mark one or more emails as read or unread.",
@@ -17,6 +21,12 @@ export default defineAction({
       .string()
       .optional()
       .describe("Specific connected account to use"),
+    accountEmails: z
+      .string()
+      .optional()
+      .describe(
+        "Per-id account emails, comma-separated and positionally matched to --id (bulk UI calls only)",
+      ),
   }),
   run: async (args) => {
     const ids = args.id
@@ -29,19 +39,43 @@ export default defineAction({
     const ownerEmail = getRequestUserEmail();
     if (!ownerEmail) throw new Error("no authenticated user");
 
+    const accountEmailList = args.accountEmails
+      ?.split(",")
+      .map((s) => s.trim());
+
     const results: { id: string; success: boolean; error?: string }[] = [];
 
-    for (const id of ids) {
-      try {
-        await markRead({
-          id,
-          ownerEmail,
-          isRead,
-          accountEmail: args.accountEmail,
-        });
-        results.push({ id, success: true });
-      } catch (err: any) {
-        results.push({ id, success: false, error: err?.message ?? "failed" });
+    // Mark-read/unread is message-level (no thread cache invalidation needed,
+    // matching markRead's own reconciliation notes), so the batch path here
+    // is simpler than archive/star.
+    if (ids.length > 1 && (await isConnected(ownerEmail))) {
+      const targets = ids.map((id, i) => ({
+        id,
+        accountEmail: accountEmailList?.[i] || args.accountEmail,
+      }));
+      const { succeeded, failed } = await gmailBatchModifyByAccount(
+        ownerEmail,
+        targets,
+        isRead ? undefined : ["UNREAD"],
+        isRead ? ["UNREAD"] : undefined,
+      );
+      for (const id of succeeded) results.push({ id, success: true });
+      for (const f of failed)
+        results.push({ id: f.id, success: false, error: f.error });
+    } else {
+      for (let i = 0; i < ids.length; i++) {
+        const id = ids[i];
+        try {
+          await markRead({
+            id,
+            ownerEmail,
+            isRead,
+            accountEmail: accountEmailList?.[i] || args.accountEmail,
+          });
+          results.push({ id, success: true });
+        } catch (err: any) {
+          results.push({ id, success: false, error: err?.message ?? "failed" });
+        }
       }
     }