apple-mail-mcp 2.10.14 → 2.10.16

package/README.md

@@ -829,11 +829,35 @@ Save a message attachment to disk.
 
 All batch operations accept an array of message IDs (max 100 per batch) and return per-item success/failure results.
 
+**Numeric IDs are scoped to the mailbox you listed them from.** Mail.app numbers messages per
+mailbox, so on a label store (Gmail, iCloud) one message answers to the same id in `INBOX`,
+`Important` and `All Mail` at once — and deleting the `All Mail` copy is not the same operation as
+deleting the `INBOX` copy. Each id is therefore bound to the mailbox it was listed/searched from and
+the operation is applied only there, so **list or search the mailbox immediately before acting on
+it**. An id the server hasn't seen listed is accepted only when exactly one mailbox holds it;
+if several do, that id fails with the candidate mailboxes named instead of being applied to an
+arbitrary copy. `imap:…` ids carry their own account + mailbox + UID and are never ambiguous.
+
+**Say which mailbox with `sourceMailbox` / `sourceAccount`.** The binding above is remembered
+per running server, so a client that reconnects, restarts, or replays a saved list of ids has
+nothing recorded and every id takes the slower whole-tree path — where, on a label store, it is
+likely to be refused as ambiguous. Passing the source mailbox explicitly is the reliable way to
+stay scoped, and it overrides the remembered location. These parameters name where the ids **came
+from**; for `batch-move-messages` that is distinct from `mailbox`, the destination.
+
+`sourceMailbox` is the one that scopes, and it works on its own: omitting `sourceAccount` means
+that mailbox **in the default account**, exactly as an omitted `account` does elsewhere. If the
+default account cannot be determined, the ids fail with an error asking for an explicit
+`sourceAccount` — a scope the server can't honor is never quietly downgraded to the guess-the-copy
+walk. `sourceAccount` by itself pins nothing, since the mailbox is what an id is scoped to.
+
 #### `batch-delete-messages`
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `ids` | string[] | Yes | Message IDs to delete (max 100) |
+| `sourceMailbox` | string | No | Mailbox the **numeric** ids were listed from — pins them to it. Ignored for `imap:` ids. |
+| `sourceAccount` | string | No | Account the numeric ids were listed from. Defaults to the default account; on its own it pins nothing — pair it with `sourceMailbox`. |
 
 **⚠️ Safety:** Destructive. Requires explicit user confirmation; search/list first to confirm the message ids.
 
@@ -844,12 +868,16 @@ All batch operations accept an array of message IDs (max 100 per batch) and retu
 | `ids` | string[] | Yes | Message IDs to move (max 100) |
 | `mailbox` | string | Yes | Destination mailbox |
 | `account` | string | No | Account containing mailbox |
+| `sourceMailbox` | string | No | Mailbox the **numeric** ids were listed from — pins them to it. Ignored for `imap:` ids. |
+| `sourceAccount` | string | No | Account the numeric ids were listed from. Defaults to the default account; on its own it pins nothing — pair it with `sourceMailbox`. |
 
 #### `batch-mark-as-read` / `batch-mark-as-unread`
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `ids` | string[] | Yes | Message IDs (max 100) |
+| `sourceMailbox` | string | No | Mailbox the **numeric** ids were listed from — pins them to it. Ignored for `imap:` ids. |
+| `sourceAccount` | string | No | Account the numeric ids were listed from. Defaults to the default account; on its own it pins nothing — pair it with `sourceMailbox`. |
 
 #### `batch-flag-messages` / `batch-unflag-messages`
 
@@ -857,6 +885,8 @@ All batch operations accept an array of message IDs (max 100 per batch) and retu
 |-----------|------|----------|-------------|
 | `ids` | string[] | Yes | Message IDs (max 100) |
 | `color` | string | No | (`batch-flag-messages` only) Flag color — see [`flag-message`](#flag-message--unflag-message). Applied on both routes, so a mixed batch of numeric and `imap:` ids all end up colored. |
+| `sourceMailbox` | string | No | Mailbox the **numeric** ids were listed from — pins them to it. Ignored for `imap:` ids. |
+| `sourceAccount` | string | No | Account the numeric ids were listed from. Defaults to the default account; on its own it pins nothing — pair it with `sourceMailbox`. |
 
 ---
 
@@ -1438,6 +1468,15 @@ In a JSON string literal, `\\` — two characters — denotes **one** literal ba
 - Message IDs change if the message is moved between mailboxes
 - Use `search-messages` to find the current message ID
 
+### "... is present in more than one mailbox"
+- A bare numeric ID identifies a message only *within a mailbox*, and a label store (Gmail, iCloud)
+  reports the same message under the same ID in `INBOX`, `Important` and `All Mail` at once. The
+  server refuses rather than guessing which copy you meant.
+- Fix it by running `list-messages`/`search-messages` on the mailbox you actually want to act on,
+  then using the IDs from that result — the operation is then scoped to that mailbox.
+- It only affects IDs the server hasn't seen listed (carried over from an earlier session, or typed
+  by hand). `imap:…` IDs encode their own mailbox and never hit this.
+
 ### `search-messages` says "Partial results" or skips a mailbox
 - This is expected for very large IMAP/Gmail mailboxes (e.g. Gmail's `All Mail`, `Important`): Apple Mail can't scan them via AppleScript before timing out, so they're skipped and named in the result rather than silently returning empty.
 - To search inside one, scope the call with `mailbox` **and** a `dateFrom`/`dateTo` window.

package/build/index.js

@@ -78237,6 +78237,8 @@ var CONTENT_MARKER = "CONTENT";
 var MSGID_MARKER = "MSGID";
 var HTML_MARKER = "HTML";
 var BATCH_FATAL = "FATAL";
+var AMBIGUOUS_ID_PREFIX = "Message id ";
+var AMBIGUOUS_ID_BATCH = "This message id is present in more than one mailbox ";
 function normalizeRfcMessageId(mid) {
   return (mid || "").trim().replace(/^<+/, "").replace(/>+$/, "").trim();
 }
@@ -78575,6 +78577,44 @@ var AppleMailManager = class {
       if (oldest !== void 0) this.idLocationIndex.delete(oldest);
     }
   }
