apple-mail-mcp 2.19.13 → 2.19.15

package/README.md

@@ -1077,6 +1077,15 @@ refused rather than guessed; pass the full path to disambiguate. This also
 means Gmail's nested special mailboxes now report their real path, e.g.
 `[Gmail]/All Mail` rather than `All Mail` — a visible change from before 2.17.0.
 
+Matching ignores letter case **and Unicode normalization form**: a typed
+precomposed `México` (NFC) finds a mailbox the server stores decomposed (NFD —
+common for folders created on a Mac, and what iCloud keeps), and the server's
+own stored spelling is what gets selected. Two mailboxes whose names differ
+*only* in case or normalization look identical in any listing, so a name that
+matches both is refused with an error saying so — rename one of them. For the
+same reason `create-mailbox` treats a normalization-equivalent existing name as
+already existing, and `rename-mailbox` refuses to create such a twin.
+
 **Mail's local "On My Mac" mailboxes** are not children of any account — they
 hang off the application — so they are reported under the synthetic account label
 **`On My Mac`**. An unscoped call includes them (listed last); `account="On My

package/build/cli.js

@@ -57647,6 +57647,19 @@ var require_imap_flow = __commonJS({
   }
 });
 
+// src/utils/mailboxName.ts
+function mailboxNameKey(name) {
+  return name.trim().normalize("NFC").toLowerCase();
+}
+function nfc(name) {
+  return name.trim().normalize("NFC");
+}
+var init_mailboxName = __esm({
+  "src/utils/mailboxName.ts"() {
+    "use strict";
+  }
+});
+
 // src/utils/mimeParse.ts
 function extractBoundary(source) {
   const match = source.match(/boundary="?([^";\s\r\n]+)"?/i);
@@ -58076,6 +58089,7 @@ __export(imapClient_exports, {
   listImapAccountLabels: () => listImapAccountLabels,
   mailFlagBitsFor: () => mailFlagBitsFor,
   mailFlagColorIndex: () => mailFlagColorIndex,
+  matchMailbox: () => matchMailbox,
   normalizeMessageId: () => normalizeMessageId,
   resolveImapConfig: () => resolveImapConfig,
   resolveImapConfigs: () => resolveImapConfigs,
@@ -58290,16 +58304,21 @@ function staticMailboxAlias(mailbox) {
 }
 async function resolveMailboxPath(client, mailbox, _mode) {
   if (!mailbox) return "INBOX";
+  let boxes;
   try {
-    const resolved = await resolveMailbox(client, mailbox);
-    if (resolved.kind === "found") return resolved.path;
-    const flag = SPECIAL_USE_ALIASES[mailbox.trim().toLowerCase()];
-    if (flag) {
-      const boxes = await client.list();
-      const special = boxes.find((b) => b.specialUse?.toLowerCase() === flag);
-      if (special) return special.path;
-    }
+    boxes = await client.list();
   } catch {
+    return staticMailboxAlias(mailbox);
+  }
+  const resolved = matchMailbox(boxes, mailbox);
+  if (resolved.kind === "found") return resolved.path;
+  const flag = SPECIAL_USE_ALIASES[mailbox.trim().toLowerCase()];
+  if (flag) {
+    const special = boxes.find((b) => b.specialUse?.toLowerCase() === flag);
+    if (special) return special.path;
+  }
+  if (resolved.kind === "ambiguous") {
+    throw new Error(ambiguousMailboxError(mailbox, resolved.candidates));
   }
   return staticMailboxAlias(mailbox);
 }
@@ -58391,6 +58410,13 @@ function structuredRow(m, account, path) {
     ...env.messageId ? { messageId: env.messageId } : {}
   };
 }
+function describeMailboxFailure(error) {
+  const raw = errText(error);
+  const oneLine = raw.split("\n")[0].trim();
+  const looksSensitive = /pass(word)?\s*[:=]|authorization:\s*\S|bearer\s+\S{10,}/i.test(oneLine);
+  const safe = looksSensitive ? "IMAP error (detail redacted \u2014 response text looked like it might contain a credential)" : oneLine || "unknown error";
+  return safe.length > 300 ? `${safe.slice(0, 300)}\u2026` : safe;
+}
 function hasMailboxFlag(mailbox, wanted) {
   const normalized = wanted.toLowerCase();
   return [...mailbox.flags ?? []].some((flag) => flag.toLowerCase() === normalized);
@@ -58472,6 +58498,7 @@ async function run(args, listMode, deps) {
       const newestPerMailbox = offset + limit;
       const fetched = [];
       const failedMailboxes = [];
+      const failedMailboxReasons = {};
       let totalMatched = 0;
       for (const path of paths) {
         try {
@@ -58480,14 +58507,16 @@ async function run(args, listMode, deps) {
           fetched.push(...result.messages.map((message) => ({ message, path })));
         } catch (error) {
           failedMailboxes.push(path);
+          failedMailboxReasons[path] = describeMailboxFailure(error);
           console.error(
             `IMAP ${listMode ? "list" : "search"} failed for account "${cfg.accountLabel}", mailbox "${path}": ${String(error)}`
           );
         }
       }
       if (failedMailboxes.length === paths.length) {
+        const detail = failedMailboxes.map((path) => `${path} (${failedMailboxReasons[path]})`).join(", ");
         throw new Error(
-          `IMAP ${listMode ? "list" : "search"} failed in every requested mailbox for account ${cfg.accountLabel}: ${failedMailboxes.join(", ")}.`
+          `IMAP ${listMode ? "list" : "search"} failed in every requested mailbox for account ${cfg.accountLabel}: ${detail}.`
         );
       }
       let ordered = fetched;
@@ -58509,7 +58538,7 @@ async function run(args, listMode, deps) {
       const partial = failedMailboxes.length > 0;
       const failureNote = partial ? `
 
-Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"${path}"`).join(", ")}.` : "";
+Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"${path}" (${failedMailboxReasons[path]})`).join(", ")}.` : "";
       const verb = listMode ? "listed" : "matched";
       const scope = unscopedSearch ? allMailboxCount === 1 ? `mailbox "${paths[0]}"` : `${allMailboxCount} selectable mailboxes` : `mailbox "${paths[0]}"`;
       if (messages.length === 0) {
@@ -58518,14 +58547,22 @@ Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"
           messages,
           count: 0,
           partial,
-          failedMailboxes
+          failedMailboxes,
+          failedMailboxReasons
         };
       }
       const text = `Found ${rows.length} message(s) via IMAP (server-side, account ${cfg.accountLabel}, ${scope}; ${totalMatched} total ${verb}):
 ` + rows.join("\n") + `
 
 Note: these IMAP IDs (imap:\u2026) work with get-message and the message mutations (mark/flag/move/delete-message), which route back to IMAP.` + failureNote;
-      return { text, messages, count: messages.length, partial, failedMailboxes };
+      return {
+        text,
+        messages,
+        count: messages.length,
+        partial,
+        failedMailboxes,
+        failedMailboxReasons
+      };
     },
     true
   );
@@ -58612,7 +58649,13 @@ function imapMailStats(deps = {}) {
   );
 }
 function errText(e) {
-  return e instanceof Error ? e.message : String(e);
+  if (!(e instanceof Error)) return String(e);
+  const x = e;
+  if (typeof x.responseStatus !== "string" || !x.responseStatus) return e.message;
+  const code = typeof x.serverResponseCode === "string" && x.serverResponseCode;
+  const text = typeof x.responseText === "string" ? x.responseText.trim() : "";
+  const server = [x.responseStatus, code ? `[${code}]` : "", text].filter(Boolean).join(" ");
+  return e.message && e.message !== "Command failed" ? `${e.message}: ${server}` : server;
 }
 function assertMutated(result, what) {
   if (!result) throw new Error(`${what}: server rejected the command (IMAP NO/BAD)`);
@@ -58764,20 +58807,30 @@ function withClient(deps, fn) {
   return useClient(deps, fn);
 }
 async function resolveMailbox(client, name) {
-  const wanted = name.trim().toLowerCase();
   const boxes = await client.list();
-  const byPath = boxes.find((b) => b.path.toLowerCase() === wanted);
-  if (byPath) return { kind: "found", path: byPath.path };
-  const byName = boxes.filter((b) => b.name.toLowerCase() === wanted);
-  if (byName.length === 1) return { kind: "found", path: byName[0].path };
-  if (byName.length > 1) {
-    return { kind: "ambiguous", candidates: byName.map((b) => b.path).sort() };
+  return matchMailbox(boxes, name);
+}
+function matchMailbox(boxes, name) {
+  const exact = boxes.find((b) => b.path === name || b.path === name.trim());
+  if (exact) return { kind: "found", path: exact.path };
+  const wanted = mailboxNameKey(name);
+  const tiers = [
+    boxes.filter((b) => mailboxNameKey(b.path) === wanted),
+    boxes.filter((b) => mailboxNameKey(b.name) === wanted)
+  ];
+  for (const hits of tiers) {
+    const paths = [...new Set(hits.map((b) => b.path))];
+    if (paths.length === 1) return { kind: "found", path: paths[0] };
+    if (paths.length > 1) return { kind: "ambiguous", candidates: paths.sort() };
   }
   return { kind: "none" };
 }
 function ambiguousMailboxError(name, candidates, accountLabel) {
   const where = accountLabel ? ` on IMAP account ${accountLabel}` : "";
-  return `Mailbox "${name}" is ambiguous${where} \u2014 it matches ${candidates.map((c) => `"${c}"`).join(" and ")}. Pass the full path.`;
+  const listed = candidates.map((c) => `"${c}"`).join(" and ");
+  const indistinguishable = new Set(candidates.map(mailboxNameKey)).size === 1;
+  const hint = indistinguishable ? " They differ only in letter case or Unicode normalization (precomposed vs decomposed accents), so no typed name can tell them apart. Rename one of them." : " Pass the full path.";
+  return `Mailbox "${name}" is ambiguous${where} \u2014 it matches ${listed}.${hint}`;
 }
 async function findMailboxPathOrThrow(client, name) {
   const res = await resolveMailbox(client, name);
@@ -58786,6 +58839,15 @@ async function findMailboxPathOrThrow(client, name) {
 }
 function imapCreateMailbox(name, deps = {}) {
   return withClient(deps, async (client) => {
+    let twin;
+    try {
+      const wanted = nfc(name);
+      twin = (await client.list()).find((b) => nfc(b.path) === wanted)?.path;
+    } catch {
+    }
+    if (twin !== void 0) {
+      return { success: true, info: `Mailbox "${twin}" already existed.` };
+    }
     try {
       const res = await client.mailboxCreate(name);
       return res.created ? { success: true, info: `Created mailbox "${res.path}".` } : { success: true, info: `Mailbox "${res.path}" already existed.` };
@@ -58837,6 +58899,14 @@ function imapRenameMailbox(oldName, newName, deps = {}) {
       };
     }
     const path = found.path;
+    const wantedNew = nfc(newName);
+    const clash = (await client.list()).find((b) => b.path !== path && nfc(b.path) === wantedNew);
+    if (clash) {
+      return {
+        success: false,
+        error: `Cannot rename "${path}" to "${newName}": mailbox "${clash.path}" already exists on IMAP account ${cfg.accountLabel} (the same name, differing only in how its accents are encoded).`
+      };
+    }
     try {
       const res = await client.mailboxRename(path, newName);
       return { success: true, info: `Renamed "${res.path}" to "${res.newPath}" via IMAP.` };
@@ -59491,6 +59561,7 @@ var init_imapClient = __esm({
     import_imapflow = __toESM(require_imap_flow(), 1);
     init_smtpMailer();
     init_docsUrls();
+    init_mailboxName();
     init_mimeParse();
     init_headers();
     init_auditLog();

package/build/index.js

@@ -7681,6 +7681,19 @@ var init_headers = __esm({
   }
 });
 
+// src/utils/mailboxName.ts
+function mailboxNameKey(name) {
+  return name.trim().normalize("NFC").toLowerCase();
+}
+function nfc(name) {
+  return name.trim().normalize("NFC");
+}
+var init_mailboxName = __esm({
+  "src/utils/mailboxName.ts"() {
+    "use strict";
+  }
+});
+
 // src/utils/attachmentLimits.ts
 function isInlineAttachmentBase64WithinLimit(contentBase64) {
   if (contentBase64.length > MAX_INLINE_ATTACHMENT_BASE64_INPUT_CHARS) return false;
@@ -65405,6 +65418,7 @@ __export(imapClient_exports, {
   listImapAccountLabels: () => listImapAccountLabels,
   mailFlagBitsFor: () => mailFlagBitsFor,
   mailFlagColorIndex: () => mailFlagColorIndex,
+  matchMailbox: () => matchMailbox,
   normalizeMessageId: () => normalizeMessageId,
   resolveImapConfig: () => resolveImapConfig,
   resolveImapConfigs: () => resolveImapConfigs,
@@ -65619,16 +65633,21 @@ function staticMailboxAlias(mailbox) {
 }
 async function resolveMailboxPath(client, mailbox, _mode) {
   if (!mailbox) return "INBOX";
+  let boxes;
   try {
-    const resolved = await resolveMailbox(client, mailbox);
-    if (resolved.kind === "found") return resolved.path;
-    const flag = SPECIAL_USE_ALIASES[mailbox.trim().toLowerCase()];
-    if (flag) {
-      const boxes = await client.list();
-      const special = boxes.find((b) => b.specialUse?.toLowerCase() === flag);
-      if (special) return special.path;
-    }
+    boxes = await client.list();
   } catch {
+    return staticMailboxAlias(mailbox);
+  }
+  const resolved = matchMailbox(boxes, mailbox);
+  if (resolved.kind === "found") return resolved.path;
+  const flag = SPECIAL_USE_ALIASES[mailbox.trim().toLowerCase()];
+  if (flag) {
+    const special = boxes.find((b) => b.specialUse?.toLowerCase() === flag);
+    if (special) return special.path;
+  }
+  if (resolved.kind === "ambiguous") {
+    throw new Error(ambiguousMailboxError(mailbox, resolved.candidates));
   }
   return staticMailboxAlias(mailbox);
 }
@@ -65720,6 +65739,13 @@ function structuredRow(m, account, path) {
     ...env.messageId ? { messageId: env.messageId } : {}
   };
 }
+function describeMailboxFailure(error2) {
+  const raw = errText(error2);
+  const oneLine = raw.split("\n")[0].trim();
+  const looksSensitive = /pass(word)?\s*[:=]|authorization:\s*\S|bearer\s+\S{10,}/i.test(oneLine);
+  const safe = looksSensitive ? "IMAP error (detail redacted \u2014 response text looked like it might contain a credential)" : oneLine || "unknown error";
+  return safe.length > 300 ? `${safe.slice(0, 300)}\u2026` : safe;
+}
 function hasMailboxFlag(mailbox, wanted) {
   const normalized = wanted.toLowerCase();
   return [...mailbox.flags ?? []].some((flag) => flag.toLowerCase() === normalized);
@@ -65801,6 +65827,7 @@ async function run(args, listMode, deps) {
       const newestPerMailbox = offset + limit;
       const fetched = [];
       const failedMailboxes = [];
+      const failedMailboxReasons = {};
       let totalMatched = 0;
       for (const path of paths) {
         try {
@@ -65809,14 +65836,16 @@ async function run(args, listMode, deps) {
           fetched.push(...result.messages.map((message) => ({ message, path })));
         } catch (error2) {
           failedMailboxes.push(path);
+          failedMailboxReasons[path] = describeMailboxFailure(error2);
           console.error(
             `IMAP ${listMode ? "list" : "search"} failed for account "${cfg.accountLabel}", mailbox "${path}": ${String(error2)}`
           );
         }
       }
       if (failedMailboxes.length === paths.length) {
+        const detail = failedMailboxes.map((path) => `${path} (${failedMailboxReasons[path]})`).join(", ");
         throw new Error(
-          `IMAP ${listMode ? "list" : "search"} failed in every requested mailbox for account ${cfg.accountLabel}: ${failedMailboxes.join(", ")}.`
+          `IMAP ${listMode ? "list" : "search"} failed in every requested mailbox for account ${cfg.accountLabel}: ${detail}.`
         );
       }
       let ordered = fetched;
@@ -65838,7 +65867,7 @@ async function run(args, listMode, deps) {
       const partial2 = failedMailboxes.length > 0;
       const failureNote = partial2 ? `
 
-Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"${path}"`).join(", ")}.` : "";
+Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"${path}" (${failedMailboxReasons[path]})`).join(", ")}.` : "";
       const verb = listMode ? "listed" : "matched";
       const scope = unscopedSearch ? allMailboxCount === 1 ? `mailbox "${paths[0]}"` : `${allMailboxCount} selectable mailboxes` : `mailbox "${paths[0]}"`;
       if (messages.length === 0) {
@@ -65847,14 +65876,22 @@ Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"
           messages,
           count: 0,
           partial: partial2,
-          failedMailboxes
+          failedMailboxes,
+          failedMailboxReasons
         };
       }
       const text = `Found ${rows.length} message(s) via IMAP (server-side, account ${cfg.accountLabel}, ${scope}; ${totalMatched} total ${verb}):
 ` + rows.join("\n") + `
 
 Note: these IMAP IDs (imap:\u2026) work with get-message and the message mutations (mark/flag/move/delete-message), which route back to IMAP.` + failureNote;
-      return { text, messages, count: messages.length, partial: partial2, failedMailboxes };
+      return {
+        text,
+        messages,
+        count: messages.length,
+        partial: partial2,
+        failedMailboxes,
+        failedMailboxReasons
+      };
     },
     true
   );
@@ -65941,7 +65978,13 @@ function imapMailStats(deps = {}) {
   );
 }
 function errText(e) {
-  return e instanceof Error ? e.message : String(e);
+  if (!(e instanceof Error)) return String(e);
+  const x = e;
+  if (typeof x.responseStatus !== "string" || !x.responseStatus) return e.message;
+  const code = typeof x.serverResponseCode === "string" && x.serverResponseCode;
+  const text = typeof x.responseText === "string" ? x.responseText.trim() : "";
+  const server2 = [x.responseStatus, code ? `[${code}]` : "", text].filter(Boolean).join(" ");
+  return e.message && e.message !== "Command failed" ? `${e.message}: ${server2}` : server2;
 }
 function assertMutated(result, what) {
   if (!result) throw new Error(`${what}: server rejected the command (IMAP NO/BAD)`);
@@ -66093,20 +66136,30 @@ function withClient(deps, fn) {
   return useClient(deps, fn);
 }
 async function resolveMailbox(client, name) {
-  const wanted = name.trim().toLowerCase();
   const boxes = await client.list();
-  const byPath = boxes.find((b) => b.path.toLowerCase() === wanted);
-  if (byPath) return { kind: "found", path: byPath.path };
-  const byName = boxes.filter((b) => b.name.toLowerCase() === wanted);
-  if (byName.length === 1) return { kind: "found", path: byName[0].path };
-  if (byName.length > 1) {
-    return { kind: "ambiguous", candidates: byName.map((b) => b.path).sort() };
+  return matchMailbox(boxes, name);
+}
+function matchMailbox(boxes, name) {
+  const exact = boxes.find((b) => b.path === name || b.path === name.trim());
+  if (exact) return { kind: "found", path: exact.path };
+  const wanted = mailboxNameKey(name);
+  const tiers = [
+    boxes.filter((b) => mailboxNameKey(b.path) === wanted),
+    boxes.filter((b) => mailboxNameKey(b.name) === wanted)
+  ];
+  for (const hits of tiers) {
+    const paths = [...new Set(hits.map((b) => b.path))];
+    if (paths.length === 1) return { kind: "found", path: paths[0] };
+    if (paths.length > 1) return { kind: "ambiguous", candidates: paths.sort() };
   }
   return { kind: "none" };
 }
 function ambiguousMailboxError(name, candidates, accountLabel) {
   const where = accountLabel ? ` on IMAP account ${accountLabel}` : "";
-  return `Mailbox "${name}" is ambiguous${where} \u2014 it matches ${candidates.map((c) => `"${c}"`).join(" and ")}. Pass the full path.`;
+  const listed = candidates.map((c) => `"${c}"`).join(" and ");
+  const indistinguishable = new Set(candidates.map(mailboxNameKey)).size === 1;
+  const hint = indistinguishable ? " They differ only in letter case or Unicode normalization (precomposed vs decomposed accents), so no typed name can tell them apart. Rename one of them." : " Pass the full path.";
+  return `Mailbox "${name}" is ambiguous${where} \u2014 it matches ${listed}.${hint}`;
 }
 async function findMailboxPathOrThrow(client, name) {
   const res = await resolveMailbox(client, name);
@@ -66115,6 +66168,15 @@ async function findMailboxPathOrThrow(client, name) {
 }
 function imapCreateMailbox(name, deps = {}) {
   return withClient(deps, async (client) => {
+    let twin;
+    try {
+      const wanted = nfc(name);
+      twin = (await client.list()).find((b) => nfc(b.path) === wanted)?.path;
+    } catch {
+    }
+    if (twin !== void 0) {
+      return { success: true, info: `Mailbox "${twin}" already existed.` };
+    }
     try {
       const res = await client.mailboxCreate(name);
       return res.created ? { success: true, info: `Created mailbox "${res.path}".` } : { success: true, info: `Mailbox "${res.path}" already existed.` };
@@ -66166,6 +66228,14 @@ function imapRenameMailbox(oldName, newName, deps = {}) {
       };
     }
     const path = found.path;
+    const wantedNew = nfc(newName);
+    const clash = (await client.list()).find((b) => b.path !== path && nfc(b.path) === wantedNew);
+    if (clash) {
+      return {
+        success: false,
+        error: `Cannot rename "${path}" to "${newName}": mailbox "${clash.path}" already exists on IMAP account ${cfg.accountLabel} (the same name, differing only in how its accents are encoded).`
+      };
+    }
     try {
       const res = await client.mailboxRename(path, newName);
       return { success: true, info: `Renamed "${res.path}" to "${res.newPath}" via IMAP.` };
@@ -66820,6 +66890,7 @@ var init_imapClient = __esm({
     import_imapflow = __toESM(require_imap_flow(), 1);
     init_smtpMailer();
     init_docsUrls();
+    init_mailboxName();
     init_mimeParse();
     init_headers();
     init_auditLog();
@@ -81913,6 +81984,7 @@ function executeAppleScript(script, options = {}) {
 init_docsUrls();
 init_mimeParse();
 init_headers();
+init_mailboxName();
 
 // src/services/templateStore.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
@@ -82548,23 +82620,28 @@ function mailboxLeaf(path) {
 function resolveAppleMailboxPath(mailbox, actualPaths) {
   if (actualPaths.length === 0) return mailbox;
   const candidates = [mailbox, ...MAILBOX_ALIASES[mailbox.toLowerCase()] ?? []];
+  const ambiguous = (matches) => {
+    const sorted = [...new Set(matches)].sort();
+    const paths = sorted.map((path) => `"${path}"`).join(" and ");
+    const twins = new Set(sorted.map(mailboxNameKey)).size === 1;
+    const hint = twins ? " They differ only in letter case or Unicode normalization (precomposed vs decomposed accents), so no typed name can tell them apart. Rename one of them." : " Pass the full path.";
+    return new Error(`Mailbox "${mailbox}" is ambiguous \u2014 it matches ${paths}.${hint}`);
+  };
   for (const candidate of candidates) {
     const exact = actualPaths.find((path) => path === candidate);
     if (exact) return exact;
-    const folded = actualPaths.find((path) => path.toLowerCase() === candidate.toLowerCase());
-    if (folded) return folded;
+    const key = mailboxNameKey(candidate);
+    const folded = [...new Set(actualPaths.filter((path) => mailboxNameKey(path) === key))];
+    if (folded.length === 1) return folded[0];
+    if (folded.length > 1) throw ambiguous(folded);
   }
   for (const candidate of candidates) {
-    const leafMatches = actualPaths.filter(
-      (path) => mailboxLeaf(path).toLowerCase() === candidate.toLowerCase()
-    );
+    const key = mailboxNameKey(candidate);
+    const leafMatches = [
+      ...new Set(actualPaths.filter((path) => mailboxNameKey(mailboxLeaf(path)) === key))
+    ];
     if (leafMatches.length === 1) return leafMatches[0];
-    if (leafMatches.length > 1) {
-      const paths = [...leafMatches].sort().map((path) => `"${path}"`).join(" and ");
-      throw new Error(
-        `Mailbox "${mailbox}" is ambiguous \u2014 it matches ${paths}. Pass the full path.`
-      );
-    }
+    if (leafMatches.length > 1) throw ambiguous(leafMatches);
   }
   return mailbox;
 }
@@ -87359,6 +87436,7 @@ async function fanOutImapMessages(args, kind, deps = {}, configs = resolveImapCo
   const accountsQueried = [];
   const accountsFailed = [];
   const failedMailboxes = [];
+  const failedMailboxReasons = {};
   for (const config2 of configs) {
     const perAccountArgs = { ...args, account: void 0 };
     try {
@@ -87368,12 +87446,15 @@ async function fanOutImapMessages(args, kind, deps = {}, configs = resolveImapCo
       failedMailboxes.push(
         ...res.failedMailboxes.map((mailbox) => `${config2.accountLabel} / ${mailbox}`)
       );
+      for (const [mailbox, reason] of Object.entries(res.failedMailboxReasons)) {
+        failedMailboxReasons[`${config2.accountLabel} / ${mailbox}`] = reason;
+      }
     } catch (e) {
       accountsFailed.push(config2.accountLabel);
       console.error(`IMAP fan-out failed for account "${config2.accountLabel}": ${String(e)}`);
     }
   }
-  return { rows, accountsQueried, accountsFailed, failedMailboxes };
+  return { rows, accountsQueried, accountsFailed, failedMailboxes, failedMailboxReasons };
 }
 function configMatchesAccount(config2, account) {
   const name = account.name.trim().toLowerCase();
@@ -87973,7 +88054,10 @@ var LIST_OUTPUT_SCHEMA = {
   skippedLargeMailboxes: external_exports.array(external_exports.string()).optional(),
   notSearchedMailboxes: external_exports.array(external_exports.string()).optional(),
   timedOutAccounts: external_exports.array(external_exports.string()).optional(),
-  failedMailboxes: external_exports.array(external_exports.string()).optional()
+  failedMailboxes: external_exports.array(external_exports.string()).optional(),
+  // Underlying error text per entry in `failedMailboxes`, same keys (#246
+  // follow-up) — declared so a client can rely on it rather than parse text.
+  failedMailboxReasons: external_exports.record(external_exports.string(), external_exports.string()).optional()
 };
 var BATCH_COUNT_OUTPUT_SCHEMA = {
   ok: external_exports.boolean().optional(),
@@ -88063,7 +88147,8 @@ function mergedMessageResponse(fan, apple, limit, verb) {
     skippedLargeMailboxes: diagnostics.skippedLargeMailboxes,
     notSearchedMailboxes: diagnostics.notSearchedMailboxes,
     timedOutAccounts: diagnostics.timedOutAccounts,
-    failedMailboxes: fan.failedMailboxes
+    failedMailboxes: fan.failedMailboxes,
+    failedMailboxReasons: fan.failedMailboxReasons
   };
   const coverageBlock = partialCoverageBlock(diagnostics);
   if (merged.length === 0) {
@@ -88165,7 +88250,8 @@ registerTool(
             messages: r.messages,
             count: r.count,
             partial: r.partial,
-            failedMailboxes: r.failedMailboxes
+            failedMailboxes: r.failedMailboxes,
+            failedMailboxReasons: r.failedMailboxReasons
           });
         }
         const fan = await fanOutImapMessages(imapArgs, "search");
@@ -88548,7 +88634,8 @@ ${r.text}`, {
           messages: r.messages,
           count: r.count,
           partial: r.partial,
-          failedMailboxes: r.failedMailboxes
+          failedMailboxes: r.failedMailboxes,
+          failedMailboxReasons: r.failedMailboxReasons
         });
       }
       const fan = await fanOutImapMessages({ subject: base, mailbox, limit }, "search");
@@ -88585,7 +88672,8 @@ ${r.text}`, {
         messages: orderedRows,
         count: orderedRows.length,
         partial: partial2,
-        failedMailboxes: fan.failedMailboxes
+        failedMailboxes: fan.failedMailboxes,
+        failedMailboxReasons: fan.failedMailboxReasons
       };
       if (orderedRows.length === 0) {
         return successResponse(`No messages found in thread "${base}".${coverage}`, structured2);
@@ -88649,7 +88737,8 @@ registerTool(
           messages: r.messages,
           count: r.count,
           partial: r.partial,
-          failedMailboxes: r.failedMailboxes
+          failedMailboxes: r.failedMailboxes,
+          failedMailboxReasons: r.failedMailboxReasons
         });
       }
       const fan = await fanOutImapMessages({ mailbox, limit, offset, from, unreadOnly }, "list");

package/package.json

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