+  /** Where a message id was last listed/searched from, if we've seen it. */
+  locationFor(id) {
+    return this.idLocationIndex.get(String(id));
+  }
+  /**
+   * Publicly record where a message id lives.
+   *
+   * The index fills itself from list/search results, but that is per-process
+   * state: a caller that carried ids across a process boundary (a stored triage
+   * list, a scheduled job resuming) starts with an empty index, so every id is
+   * "unlocated" and a label-store id gets refused as ambiguous. Registering the
+   * known location restores scoped resolution.
+   */
+  noteMessageLocation(id, account, mailbox) {
+    this.rememberLocation(id, account, mailbox);
+  }
+  /**
+   * AppleScript fragment resolving `account` + `mailbox` into `_tmb`, leaving
+   * `_tmb` as `missing value` when it can't be pinned down. Exact-name match
+   * only, and a name matching more than one mailbox resolves to nothing rather
+   * than guessing — the same rule the move destination already applies.
+   */
+  resolveMailboxFragment(account, mailbox) {
+    const resolved = this.resolveMailbox(mailbox, account);
+    return `
+        set _tmb to missing value
+        set _acctM to {}
+        repeat with _a in accounts
+          if (name of _a) is "${escapeForAppleScript(account)}" then set end of _acctM to _a
+        end repeat
+        if (count of _acctM) is 1 then
+          set _mbM to {}
+          repeat with _m in (mailboxes of (item 1 of _acctM))
+            if (name of _m) is "${escapeForAppleScript(resolved)}" then set end of _mbM to _m
+          end repeat
+          if (count of _mbM) is 1 then set _tmb to item 1 of _mbM
+        end if`;
+  }
   /**
    * Returns cached accounts or fetches fresh data if cache is expired/empty.
    */
@@ -79781,24 +79821,63 @@ var AppleMailManager = class {
     return true;
   }
   /**
-   * Helper to find and operate on a message by ID.
+   * Helper to find and operate on a message by ID, scoped to the mailbox the id
+   * was listed from.
+   *
+   * Mail.app numeric ids are per-mailbox, and on a label store (Gmail, iCloud)
+   * ONE message is present in several mailboxes under the SAME id — INBOX,
+   * "Important" and "All Mail" all report id 75816 for the same mail. This used
+   * to walk every account's every mailbox and mutate the FIRST hit, so whichever
+   * copy `mailboxes of <account>` happened to reach first won and the mailbox the
+   * id was listed from lost whenever an alias came earlier in that (store-
+   * dependent) order — the op reported success while the copy the caller meant
+   * stayed put and a different one was moved/deleted (#152). See
+   * runBatchOperation for the observed ordering on the reporting account.
+   *
+   * Which mailbox a mutation lands in is semantic — deleting the INBOX copy and
+   * deleting the "All Mail" copy are different operations — so scope to the
+   * mailbox the id actually came from (`idLocationIndex`, populated by every
+   * list/search) and never guess.
    */
   findMessageScript(id, operation) {
+    const loc = this.locationFor(id);
+    if (loc) {
+      return buildAppLevelScript(`
+      try
+        ${this.resolveMailboxFragment(loc.account, loc.mailbox)}
+        if _tmb is missing value then return "error:Message not found"
+        set matchingMsgs to (messages of _tmb whose id is ${Number(id)})
+        if (count of matchingMsgs) > 0 then
+          set msg to item 1 of matchingMsgs
+          ${operation}
+          return "ok"
+        end if
+        return "error:Message not found"
+      on error errMsg
+        return "error:" & errMsg
+      end try
+    `);
+    }
     return buildAppLevelScript(`
       try
+        set _hits to {}
+        set _names to ""
         repeat with acct in accounts
           repeat with mb in mailboxes of acct
             try
               set matchingMsgs to (messages of mb whose id is ${Number(id)})
               if (count of matchingMsgs) > 0 then
-                set msg to item 1 of matchingMsgs
-                ${operation}
-                return "ok"
+                set end of _hits to (item 1 of matchingMsgs)
+                set _names to _names & (name of acct) & "/" & (name of mb) & ", "
               end if
             end try
           end repeat
         end repeat
-        return "error:Message not found"
+        if (count of _hits) is 0 then return "error:Message not found"
+        if (count of _hits) > 1 then return "error:${AMBIGUOUS_ID_PREFIX}${Number(id)} is present in more than one mailbox (" & _names & "); list or search that mailbox first so the operation targets the right copy"
+        set msg to item 1 of _hits
+        ${operation}
+        return "ok"
       on error errMsg
         return "error:" & errMsg
       end try
@@ -79983,6 +80062,31 @@ var AppleMailManager = class {
     const targetMailbox = this.resolveMailbox(mailbox, targetAccount);
     const safeMailbox = escapeForAppleScript(targetMailbox);
     const safeAccount = escapeForAppleScript(targetAccount);
+    const loc = this.locationFor(id);
+    const findAndMove = loc ? `
+        ${this.resolveMailboxFragment(loc.account, loc.mailbox)}
+        if _tmb is missing value then return "error:Message not found"
+        set matchingMsgs to (messages of _tmb whose id is ${Number(id)})
+        if (count of matchingMsgs) is 0 then return "error:Message not found"
+        move (item 1 of matchingMsgs) to destMailbox
+        return "ok"` : `
+        set _hits to {}
+        set _names to ""
+        repeat with acct in accounts
+          repeat with mb in (mailboxes of acct)
+            try
+              set matchingMsgs to (messages of mb whose id is ${Number(id)})
+              if (count of matchingMsgs) > 0 then
+                set end of _hits to (item 1 of matchingMsgs)
+                set _names to _names & (name of acct) & "/" & (name of mb) & ", "
+              end if
+            end try
+          end repeat
+        end repeat
+        if (count of _hits) is 0 then return "error:Message not found"
+        if (count of _hits) > 1 then return "error:${AMBIGUOUS_ID_PREFIX}${Number(id)} is present in more than one mailbox (" & _names & "); list or search that mailbox first so the move targets the right copy"
+        move (item 1 of _hits) to destMailbox
+        return "ok"`;
     const script = buildAppLevelScript(`
       try
         -- \`mailboxes of account\` is already flat: it includes nested mailboxes
@@ -79998,21 +80102,7 @@ var AppleMailManager = class {
         if (count of destMatches) is 0 then return "error:Destination mailbox \\"" & destName & "\\" not found in account \\"${safeAccount}\\""
         if (count of destMatches) > 1 then return "error:Destination mailbox \\"" & destName & "\\" is ambiguous (" & (count of destMatches) & " matches) in account \\"${safeAccount}\\"; disambiguate or move by full path"
         set destMailbox to item 1 of destMatches
-
-        -- Find the message by id. The flat mailbox list already covers nested
-        -- mailboxes, so this reaches messages in subfolders without recursing.
-        repeat with acct in accounts
-          repeat with mb in (mailboxes of acct)
-            try
-              set matchingMsgs to (messages of mb whose id is ${Number(id)})
-              if (count of matchingMsgs) > 0 then
-                move (item 1 of matchingMsgs) to destMailbox
-                return "ok"
-              end if
-            end try
-          end repeat
-        end repeat
-        return "error:Message not found"
+        ${findAndMove}
       on error errMsg
         return "error:" & errMsg
       end try
@@ -80040,23 +80130,76 @@ var AppleMailManager = class {
   // ===========================================================================
   // Batch Operations
   // ===========================================================================
+  /**
+   * Turn a caller-supplied batch source scope into an account+mailbox pair.
+   *
+   * `mailbox` is what does the scoping, and it works ON ITS OWN: an omitted
+   * `account` means "the default account" here exactly as it does for every
+   * other tool in this server (see resolveAccount), never "ignore the argument
+   * you were given". Requiring both used to make a lone `sourceMailbox` a silent
+   * no-op — the ids fell back to the whole-tree path and were then refused as
+   * ambiguous, which is the very failure the parameter exists to prevent.
+   *
+   * The safety property is absolute: when the account cannot be determined there
+   * is NO fallback to the scan-and-guess walk. The caller gets an error naming
+   * the mailbox it asked for, so it can retry with an explicit `sourceAccount`.
+   * (An `account` with no `mailbox` cannot pin anything, so it scopes nothing —
+   * those ids still go through the index / ambiguity-checked path.)
+   */
+  resolveBatchScope(scope) {
+    const mailbox = scope?.mailbox?.trim();
+    if (!mailbox) return { kind: "none" };
+    const account = scope?.account?.trim();
+    if (account) return { kind: "scoped", account, mailbox };
+    const known = this.getCachedAccounts();
+    if (known.length === 0) {
+      return {
+        kind: "unresolvable",
+        error: `Cannot scope to source mailbox "${mailbox}": no sourceAccount was given and no Mail account could be read (Mail returned none, or the AppleScript transport failed). Retry with an explicit sourceAccount.`
+      };
+    }
+    const chosen = this.resolveAccount();
+    if (!known.some((a) => a.name === chosen)) {
+      return {
+        kind: "unresolvable",
+        error: `Cannot scope to source mailbox "${mailbox}": no sourceAccount was given and the default account could not be determined. Retry with an explicit sourceAccount (available: ${known.map((a) => a.name).join(", ")}).`
+      };
+    }
+    return { kind: "scoped", account: chosen, mailbox };
+  }
   /**
    * Run one operation over many message IDs in a SINGLE osascript invocation.
    *
    * Previously each batch method looped and called the per-id method, so a
    * 100-id batch spawned 100 osascript processes — each one re-resolving
    * accounts and walking the whole account→mailbox tree — all serialized
-   * through the gate (issue #31). This walks the tree exactly once: for each
-   * mailbox it probes the still-pending IDs with `whose id is` (indexed, so
-   * effectively free) and applies `operation` to any match, tracking found IDs
-   * so it can stop early once all are accounted for. Per-id outcomes come back
-   * as control-char-delimited `id<FS>status` records (status: `ok`,
-   * `notfound`, or `error:<msg>`), and results are returned in input order.
+   * through the gate (issue #31). Still one osascript invocation, but the ids
+   * are now grouped by the mailbox they were listed from and each group opens
+   * exactly that one mailbox. Per-id outcomes come back as control-char
+   * delimited `position<FS>status` records (status: `ok`, `notfound`, or
+   * `error:<msg>`), and results are returned in input order.
    *
-   * `setup` runs once before the walk (used by move to resolve the destination);
-   * it may bail the whole batch by returning a `BATCH_FATAL`-prefixed string.
+   * Scoping is a CORRECTNESS requirement, not an optimization (#152). A Mail.app
+   * numeric id is unique only within a mailbox, and a label store (Gmail,
+   * iCloud) exposes one message in several mailboxes under the same id — INBOX,
+   * "Important" and "All Mail" all report id 75816 for the same mail. The old
+   * tree walk applied `operation` to the FIRST mailbox that matched while
+   * iterating `mailboxes of <account>`, so whichever copy that iteration reached
+   * first won — and the ids' real source mailbox lost whenever an alias came
+   * earlier. Observed on the reporting account (`list-mailboxes`, 2026-08-13):
+   * INBOX 1, "[Gmail]/All Mail" 5, "[Gmail]/Important" 9, "Sales Spam" 12 — so a
+   * batch listed from "Sales Spam" was applied to the All Mail copies while the
+   * Sales Spam messages stayed put, and every id still reported `ok`. That order
+   * is a property of the store, not a guarantee: do not rely on it in either
+   * direction — any mailbox the walk reaches late loses the same way. Grouping by
+   * recorded source mailbox makes the op land on the copy the caller actually
+   * listed; ids with no recorded mailbox are refused when ambiguous rather than
+   * applied to an arbitrary copy.
+   *
+   * `setup` runs once up front (used by move to resolve the destination); it may
+   * bail the whole batch by returning a `BATCH_FATAL`-prefixed string.
    */
-  runBatchOperation(ids, operation, setup = "") {
+  runBatchOperation(ids, operation, setup = "", scope) {
     const valid = [];
     for (const id of ids) {
       const num = Number(id);
@@ -80065,39 +80208,101 @@ var AppleMailManager = class {
     if (valid.length === 0) {
       return ids.map((id) => ({ id, success: false, error: "Invalid message ID" }));
     }
-    const script = buildAppLevelScript(`
-      try
-        ${setup}
-        set _out to ""
-        set _done to {}
-        set _ids to {${valid.map((v) => v.num).join(", ")}}
-        set _total to count of _ids
+    const resolved = this.resolveBatchScope(scope);
+    if (resolved.kind === "unresolvable") {
+      return ids.map((id) => ({ id, success: false, error: resolved.error }));
+    }
+    const callerScope = resolved.kind === "scoped" ? resolved : void 0;
+    const groups = /* @__PURE__ */ new Map();
+    const unlocated = [];
+    valid.forEach((v, i) => {
+      const pos = i + 1;
+      const loc = callerScope ?? this.locationFor(v.id);
+      if (!loc) {
+        unlocated.push({ num: v.num, pos });
+        return;
+      }
+      const key = `${loc.account}\0${loc.mailbox}`;
+      const g = groups.get(key) ?? { account: loc.account, mailbox: loc.mailbox, items: [] };
+      g.items.push({ num: v.num, pos });
+      groups.set(key, g);
+    });
+    const asList = (nums) => `{${nums.join(", ")}}`;
+    const scopedBlocks = [...groups.values()].map(
+      (g) => `
+        ${this.resolveMailboxFragment(g.account, g.mailbox)}
+        set _gids to ${asList(g.items.map((it) => it.num))}
+        set _gpos to ${asList(g.items.map((it) => it.pos))}
+        if _tmb is missing value then
+          repeat with _k from 1 to (count of _gpos)
+            set _out to _out & ((item _k of _gpos) as string) & "${FIELD_SEP}error:source mailbox \\"${escapeForAppleScript(g.mailbox)}\\" not found in account \\"${escapeForAppleScript(g.account)}\\"${RECORD_SEP}"
+          end repeat
+        else
+          repeat with _k from 1 to (count of _gids)
+            set _idx to item _k of _gpos
+            try
+              set _m to (messages of _tmb whose id is (item _k of _gids))
+              if (count of _m) > 0 then
+                set _msg to item 1 of _m
+                ${operation}
+                set _out to _out & (_idx as string) & "${FIELD_SEP}ok${RECORD_SEP}"
+              else
+                set _out to _out & (_idx as string) & "${FIELD_SEP}notfound${RECORD_SEP}"
+              end if
+            on error _e
+              set _out to _out & (_idx as string) & "${FIELD_SEP}error:" & _e & "${RECORD_SEP}"
+            end try
+          end repeat
+        end if`
+    ).join("\n");
+    const unlocatedBlock = unlocated.length ? `
+        set _uids to ${asList(unlocated.map((it) => it.num))}
+        set _upos to ${asList(unlocated.map((it) => it.pos))}
+        set _ucount to count of _uids
+        set _uhit to {}
+        set _umsg to {}
+        set _unames to {}
+        repeat with _k from 1 to _ucount
+          set end of _uhit to 0
+          set end of _umsg to missing value
+          set end of _unames to ""
+        end repeat
         repeat with acct in accounts
-          if (count of _done) is _total then exit repeat
           repeat with mb in (mailboxes of acct)
-            if (count of _done) is _total then exit repeat
-            repeat with _idx from 1 to _total
-              if _idx is not in _done then
-                set _theId to item _idx of _ids
-                try
-                  set _m to (messages of mb whose id is _theId)
-                  if (count of _m) > 0 then
-                    set _msg to item 1 of _m
-                    ${operation}
-                    set end of _done to _idx
-                    set _out to _out & (_idx as string) & "${FIELD_SEP}ok${RECORD_SEP}"
-                  end if
-                on error _e
-                  set end of _done to _idx
-                  set _out to _out & (_idx as string) & "${FIELD_SEP}error:" & _e & "${RECORD_SEP}"
-                end try
-              end if
+            repeat with _k from 1 to _ucount
+              try
+                set _m to (messages of mb whose id is (item _k of _uids))
+                if (count of _m) > 0 then
+                  set item _k of _uhit to ((item _k of _uhit) + 1)
+                  if (item _k of _uhit) is 1 then set item _k of _umsg to (item 1 of _m)
+                  set item _k of _unames to ((item _k of _unames) & (name of acct) & "/" & (name of mb) & ", ")
+                end if
+              end try
             end repeat
           end repeat
         end repeat
-        repeat with _idx from 1 to _total
-          if _idx is not in _done then set _out to _out & (_idx as string) & "${FIELD_SEP}notfound${RECORD_SEP}"
-        end repeat
+        repeat with _k from 1 to _ucount
+          set _idx to item _k of _upos
+          if (item _k of _uhit) is 0 then
+            set _out to _out & (_idx as string) & "${FIELD_SEP}notfound${RECORD_SEP}"
+          else if (item _k of _uhit) > 1 then
+            set _out to _out & (_idx as string) & "${FIELD_SEP}error:${AMBIGUOUS_ID_BATCH}(" & (item _k of _unames) & "); list or search that mailbox first so the operation targets the right copy${RECORD_SEP}"
+          else
+            try
+              set _msg to item _k of _umsg
+              ${operation}
+              set _out to _out & (_idx as string) & "${FIELD_SEP}ok${RECORD_SEP}"
+            on error _e
+              set _out to _out & (_idx as string) & "${FIELD_SEP}error:" & _e & "${RECORD_SEP}"
+            end try
+          end if
+        end repeat` : "";
+    const script = buildAppLevelScript(`
+      try
+        ${setup}
+        set _out to ""
+        ${scopedBlocks}
+        ${unlocatedBlock}
         return _out
       on error errMsg
         return "${BATCH_FATAL}" & errMsg
@@ -80140,8 +80345,8 @@ var AppleMailManager = class {
   /**
    * Delete multiple messages at once (single tree walk — see runBatchOperation).
    */
-  batchDeleteMessages(ids) {
-    return this.runBatchOperation(ids, "delete _msg");
+  batchDeleteMessages(ids, scope) {
+    return this.runBatchOperation(ids, "delete _msg", "", scope);
   }
   /**
    * Move multiple messages to a mailbox at once (single tree walk).
@@ -80150,7 +80355,7 @@ var AppleMailManager = class {
    * matching more than one mailbox fails the whole batch rather than guessing),
    * then every matched message is moved in the same walk.
    */
-  batchMoveMessages(ids, mailbox, account) {
+  batchMoveMessages(ids, mailbox, account, scope) {
     const targetAccount = this.resolveAccount(account);
     const targetMailbox = this.resolveMailbox(mailbox, targetAccount);
     const safeMailbox = escapeForAppleScript(targetMailbox);
@@ -80164,31 +80369,31 @@ var AppleMailManager = class {
         if (count of destMatches) is 0 then return "${BATCH_FATAL}Destination mailbox \\"" & destName & "\\" not found in account \\"${safeAccount}\\""
         if (count of destMatches) > 1 then return "${BATCH_FATAL}Destination mailbox \\"" & destName & "\\" is ambiguous (" & (count of destMatches) & " matches) in account \\"${safeAccount}\\"; move by full path"
         set destMailbox to item 1 of destMatches`;
-    return this.runBatchOperation(ids, "move _msg to destMailbox", setup);
+    return this.runBatchOperation(ids, "move _msg to destMailbox", setup, scope);
   }
   /**
    * Mark multiple messages as read at once (single tree walk).
    */
-  batchMarkAsRead(ids) {
-    return this.runBatchOperation(ids, "set read status of _msg to true");
+  batchMarkAsRead(ids, scope) {
+    return this.runBatchOperation(ids, "set read status of _msg to true", "", scope);
   }
   /**
    * Mark multiple messages as unread at once (single tree walk).
    */
-  batchMarkAsUnread(ids) {
-    return this.runBatchOperation(ids, "set read status of _msg to false");
+  batchMarkAsUnread(ids, scope) {
+    return this.runBatchOperation(ids, "set read status of _msg to false", "", scope);
   }
   /**
    * Flag multiple messages at once (single tree walk).
    */
-  batchFlagMessages(ids, colorIndex) {
-    return this.runBatchOperation(ids, this.flagOperation("_msg", colorIndex));
+  batchFlagMessages(ids, colorIndex, scope) {
+    return this.runBatchOperation(ids, this.flagOperation("_msg", colorIndex), "", scope);
   }
   /**
    * Unflag multiple messages at once (single tree walk).
    */
-  batchUnflagMessages(ids) {
-    return this.runBatchOperation(ids, "set flagged status of _msg to false");
+  batchUnflagMessages(ids, scope) {
+    return this.runBatchOperation(ids, "set flagged status of _msg to false", "", scope);
   }
   /**
    * List attachments for a message.
@@ -82853,6 +83058,57 @@ function withErrorHandling(handler, errorPrefix) {
   };
 }
 
+// src/tools/batchResults.ts
+async function hybridBatchCounts(ids, appleFn, imapFn) {
+  const imapIds = ids.filter((i) => i.startsWith("imap:"));
+  const numericIds = ids.filter((i) => !i.startsWith("imap:"));
+  let success = 0;
+  let fail = 0;
+  const errors = [];
+  if (numericIds.length > 0) {
+    const res = appleFn(numericIds);
+    const s = res.filter((r) => r.success).length;
+    success += s;
+    fail += res.length - s;
+    errors.push(...res.filter((r) => !r.success && r.error).map((r) => r.error));
+  }
+  if (imapIds.length > 0) {
+    const r = await imapFn(imapIds);
+    success += r.success;
+    fail += r.failed;
+    errors.push(...r.errors);
+  }
+  return { success, fail, errors };
+}
+function distinctErrors(errors) {
+  return [...new Set(errors.filter(Boolean))];
+}
+function formatBatchErrors(errors, max = 5) {
+  const distinct = distinctErrors(errors);
+  if (distinct.length === 0) return "";
+  const shown = distinct.slice(0, max);
+  const more = distinct.length - shown.length;
+  return `: ${shown.join("; ")}${more > 0 ? ` (+${more} more)` : ""}`;
+}
+var MAX_STRUCTURED_BATCH_ERRORS = 20;
+function batchResponse(counts, messages, extra = {}) {
+  const { success, fail, errors } = counts;
+  const distinct = distinctErrors(errors);
+  const reported = distinct.slice(0, MAX_STRUCTURED_BATCH_ERRORS);
+  const structured = {
+    ok: fail === 0,
+    success,
+    failed: fail,
+    ...extra,
+    ...reported.length > 0 ? { errors: reported } : {},
+    ...distinct.length > reported.length ? { errorsTruncated: true } : {}
+  };
+  const suffix = formatBatchErrors(distinct);
+  if (fail === 0) return successResponse(messages.allSucceeded(success), structured);
+  if (success === 0) return errorResponse(`${messages.allFailed(fail)}${suffix}`, structured);
+  return successResponse(`${messages.partial(success, fail)}${suffix}`, structured);
+}
+
 // src/services/imapMultiAccount.ts
 function normalizeMessageId2(row) {
   const raw = typeof row.messageId === "string" ? row.messageId.trim() : "";
@@ -83444,6 +83700,12 @@ function withJsonSchema2020_12(transport2) {
 loadFileConfig();
 var MESSAGE_ID_SCHEMA = external_exports.string().regex(/^(\d+|imap:[A-Za-z0-9_-]+)$/, "Message ID must be numeric or an IMAP id (imap:\u2026)");
 var BATCH_IDS_SCHEMA = external_exports.array(MESSAGE_ID_SCHEMA).min(1, "At least one message ID is required").max(100, "Cannot process more than 100 messages in a single batch");
+var BATCH_SOURCE_MAILBOX_SCHEMA = external_exports.string().optional().describe(
+  "Mailbox the numeric ids were listed from (e.g. 'INBOX'). Pins each id to that mailbox \u2014 strongly recommended, since one numeric id can match in several mailboxes. Works on its own: without sourceAccount it means that mailbox in the default account. Ignored for imap: ids."
+);
+var BATCH_SOURCE_ACCOUNT_SCHEMA = external_exports.string().optional().describe(
+  "Account the numeric ids were listed from. Defaults to the default account. On its own it pins nothing \u2014 pair it with sourceMailbox."
+);
 var FLAG_COLOR_INDEX = {
   red: 0,
   orange: 1,
@@ -83493,7 +83755,19 @@ var BATCH_COUNT_OUTPUT_SCHEMA = {
   ok: external_exports.boolean().optional(),
   success: external_exports.number().optional(),
   failed: external_exports.number().optional(),
-  mailbox: external_exports.string().optional()
+  mailbox: external_exports.string().optional(),
+  // Declared so the failure channel is part of the tool's advertised CONTRACT:
+  // a client can rely on `errors` being string[] and code against it, and it
+  // shows up in generated types and docs. Declaring is not what makes it
+  // deliverable — registerTool() wraps every outputSchema in
+  // `z.object(shape).passthrough()`, so these tools advertise
+  // `additionalProperties: true` (verified against the built server) and an
+  // undeclared key would be carried through, not rejected. Enumerating it is a
+  // promise to callers, not a workaround for a validator.
+  errors: external_exports.array(external_exports.string()).optional(),
+  // Set when `errors` was capped (MAX_STRUCTURED_BATCH_ERRORS distinct reasons),
+  // so a short list is never mistaken for the complete one.
+  errorsTruncated: external_exports.boolean().optional()
 };
 var CHECK_ITEM_SCHEMA = external_exports.object({}).passthrough();
 var require2 = createRequire(import.meta.url);
@@ -83574,26 +83848,6 @@ function registerTool(name, config2, cb) {
 }
 var mailManager = new AppleMailManager();
 registerResourcesAndPrompts(server, mailManager);
-async function hybridBatchCounts(ids, appleFn, imapFn) {
-  const imapIds = ids.filter((i) => i.startsWith("imap:"));
-  const numericIds = ids.filter((i) => !i.startsWith("imap:"));
-  let success = 0;
-  let fail = 0;
-  const errors = [];
-  if (numericIds.length > 0) {
-    const res = appleFn(numericIds);
-    const s = res.filter((r) => r.success).length;
-    success += s;
-    fail += res.length - s;
-  }
-  if (imapIds.length > 0) {
-    const r = await imapFn(imapIds);
-    success += r.success;
-    fail += r.failed;
-    errors.push(...r.errors);
-  }
-  return { success, fail, errors };
-}
 registerTool(
   "search-messages",
   {
@@ -84371,173 +84625,159 @@ registerTool(
 registerTool(
   "batch-delete-messages",
   {
-    description: "Use when: deleting multiple messages in one call (1\u2013100 ids; moves them to Trash).\nReturns: counts of how many were deleted and how many failed.\nDo not use when: deleting just one (use delete-message) or filing messages away (use batch-move-messages).\nSafety: destructive and applies to many messages at once \u2014 require explicit user confirmation, and search-messages/list-messages first to confirm every id is correct before deleting.",
+    description: "Use when: deleting multiple messages in one call (1\u2013100 ids; moves them to Trash).\nReturns: counts of how many were deleted and how many failed, plus the distinct reasons for any failures.\nDo not use when: deleting just one (use delete-message) or filing messages away (use batch-move-messages).\nSafety: destructive and applies to many messages at once \u2014 require explicit user confirmation, and search-messages/list-messages first to confirm every id is correct before deleting. Pass sourceMailbox/sourceAccount (the mailbox you listed the ids from) so each numeric id is pinned to that mailbox; an id that matches in several mailboxes is refused, not guessed.",
     inputSchema: {
-      ids: BATCH_IDS_SCHEMA
+      ids: BATCH_IDS_SCHEMA,
+      sourceMailbox: BATCH_SOURCE_MAILBOX_SCHEMA,
+      sourceAccount: BATCH_SOURCE_ACCOUNT_SCHEMA
     },
     outputSchema: BATCH_COUNT_OUTPUT_SCHEMA
   },
-  withErrorHandling(async ({ ids }) => {
-    const { success: successCount, fail: failCount } = await hybridBatchCounts(
+  withErrorHandling(async ({ ids, sourceMailbox, sourceAccount }) => {
+    const counts = await hybridBatchCounts(
       ids,
-      (n) => mailManager.batchDeleteMessages(n),
+      (n) => mailManager.batchDeleteMessages(n, { account: sourceAccount, mailbox: sourceMailbox }),
       (im) => imapBatchDelete(im)
     );
-    const structured = { ok: failCount === 0, success: successCount, failed: failCount };
-    if (failCount === 0) {
-      return successResponse(`Successfully deleted ${successCount} message(s)`, structured);
-    } else if (successCount === 0) {
-      return errorResponse(`Failed to delete all ${failCount} message(s)`);
-    } else {
-      return successResponse(`Deleted ${successCount} message(s), ${failCount} failed`, structured);
-    }
+    return batchResponse(counts, {
+      allSucceeded: (n) => `Successfully deleted ${n} message(s)`,
+      allFailed: (n) => `Failed to delete all ${n} message(s)`,
+      partial: (ok, failed) => `Deleted ${ok} message(s), ${failed} failed`
+    });
   }, "Error batch deleting messages")
 );
 registerTool(
   "batch-move-messages",
   {
-    description: "Use when: moving multiple messages (1\u2013100 ids) into the same destination mailbox/folder in one call, e.g. bulk archiving.\nReturns: counts of how many were moved and how many failed.\nDo not use when: moving just one (use move-message) or deleting (use batch-delete-messages). Use list-mailboxes to confirm the destination name exists.\nSafety: moves many real messages at once \u2014 confirm the destination mailbox, and search-messages/list-messages first to confirm the ids.",
+    description: "Use when: moving multiple messages (1\u2013100 ids) into the same destination mailbox/folder in one call, e.g. bulk archiving.\nReturns: counts of how many were moved and how many failed, plus the distinct reasons for any failures.\nDo not use when: moving just one (use move-message) or deleting (use batch-delete-messages). Use list-mailboxes to confirm the destination name exists.\nSafety: moves many real messages at once \u2014 confirm the destination mailbox, and search-messages/list-messages first to confirm the ids. Pass sourceMailbox/sourceAccount (the mailbox you listed the ids from \u2014 not the destination) so each numeric id is pinned to that mailbox; an id that matches in several mailboxes is refused, not guessed.",
     inputSchema: {
       ids: BATCH_IDS_SCHEMA,
       mailbox: external_exports.string().min(1, "Destination mailbox is required"),
-      account: external_exports.string().optional().describe("Account containing the destination mailbox")
+      account: external_exports.string().optional().describe("Account containing the destination mailbox"),
+      sourceMailbox: BATCH_SOURCE_MAILBOX_SCHEMA,
+      sourceAccount: BATCH_SOURCE_ACCOUNT_SCHEMA
     },
     outputSchema: BATCH_COUNT_OUTPUT_SCHEMA
   },
-  withErrorHandling(async ({ ids, mailbox, account }) => {
-    const { success: successCount, fail: failCount } = await hybridBatchCounts(
+  withErrorHandling(async ({ ids, mailbox, account, sourceMailbox, sourceAccount }) => {
+    const counts = await hybridBatchCounts(
       ids,
-      (n) => mailManager.batchMoveMessages(n, mailbox, account),
+      (n) => mailManager.batchMoveMessages(n, mailbox, account, {
+        account: sourceAccount,
+        mailbox: sourceMailbox
+      }),
       (im) => imapBatchMove(im, mailbox, { account })
     );
-    const structured = { ok: failCount === 0, success: successCount, failed: failCount, mailbox };
-    if (failCount === 0) {
-      return successResponse(
-        `Successfully moved ${successCount} message(s) to "${mailbox}"`,
-        structured
-      );
-    } else if (successCount === 0) {
-      return errorResponse(`Failed to move all ${failCount} message(s)`);
-    } else {
-      return successResponse(
-        `Moved ${successCount} message(s) to "${mailbox}", ${failCount} failed`,
-        structured
-      );
-    }
+    return batchResponse(
+      counts,
+      {
+        allSucceeded: (n) => `Successfully moved ${n} message(s) to "${mailbox}"`,
+        allFailed: (n) => `Failed to move all ${n} message(s)`,
+        partial: (ok, failed) => `Moved ${ok} message(s) to "${mailbox}", ${failed} failed`
+      },
+      { mailbox }
+    );
   }, "Error batch moving messages")
 );
 registerTool(
   "batch-mark-as-read",
   {
-    description: "Use when: marking multiple messages (1\u2013100 ids) as read in one call.\nReturns: counts of how many were marked read and how many failed.\nDo not use when: marking just one (use mark-as-read) or marking unread (use batch-mark-as-unread). Get the ids from search-messages or list-messages first.",
+    description: "Use when: marking multiple messages (1\u2013100 ids) as read in one call.\nReturns: counts of how many were marked read and how many failed.\nDo not use when: marking just one (use mark-as-read) or marking unread (use batch-mark-as-unread). Get the ids from search-messages or list-messages first. Pass sourceMailbox/sourceAccount (the mailbox you listed the ids from) so each numeric id is pinned to that mailbox; an id that matches in several mailboxes is refused, not guessed.",
     inputSchema: {
-      ids: BATCH_IDS_SCHEMA
+      ids: BATCH_IDS_SCHEMA,
+      sourceMailbox: BATCH_SOURCE_MAILBOX_SCHEMA,
+      sourceAccount: BATCH_SOURCE_ACCOUNT_SCHEMA
     },
     outputSchema: BATCH_COUNT_OUTPUT_SCHEMA
   },
-  withErrorHandling(async ({ ids }) => {
-    const { success: successCount, fail: failCount } = await hybridBatchCounts(
+  withErrorHandling(async ({ ids, sourceMailbox, sourceAccount }) => {
+    const counts = await hybridBatchCounts(
       ids,
-      (n) => mailManager.batchMarkAsRead(n),
+      (n) => mailManager.batchMarkAsRead(n, { account: sourceAccount, mailbox: sourceMailbox }),
       (im) => imapBatchMarkRead(im)
     );
-    const structured = { ok: failCount === 0, success: successCount, failed: failCount };
-    if (failCount === 0) {
-      return successResponse(`Successfully marked ${successCount} message(s) as read`, structured);
-    } else if (successCount === 0) {
-      return errorResponse(`Failed to mark all ${failCount} message(s) as read`);
-    } else {
-      return successResponse(
-        `Marked ${successCount} message(s) as read, ${failCount} failed`,
-        structured
-      );
-    }
+    return batchResponse(counts, {
+      allSucceeded: (n) => `Successfully marked ${n} message(s) as read`,
+      allFailed: (n) => `Failed to mark all ${n} message(s) as read`,
+      partial: (ok, failed) => `Marked ${ok} message(s) as read, ${failed} failed`
+    });
   }, "Error batch marking messages as read")
 );
 registerTool(
   "batch-mark-as-unread",
   {
-    description: "Use when: marking multiple messages (1\u2013100 ids) as unread in one call.\nReturns: counts of how many were marked unread and how many failed.\nDo not use when: marking just one (use mark-as-unread) or marking read (use batch-mark-as-read). Get the ids from search-messages or list-messages first.",
+    description: "Use when: marking multiple messages (1\u2013100 ids) as unread in one call.\nReturns: counts of how many were marked unread and how many failed.\nDo not use when: marking just one (use mark-as-unread) or marking read (use batch-mark-as-read). Get the ids from search-messages or list-messages first. Pass sourceMailbox/sourceAccount (the mailbox you listed the ids from) so each numeric id is pinned to that mailbox; an id that matches in several mailboxes is refused, not guessed.",
     inputSchema: {
-      ids: BATCH_IDS_SCHEMA
+      ids: BATCH_IDS_SCHEMA,
+      sourceMailbox: BATCH_SOURCE_MAILBOX_SCHEMA,
+      sourceAccount: BATCH_SOURCE_ACCOUNT_SCHEMA
     },
     outputSchema: BATCH_COUNT_OUTPUT_SCHEMA
   },
-  withErrorHandling(async ({ ids }) => {
-    const { success: successCount, fail: failCount } = await hybridBatchCounts(
+  withErrorHandling(async ({ ids, sourceMailbox, sourceAccount }) => {
+    const counts = await hybridBatchCounts(
       ids,
-      (n) => mailManager.batchMarkAsUnread(n),
+      (n) => mailManager.batchMarkAsUnread(n, { account: sourceAccount, mailbox: sourceMailbox }),
       (im) => imapBatchMarkUnread(im)
     );
-    const structured = { ok: failCount === 0, success: successCount, failed: failCount };
-    if (failCount === 0) {
-      return successResponse(
-        `Successfully marked ${successCount} message(s) as unread`,
-        structured
-      );
-    } else if (successCount === 0) {
-      return errorResponse(`Failed to mark all ${failCount} message(s) as unread`);
-    } else {
-      return successResponse(
-        `Marked ${successCount} message(s) as unread, ${failCount} failed`,
-        structured
-      );
-    }
+    return batchResponse(counts, {
+      allSucceeded: (n) => `Successfully marked ${n} message(s) as unread`,
+      allFailed: (n) => `Failed to mark all ${n} message(s) as unread`,
+      partial: (ok, failed) => `Marked ${ok} message(s) as unread, ${failed} failed`
+    });
   }, "Error batch marking messages as unread")
 );
 registerTool(
   "batch-flag-messages",
   {
-    description: "Use when: flagging multiple messages (1\u2013100 ids) in one call, optionally with a color (red/orange/yellow/green/blue/purple/gray).\nReturns: counts of how many were flagged and how many failed.\nDo not use when: flagging just one (use flag-message) or removing flags (use batch-unflag-messages). Get the ids from search-messages or list-messages first.\nNote: the color is applied on both routes \u2014 AppleScript sets the flag index, IMAP writes the equivalent $MailFlagBit0/1/2 keywords Mail.app reads \u2014 so a mixed batch of numeric and `imap:` ids all end up colored.",
+    description: "Use when: flagging multiple messages (1\u2013100 ids) in one call, optionally with a color (red/orange/yellow/green/blue/purple/gray).\nReturns: counts of how many were flagged and how many failed.\nDo not use when: flagging just one (use flag-message) or removing flags (use batch-unflag-messages). Get the ids from search-messages or list-messages first. Pass sourceMailbox/sourceAccount (the mailbox you listed the ids from) so each numeric id is pinned to that mailbox; an id that matches in several mailboxes is refused, not guessed.\nNote: the color is applied on both routes \u2014 AppleScript sets the flag index, IMAP writes the equivalent $MailFlagBit0/1/2 keywords Mail.app reads \u2014 so a mixed batch of numeric and `imap:` ids all end up colored.",
     inputSchema: {
       ids: BATCH_IDS_SCHEMA,
-      color: FLAG_COLOR_SCHEMA
+      color: FLAG_COLOR_SCHEMA,
+      sourceMailbox: BATCH_SOURCE_MAILBOX_SCHEMA,
+      sourceAccount: BATCH_SOURCE_ACCOUNT_SCHEMA
     },
     outputSchema: BATCH_COUNT_OUTPUT_SCHEMA
   },
-  withErrorHandling(async ({ ids, color }) => {
+  withErrorHandling(async ({ ids, color, sourceMailbox, sourceAccount }) => {
     const colorIndex = color ? FLAG_COLOR_INDEX[color] : void 0;
-    const { success: successCount, fail: failCount } = await hybridBatchCounts(
+    const counts = await hybridBatchCounts(
       ids,
-      (n) => mailManager.batchFlagMessages(n, colorIndex),
+      (n) => mailManager.batchFlagMessages(n, colorIndex, {
+        account: sourceAccount,
+        mailbox: sourceMailbox
+      }),
       (im) => imapBatchFlag(im, colorIndex)
     );
-    const structured = { ok: failCount === 0, success: successCount, failed: failCount };
-    if (failCount === 0) {
-      return successResponse(`Successfully flagged ${successCount} message(s)`, structured);
-    } else if (successCount === 0) {
-      return errorResponse(`Failed to flag all ${failCount} message(s)`);
-    } else {
-      return successResponse(`Flagged ${successCount} message(s), ${failCount} failed`, structured);
-    }
+    return batchResponse(counts, {
+      allSucceeded: (n) => `Successfully flagged ${n} message(s)`,
+      allFailed: (n) => `Failed to flag all ${n} message(s)`,
+      partial: (ok, failed) => `Flagged ${ok} message(s), ${failed} failed`
+    });
   }, "Error batch flagging messages")
 );
 registerTool(
   "batch-unflag-messages",
   {
-    description: "Use when: removing flags from multiple messages (1\u2013100 ids) in one call.\nReturns: counts of how many were unflagged and how many failed.\nDo not use when: unflagging just one (use unflag-message) or adding flags (use batch-flag-messages). Get the ids from search-messages or list-messages first.",
+    description: "Use when: removing flags from multiple messages (1\u2013100 ids) in one call.\nReturns: counts of how many were unflagged and how many failed.\nDo not use when: unflagging just one (use unflag-message) or adding flags (use batch-flag-messages). Get the ids from search-messages or list-messages first. Pass sourceMailbox/sourceAccount (the mailbox you listed the ids from) so each numeric id is pinned to that mailbox; an id that matches in several mailboxes is refused, not guessed.",
     inputSchema: {
-      ids: BATCH_IDS_SCHEMA
+      ids: BATCH_IDS_SCHEMA,
+      sourceMailbox: BATCH_SOURCE_MAILBOX_SCHEMA,
+      sourceAccount: BATCH_SOURCE_ACCOUNT_SCHEMA
     },
     outputSchema: BATCH_COUNT_OUTPUT_SCHEMA
   },
-  withErrorHandling(async ({ ids }) => {
-    const { success: successCount, fail: failCount } = await hybridBatchCounts(
+  withErrorHandling(async ({ ids, sourceMailbox, sourceAccount }) => {
+    const counts = await hybridBatchCounts(
       ids,
-      (n) => mailManager.batchUnflagMessages(n),
+      (n) => mailManager.batchUnflagMessages(n, { account: sourceAccount, mailbox: sourceMailbox }),
       (im) => imapBatchUnflag(im)
     );
-    const structured = { ok: failCount === 0, success: successCount, failed: failCount };
-    if (failCount === 0) {
-      return successResponse(`Successfully unflagged ${successCount} message(s)`, structured);
-    } else if (successCount === 0) {
-      return errorResponse(`Failed to unflag all ${failCount} message(s)`);
-    } else {
-      return successResponse(
-        `Unflagged ${successCount} message(s), ${failCount} failed`,
-        structured
-      );
-    }
+    return batchResponse(counts, {
+      allSucceeded: (n) => `Successfully unflagged ${n} message(s)`,
+      allFailed: (n) => `Failed to unflag all ${n} message(s)`,
+      partial: (ok, failed) => `Unflagged ${ok} message(s), ${failed} failed`
+    });
   }, "Error batch unflagging messages")
 );
 registerTool(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.10.14",
+  "version": "2.10.16",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",