apple-mail-mcp 2.20.2 → 2.20.4

package/README.md

@@ -309,15 +309,17 @@ inferred from the top-level `Content-Type`.
 
 Get the full content of a message.
 
-| Parameter    | Type    | Required | Description                                                                                                                                                                      |
-| ------------ | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`         | string  | Yes      | Message ID                                                                                                                                                                       |
-| `preferHtml` | boolean | No       | Return HTML source instead of plain text                                                                                                                                         |
-| `mailbox`    | string  | No       | Mailbox holding the message (e.g. `"Sent Items"`). With `account`, opens that mailbox directly instead of scanning every mailbox — this is the fix for timeouts on large folders |
-| `account`    | string  | No       | Account holding the message. Pair with `mailbox` to skip the cross-mailbox scan                                                                                                  |
+| Parameter    | Type    | Required | Description                                                                                                                                                                                                                                                                                       |
+| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`         | string  | Yes      | Message ID                                                                                                                                                                                                                                                                                        |
+| `preferHtml` | boolean | No       | Return HTML source instead of plain text                                                                                                                                                                                                                                                          |
+| `mailbox`    | string  | No       | Mailbox holding the message (e.g. `"Sent Items"`). With `account`, opens that mailbox directly instead of scanning every mailbox — this is the fix for timeouts on large folders. A miss there is reported as "not found in <account> / <mailbox>"; it never falls back to the cross-mailbox scan |
+| `account`    | string  | No       | Account holding the message. Pair with `mailbox` to skip the cross-mailbox scan                                                                                                                                                                                                                   |
 
 **Returns:** Subject line and message body (plain text by default, HTML if `preferHtml` is true and HTML content is available). `structuredContent` also carries `rfcMessageId` and, since 2.19.0, two dates: `dateSent` (the message's `Date:` header — Mail's `date sent`) and `dateReceived` (arrival in the mailbox — Mail's `date received` / IMAP `INTERNALDATE`). They differ legitimately by transit time; when they differ by **years**, the mailbox was migrated or re-imported and the arrival timestamp was reset — trust `dateSent` for chronology ([#224](https://github.com/sweetrb/apple-mail-mcp/issues/224)). Since 2.19.6 `dateSent` is **omitted** when it is more than 7 days later than `dateReceived`: a message cannot be sent after it arrived, and Mail.app substitutes a timestamp of its own for a `Date:` header it cannot parse ([#234](https://github.com/sweetrb/apple-mail-mcp/issues/234)). `isHtml` reports what was actually returned — a message with no `text/plain` part returns its HTML part with `isHtml: true`. Bodies are decoded by each part's declared `charset`, falling back to windows-1252 for bytes that are not valid UTF-8.
 
+**Numeric ids — how the message is found ([#270](https://github.com/sweetrb/apple-mail-mcp/issues/270)):** with `account` + `mailbox` the read opens that one mailbox and stops there. Otherwise it opens the mailbox the id was last listed or searched from (a remembered location that turns out stale — the message was moved, e.g. by another client — is forgotten), and only then scans every mailbox. That cross-mailbox scan skips any mailbox holding more than `APPLE_MAIL_MAX_BYID_SCAN_MAILBOX` messages (default `50000`; `0` disables the guard) and stops after ~9s, because Mail's `whose id is` probe costs seconds per hundred thousand messages; a miss then names the mailboxes it did not scan. Pass `account` + `mailbox` to read from one of those, or use the message's `imap:` id, which never scans. The same resolution backs `get-message-headers`, `get-thread`'s seed lookup, and the original-message read of `reply-to-message` / `forward-message` and the attachment tools.
+
 > **Large messages / attachments:** reading a full message routes through
 > `osascript`, whose captured output buffer defaults to **64 MB**. Override it
 > with the `APPLE_MAIL_MCP_MAX_BUFFER` environment variable (in **bytes**) if you
@@ -2127,6 +2129,10 @@ In a JSON string literal, `\\` — two characters — denotes **one** literal ba
 - Message may have been deleted or moved
 - Message IDs change if the message is moved between mailboxes
 - Use `search-messages` to find the current message ID
+- "**not found in the mailboxes scanned**" with a list of mailboxes means the numeric-id scan
+  skipped those because they hold more than `APPLE_MAIL_MAX_BYID_SCAN_MAILBOX` messages (default
+  `50000`). The message may be in one of them: pass `account` + `mailbox` to read it from there, or
+  use its `imap:` id ([#270](https://github.com/sweetrb/apple-mail-mcp/issues/270)).
 
 ### "... is present in more than one mailbox"
 

package/build/index.js

@@ -82325,7 +82325,8 @@ function executeAppleScript(script, options = {}) {
       lastError = {
         success: false,
         output: "",
-        error: errorMessage
+        error: errorMessage,
+        ...isTimeout ? { timedOut: true } : {}
       };
       const canRetry = isTimeout || isRetryableError(errorMessage);
       const hasAttemptsLeft = attempt < maxRetries;
@@ -82598,6 +82599,48 @@ function getMailboxScanThreshold() {
 }
 var SEARCH_ACCOUNT_BUDGET_SECONDS = 30;
 var SEARCH_ACCOUNT_TIMEOUT_MS = 45e3;
+var READ_ONLY_BYID_TIMEOUT_MS = 15e3;
+function timedOutResolvingId(id) {
+  return `AppleScript timed out resolving id ${Number(id)} \u2014 Mail.app's scripting bridge may be wedged; try health-check.`;
+}
+function timedOutScanningForId(id) {
+  return `AppleScript timed out scanning every mailbox for id ${Number(id)} \u2014 the cross-mailbox scan did not finish within ${READ_ONLY_BYID_TIMEOUT_MS / 1e3}s (very large mailboxes; if health-check also fails, Mail.app's scripting bridge may be wedged). Pass account + mailbox to read it from one mailbox, or use the message's imap: id from list-messages/search-messages.`;
+}
+function getByIdScanThreshold() {
+  const raw = process.env.APPLE_MAIL_MAX_BYID_SCAN_MAILBOX;
+  if (raw !== void 0 && raw.trim() !== "") {
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0) return Math.floor(n);
+  }
+  return 5e4;
+}
+var BYID_SCAN_BUDGET_SECONDS = 9;
+var BYID_COVERAGE_MARKER = "COV";
+var SCOPED_MISS_MARKER = "SCOPED";
+function describeUnscopedMiss(id, raw) {
+  const covIdx = raw.indexOf(BYID_COVERAGE_MARKER);
+  if (covIdx === -1) return raw.trim();
+  const base2 = raw.slice(0, covIdx).trim();
+  const [skippedRaw = "", budgetRaw = ""] = raw.slice(covIdx + BYID_COVERAGE_MARKER.length).split(DIAG_FIELD_SEP);
+  const skipped = skippedRaw.split(DIAG_ITEM_SEP).map((s) => s.trim()).filter(Boolean);
+  const budgetHit = budgetRaw.trim() === "true";
+  if (skipped.length === 0 && !budgetHit) return base2;
+  const parts = [`Message ${Number(id)} not found in the mailboxes scanned.`];
+  if (skipped.length > 0) {
+    parts.push(
+      `Not scanned \u2014 too large for a cross-mailbox id scan (over ${getByIdScanThreshold()} messages; APPLE_MAIL_MAX_BYID_SCAN_MAILBOX): ${skipped.join(", ")}.`
+    );
+  }
+  if (budgetHit) {
+    parts.push(
+      `The scan also stopped after its ${BYID_SCAN_BUDGET_SECONDS}s budget before reaching every mailbox.`
+    );
+  }
+  parts.push(
+    "If the message is in a mailbox that was not scanned, pass account + mailbox to read it from that mailbox directly, or use its imap: id from list-messages/search-messages."
+  );
+  return parts.join(" ");
+}
 var GROUP_SEP = "";
 var FIELD_SEP = "";
 var RECORD_SEP = "";
@@ -83103,8 +83146,9 @@ var AppleMailManager = class {
    * Items") isn't reached before the AppleScript timeout fires, so the fetch
    * returns a false "not found" (only INBOX ids, reached early, worked). Every
    * search/list/by-id result records its id→location here so a subsequent fetch
-   * opens the one right mailbox directly. A stale entry (message moved) simply
-   * misses and falls back to the full scan, so it can never wedge a lookup.
+   * opens the one right mailbox directly. A stale entry (message moved by
+   * another client) misses, is EVICTED, and the read falls back to the bounded
+   * cross-mailbox scan — see `resolveScopedById` (#270).
    */
   idLocationIndex = /* @__PURE__ */ new Map();
   /** Error from the most recent numeric message read, if it was refused. */
@@ -84204,24 +84248,22 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
   /**
    * Get a message by ID.
    *
-   * Note: Mail.app message IDs are unique per mailbox. This method searches
-   * all mailboxes in all accounts to find the message.
+   * Note: Mail.app message IDs are unique per mailbox. Resolution goes through
+   * `resolveById` — the remembered location first, then the bounded
+   * cross-mailbox scan — taking the FIRST copy found rather than refusing an id
+   * a label store repeats across INBOX / "All Mail": every caller of this reads
+   * per-message metadata (get-thread's seed subject, a mutation error's mailbox
+   * hint) that is identical across those copies.
    */
   getMessageById(id, deepAttachmentCheck = false) {
+    this.lastMessageLookupError = void 0;
     const deepScan = deepAttachmentCheck ? `if hasAtt is "false" then
                   try
                     set rawSrc to source of msg
                     if rawSrc contains "Content-Disposition: attachment" then set hasAtt to "true"
                   end try
                 end if` : "";
-    const script = buildAppLevelScript(`
-      try
-        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
+    const innerFetch = `
                 set msgSubject to subject of msg
                 set msgSender to sender of msg
                 set d to date received of msg
@@ -84231,30 +84273,20 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
                 set msgJunk to junk mail status of msg as string
                 set msgDeleted to deleted status of msg as string
                 set msgMailbox to ""
-                ${mailboxPathFragment("mb", "msgMailbox")}
-                set msgAccount to name of acct
+                try
+                  ${mailboxPathFragment("_hitMb", "msgMailbox")}
+                end try
+                set msgAccount to _hitAcct
                 set hasAtt to "false"
                 try
                   set attCount to count of mail attachments of msg
                   if attCount > 0 then set hasAtt to "true"
                 end try
                 ${deepScan}
-                return msgSubject & "${FIELD_SEP}" & msgSender & "${FIELD_SEP}" & msgDate & "${FIELD_SEP}" & msgRead & "${FIELD_SEP}" & msgFlagged & "${FIELD_SEP}" & msgJunk & "${FIELD_SEP}" & msgDeleted & "${FIELD_SEP}" & msgMailbox & "${FIELD_SEP}" & msgAccount & "${FIELD_SEP}" & hasAtt
-              end if
-            end try
-          end repeat
-        end repeat
-        return ""
-      on error errMsg
-        return ""
-      end try
-    `);
-    const result = executeAppleScript(script, { timeoutMs: 6e4 });
-    if (!result.success || !result.output.trim()) {
-      console.error(`Failed to get message ${id}: ${result.error}`);
-      return null;
-    }
-    const parts = result.output.split(FIELD_SEP);
+                return msgSubject & "${FIELD_SEP}" & msgSender & "${FIELD_SEP}" & msgDate & "${FIELD_SEP}" & msgRead & "${FIELD_SEP}" & msgFlagged & "${FIELD_SEP}" & msgJunk & "${FIELD_SEP}" & msgDeleted & "${FIELD_SEP}" & msgMailbox & "${FIELD_SEP}" & msgAccount & "${FIELD_SEP}" & hasAtt`;
+    const output = this.resolveById(id, innerFetch, void 0, { firstHit: true });
+    if (output === null) return null;
+    const parts = output.split(FIELD_SEP);
     if (parts.length < 9) return null;
     this.rememberLocation(id.toString(), parts[8], parts[7]);
     return {
@@ -84272,47 +84304,194 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       hasAttachments: parts.length > 9 ? parts[9] === "true" : false
     };
   }
+  /**
+   * Resolve numeric `id` and run `innerAction` against it — the ONE resolution
+   * path behind every read-only by-id lookup (getMessageById,
+   * getMessageContent, getMessageHeaders, getRawSource), so the four cannot
+   * drift apart again. Returns the action's output, or null with
+   * `lastMessageLookupError` set when there is something to say (#270):
+   *
+   *  1. Scoped, when a location is known — the caller's explicit `account` +
+   *     `mailbox`, else the `idLocationIndex` entry (see `resolveScopedById`):
+   *     - explicit hint, miss → a clean "not found in <account> / <mailbox>".
+   *       NO fallback: the caller said where to look, and the cross-mailbox
+   *       scan it would fall back to is the 20-50s operation @j5pu timed.
+   *     - index entry, miss → the entry is stale (the message was moved, by
+   *       another client or in Mail itself): evict it, then fall back to (2).
+   *     - timeout on either → report it; no second 15s scan on top.
+   *  2. Unscoped: every mailbox of every account plus the local store, but
+   *     mailboxes above `getByIdScanThreshold()` are skipped and the walk stops
+   *     at `BYID_SCAN_BUDGET_SECONDS`; a miss names what was not covered.
+   */
+  resolveById(id, innerAction, hint, opts = {}) {
+    const remembered = this.idLocationIndex.get(String(id));
+    const loc = hint?.account && hint?.mailbox ? { account: hint.account, mailbox: hint.mailbox, explicit: true } : remembered ? { ...remembered, explicit: false } : void 0;
+    if (loc) {
+      const scoped = this.resolveScopedById(id, loc, innerAction);
+      if (scoped.kind === "hit") return scoped.output;
+      if (scoped.kind === "done") return null;
+    }
+    const result = executeAppleScript(this.unscopedByIdScript(id, innerAction, opts), {
+      timeoutMs: READ_ONLY_BYID_TIMEOUT_MS
+    });
+    if (!result.success || !result.output.trim()) {
+      if (!result.success) {
+        if (result.timedOut) this.lastMessageLookupError = timedOutScanningForId(id);
+        console.error(`Failed to resolve message ${id}: ${result.error}`);
+      }
+      return null;
+    }
+    if (result.output.startsWith(LOOKUP_ERROR_MARKER)) {
+      this.lastMessageLookupError = describeUnscopedMiss(
+        id,
+        result.output.slice(LOOKUP_ERROR_MARKER.length)
+      );
+      return null;
+    }
+    return result.output;
+  }
+  /**
+   * The scoped half of `resolveById`: open exactly `loc`'s mailbox and look for
+   * the id there. `hit` carries the action's output; `done` means stop with
+   * `lastMessageLookupError` set; `fallback` means the remembered location was
+   * stale and has been evicted, so the caller should try the bounded scan.
+   */
+  resolveScopedById(id, loc, innerAction) {
+    const result = executeAppleScript(
+      this.scopedByIdScript(loc.account, loc.mailbox, id, innerAction),
+      { timeoutMs: READ_ONLY_BYID_TIMEOUT_MS }
+    );
+    const where = `${loc.account} / ${loc.mailbox}`;
+    if (!result.success) {
+      console.error(`Failed to read message ${id} from ${where}: ${result.error}`);
+      if (result.timedOut) {
+        this.lastMessageLookupError = timedOutResolvingId(id);
+        return { kind: "done" };
+      }
+      if (loc.explicit) {
+        this.lastMessageLookupError = `Could not read message ${Number(id)} from ${where}: ${result.error ?? "AppleScript error"}`;
+        return { kind: "done" };
+      }
+      this.forgetLocation(id);
+      return { kind: "fallback" };
+    }
+    const scopedPrefix = LOOKUP_ERROR_MARKER + SCOPED_MISS_MARKER;
+    if (result.output.trim() && !result.output.startsWith(scopedPrefix)) {
+      return { kind: "hit", output: result.output };
+    }
+    if (!loc.explicit) {
+      this.forgetLocation(id);
+      return { kind: "fallback" };
+    }
+    const reason = result.output.startsWith(scopedPrefix) ? result.output.slice(scopedPrefix.length) : "nomessage";
+    if (reason === "nomailbox") {
+      this.lastMessageLookupError = `Mailbox "${loc.mailbox}" not found in account "${loc.account}" \u2014 message ${Number(id)} was not looked up. Check the names with list-mailboxes, or omit account/mailbox to scan every mailbox.`;
+    } else if (reason.startsWith("error:")) {
+      this.lastMessageLookupError = `Could not read message ${Number(id)} from ${where}: ${reason.slice("error:".length)}`;
+    } else {
+      this.lastMessageLookupError = `Message ${Number(id)} not found in ${where} \u2014 it may have been moved or deleted. Re-list or search to get its current id, or omit account/mailbox to scan every mailbox.`;
+    }
+    return { kind: "done" };
+  }
+  /** Drop a stale id→location entry (#270) so the next read doesn't retry it. */
+  forgetLocation(id) {
+    this.idLocationIndex.delete(String(id));
+  }
   /**
    * The unscoped by-id resolution: walk every mailbox of every account, then the
    * local store (#183), and run `innerAction` with `msg` bound when EXACTLY one
-   * mailbox holds the id — `{LOOKUP_ERROR_MARKER}` prefixes both the not-found
-   * and the ambiguous outcome. Shared by getMessageContent, getRawSource and
-   * getMessageHeaders so the three reads cannot drift apart (the pre-#224 code
-   * carried two byte-identical copies).
+   * mailbox holds the id (or on the first hit, with `firstHit`) —
+   * `{LOOKUP_ERROR_MARKER}` prefixes both the not-found and the ambiguous
+   * outcome. `_hitMb` / `_hitAcct` are bound to the hit's mailbox and account
+   * name alongside `msg`.
+   *
+   * Bounded (#270): a mailbox above `getByIdScanThreshold()` messages is
+   * skipped rather than probed, and the walk stops once it has run for
+   * `BYID_SCAN_BUDGET_SECONDS`. Either way the not-found outcome carries a
+   * `BYID_COVERAGE_MARKER` trailer naming what was not covered, so the caller
+   * can say "not found in the mailboxes scanned; these large ones were not"
+   * instead of a false flat "not found". A copy that sits only in a skipped
+   * mailbox therefore no longer counts toward the ambiguity check — harmless
+   * for these read-only lookups, whose copies are the same message.
    */
-  unscopedByIdScript(id, innerAction) {
+  unscopedByIdScript(id, innerAction, opts = {}) {
+    const threshold = getByIdScanThreshold();
+    const sizeGuard = (mbVar, acctNameExpr) => threshold > 0 ? `set _mbCount to 0
+            try
+              set _mbCount to count of messages of ${mbVar}
+            end try
+            if _mbCount > ${threshold} then
+              set _skipPath to ""
+              try
+                ${mailboxPathFragment(mbVar, "_skipPath")}
+              end try
+              set _skipped to _skipped & ${acctNameExpr} & " / " & _skipPath & " (" & (_mbCount as string) & ")${DIAG_ITEM_SEP}"
+              set _probe to false
+            end if` : "";
+    const budgetCheck = `if ((current date) - _startedAt) > ${BYID_SCAN_BUDGET_SECONDS} then
+              set _budgetHit to true
+              exit repeat
+            end if`;
+    const stopOnHit = opts.firstHit ? `if (count of _hits) > 0 then exit repeat` : "";
     return buildAppLevelScript(`
       try
         set _hits to {}
+        set _hitMbs to {}
+        set _hitAccts to {}
         set _names to ""
+        set _skipped to ""
+        set _budgetHit to false
+        set _startedAt to current date
         repeat with acct in accounts
+          if _budgetHit then exit repeat
+          ${stopOnHit}
           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
+            ${budgetCheck}
+            set _probe to true
+            ${sizeGuard("mb", "(name of acct)")}
+            if _probe then
+              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 end of _hitMbs to (contents of mb)
+                  set end of _hitAccts to (name of acct)
+                  set _names to _names & (name of acct) & "/" & (name of mb) & ", "
+                end if
+              end try
+            end if
+            ${stopOnHit}
           end repeat
         end repeat
         -- #183: local mailboxes belong to no account, so the walk above cannot
         -- reach them. Collect into the SAME _hits/_names, which means an id
         -- present both in an account and locally is now correctly reported as
-        -- ambiguous rather than silently resolving to the account copy.${localMailboxBindingFragment()}
-        repeat with mb in _mbs
-          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 & "${LOCAL_STORE_LABEL}/" & (name of mb) & ", "
+        -- ambiguous rather than silently resolving to the account copy.
+        if (not _budgetHit) and ${opts.firstHit ? "(count of _hits) is 0" : "true"} then${localMailboxBindingFragment()}
+          repeat with mb in _mbs
+            ${budgetCheck}
+            set _probe to true
+            ${sizeGuard("mb", `"${LOCAL_STORE_LABEL}"`)}
+            if _probe then
+              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 end of _hitMbs to (contents of mb)
+                  set end of _hitAccts to "${LOCAL_STORE_LABEL}"
+                  set _names to _names & "${LOCAL_STORE_LABEL}/" & (name of mb) & ", "
+                end if
+              end try
             end if
-          end try
-        end repeat
-        if (count of _hits) is 0 then return "${LOOKUP_ERROR_MARKER}Message not found"
-        if (count of _hits) > 1 then return "${LOOKUP_ERROR_MARKER}${AMBIGUOUS_ID_PREFIX}${Number(id)} is present in more than one mailbox (" & _names & "); list or search that mailbox first so the read targets the right copy"
-        if (count of _hits) is 1 then
+            ${stopOnHit}
+          end repeat
+        end if
+        if (count of _hits) is 0 then return "${LOOKUP_ERROR_MARKER}Message not found${BYID_COVERAGE_MARKER}" & _skipped & "${DIAG_FIELD_SEP}" & (_budgetHit as string)
+        ${opts.firstHit ? "" : `if (count of _hits) > 1 then return "${LOOKUP_ERROR_MARKER}${AMBIGUOUS_ID_PREFIX}${Number(id)} is present in more than one mailbox (" & _names & "); list or search that mailbox first so the read targets the right copy"`}
+        if (count of _hits) ${opts.firstHit ? "> 0" : "is 1"} then
           set msg to item 1 of _hits
+          set _hitMb to item 1 of _hitMbs
+          set _hitAcct to item 1 of _hitAccts
           ${innerAction}
         end if
         return ""
@@ -84324,20 +84503,25 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
   /**
    * Build an app-level AppleScript that opens exactly one account+mailbox, finds
    * the message with numeric `id` in it, and runs `innerAction` (which may assume
-   * `msg` is bound). Used by the by-id fast paths (getMessageContent/getRawSource)
-   * so a message in a late-iterated large folder resolves directly instead of via
-   * the timeout-prone full-mailbox scan.
+   * `msg`, `_hitMb` and `_hitAcct` are bound). Used by the by-id fast path
+   * (`resolveScopedById`) so a message in a late-iterated large folder resolves
+   * directly instead of via the timeout-prone full-mailbox scan.
    *
    * The mailbox name is resolved through `resolveMailbox` (so an alias like
    * "Sent"→"Sent Items" or a casing mismatch like "INBOX"→"Inbox" still opens the
    * right folder), and matched case-insensitively by iterating the account's
    * mailboxes — `mailbox "INBOX" of account …` throws on accounts whose inbox is
    * actually named "Inbox", which would silently drop us back to the slow scan.
-   * Returns "" (found nothing) on any error, so the caller falls back safely.
+   *
+   * A miss is reported, not swallowed (#270): `{LOOKUP_ERROR_MARKER}
+   * {SCOPED_MISS_MARKER}` followed by `nomailbox`, `nomessage` or
+   * `error:<Mail's text>`, so the caller can return a clean "not found in
+   * <mailbox>" for an explicit hint instead of guessing.
    */
   scopedByIdScript(account, mailbox, id, innerAction) {
     const resolved = this.resolveMailbox(mailbox, account);
     const bind = isLocalStoreLabel(account) ? `${localMailboxBindingFragment()}
+        set _hitAcct to "${LOCAL_STORE_LABEL}"
         set targetMb to missing value
         ignoring case
           repeat with mb in _mbs
@@ -84349,6 +84533,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
             end if
           end repeat
         end ignoring` : `set acct to (first account whose name is "${escapeForAppleScript(account)}")
+        set _hitAcct to (name of acct)
         set targetMb to missing value
         ignoring case
           repeat with mb in mailboxes of acct
@@ -84360,19 +84545,19 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
             end if
           end repeat
         end ignoring`;
+    const miss = `${LOOKUP_ERROR_MARKER}${SCOPED_MISS_MARKER}`;
     return buildAppLevelScript(`
       try
         ${bind}
-        if targetMb is not missing value then
-          set matchingMsgs to (messages of targetMb whose id is ${Number(id)})
-          if (count of matchingMsgs) > 0 then
-            set msg to item 1 of matchingMsgs
-            ${innerAction}
-          end if
-        end if
+        if targetMb is missing value then return "${miss}nomailbox"
+        set _hitMb to (contents of targetMb)
+        set matchingMsgs to (messages of targetMb whose id is ${Number(id)})
+        if (count of matchingMsgs) is 0 then return "${miss}nomessage"
+        set msg to item 1 of matchingMsgs
+        ${innerAction}
         return ""
       on error errMsg
-        return ""
+        return "${miss}error:" & errMsg
       end try
     `);
   }
@@ -84385,6 +84570,9 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
    *   source can be MB-sized (it includes base64 attachments) and the plain-text
    *   path doesn't need it; fetching it unconditionally was both slow and, worse,
    *   returned the entire raw MIME blob mislabeled as HTML (#32).
+   * @param hint - Explicit account + mailbox (both required to take effect):
+   *   the read opens that one mailbox and, on a miss, reports "not found in
+   *   <account> / <mailbox>" without scanning anywhere else (#270).
    */
   getMessageContent(id, includeHtml = false, hint) {
     this.lastMessageLookupError = void 0;
@@ -84402,38 +84590,15 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
                 ${sourceFetch}
                 ${AS_MESSAGE_DATES_FRAGMENT}
                 return msgSubject & "${MSGID_MARKER}" & msgRfcId & "${DATES_MARKER}" & msgDates & "${CONTENT_MARKER}" & msgContent & "${HTML_MARKER}" & htmlSource`;
-    const loc = hint?.account && hint?.mailbox ? { account: hint.account, mailbox: hint.mailbox } : this.idLocationIndex.get(id.toString());
-    if (loc) {
-      const scopedScript = this.scopedByIdScript(loc.account, loc.mailbox, id, innerFetch);
-      const scoped = this.parseMessageContent(
-        id,
-        executeAppleScript(scopedScript, { timeoutMs: 6e4 }),
-        includeHtml
-      );
-      if (scoped) return scoped;
-    }
-    const script = this.unscopedByIdScript(id, innerFetch);
-    return this.parseMessageContent(
-      id,
-      executeAppleScript(script, { timeoutMs: 6e4 }),
-      includeHtml
-    );
+    const output = this.resolveById(id, innerFetch, hint);
+    return output === null ? null : this.parseMessageContent(id, output, includeHtml);
   }
   /**
    * Parse the marker-delimited output of a getMessageContent AppleScript into a
-   * MessageContent, or null when nothing was found / the fetch failed. Shared by
-   * the scoped fast path and the full-mailbox-scan fallback.
+   * MessageContent, or null when the payload is malformed.
    */
-  parseMessageContent(id, result, includeHtml) {
-    if (!result.success || !result.output.trim()) {
-      if (!result.success) console.error(`Failed to get message content: ${result.error}`);
-      return null;
-    }
-    if (result.output.startsWith(LOOKUP_ERROR_MARKER)) {
-      this.lastMessageLookupError = result.output.slice(LOOKUP_ERROR_MARKER.length).trim();
-      return null;
-    }
-    const htmlSplit = result.output.split(HTML_MARKER);
+  parseMessageContent(id, output, includeHtml) {
+    const htmlSplit = output.split(HTML_MARKER);
     const contentPart = htmlSplit[0];
     const rawSource = htmlSplit.length > 1 ? htmlSplit[1] : "";
     const parts = contentPart.split(CONTENT_MARKER);
@@ -84458,8 +84623,8 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
   /**
    * Fetch ONLY the raw RFC 5322 header block of a message (#224) — Mail's
    * `all headers` property — plus its `date received`, so the caller can show the
-   * arrival timestamp beside the author's `Date:` header. Same scoped-fast-path /
-   * full-scan resolution as getMessageContent; never reads the body or source.
+   * arrival timestamp beside the author's `Date:` header. Same resolution as
+   * getMessageContent (resolveById); never reads the body or source.
    * Returns null (with `lastMessageLookupError` set when Mail said why) on a miss.
    */
   getMessageHeaders(id, hint) {
@@ -84471,70 +84636,32 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
                 end try
                 ${AS_MESSAGE_DATES_FRAGMENT}
                 return msgDates & "${DATES_MARKER}" & msgHeaders`;
-    const parse4 = (result) => {
-      if (!result.success || !result.output.trim()) {
-        if (!result.success) console.error(`Failed to get message headers: ${result.error}`);
-        return null;
-      }
-      if (result.output.startsWith(LOOKUP_ERROR_MARKER)) {
-        this.lastMessageLookupError = result.output.slice(LOOKUP_ERROR_MARKER.length).trim();
-        return null;
-      }
-      const idx = result.output.indexOf(DATES_MARKER);
-      if (idx === -1) return null;
-      const { dateReceived } = parseMessageDates(result.output.slice(0, idx));
-      const raw = result.output.slice(idx + DATES_MARKER.length);
-      if (!raw.trim()) return null;
-      return { raw, ...dateReceived ? { dateReceived } : {} };
-    };
-    const loc = hint?.account && hint?.mailbox ? { account: hint.account, mailbox: hint.mailbox } : this.idLocationIndex.get(id.toString());
-    if (loc) {
-      const scoped = parse4(
-        executeAppleScript(this.scopedByIdScript(loc.account, loc.mailbox, id, innerFetch), {
-          timeoutMs: 6e4
-        })
-      );
-      if (scoped) return scoped;
-    }
-    return parse4(executeAppleScript(this.unscopedByIdScript(id, innerFetch), { timeoutMs: 6e4 }));
+    const output = this.resolveById(id, innerFetch, hint);
+    if (output === null) return null;
+    const idx = output.indexOf(DATES_MARKER);
+    if (idx === -1) return null;
+    const { dateReceived } = parseMessageDates(output.slice(0, idx));
+    const raw = output.slice(idx + DATES_MARKER.length);
+    if (!raw.trim()) return null;
+    return { raw, ...dateReceived ? { dateReceived } : {} };
   }
   /**
    * Get the raw MIME source of a message.
    * Used as fallback for attachment extraction when AppleScript
    * mail attachments returns empty.
    *
-   * Timeout is 2x the default (120s) because `source of msg` returns
-   * the entire raw message including base64-encoded attachments —
-   * a 20MB attachment can take several seconds over Exchange/IMAP.
+   * Uses the same short `READ_ONLY_BYID_TIMEOUT_MS` as the other by-id reads
+   * (#270) — `source of msg` returning the entire raw message, base64
+   * attachments included, is documented elsewhere as taking "several
+   * seconds" for a 20MB attachment over Exchange/IMAP, comfortably inside
+   * that budget; a call still running past it is a wedged scripting bridge,
+   * not legitimate transfer time, so there is no case where the old 120s
+   * ceiling was buying a real result a shorter one would have missed.
+   * Same resolution as getMessageContent (resolveById).
    */
   getRawSource(id, hint) {
     this.lastMessageLookupError = void 0;
-    const loc = hint?.account && hint?.mailbox ? { account: hint.account, mailbox: hint.mailbox } : this.idLocationIndex.get(id.toString());
-    if (loc) {
-      const scopedScript = this.scopedByIdScript(
-        loc.account,
-        loc.mailbox,
-        id,
-        "return source of msg"
-      );
-      const scoped = executeAppleScript(scopedScript, { timeoutMs: 12e4 });
-      if (scoped.success && scoped.output.trim() && !scoped.output.startsWith(LOOKUP_ERROR_MARKER)) {
-        return scoped.output;
-      }
-      if (scoped.success && scoped.output.startsWith(LOOKUP_ERROR_MARKER)) {
-        this.lastMessageLookupError = scoped.output.slice(LOOKUP_ERROR_MARKER.length).trim();
-      }
-    }
-    const script = this.unscopedByIdScript(id, "return source of msg");
-    const result = executeAppleScript(script, { timeoutMs: 12e4 });
-    if (!result.success || !result.output.trim()) {
-      return null;
-    }
-    if (result.output.startsWith(LOOKUP_ERROR_MARKER)) {
-      this.lastMessageLookupError = result.output.slice(LOOKUP_ERROR_MARKER.length).trim();
-      return null;
-    }
-    return result.output;
+    return this.resolveById(id, "return source of msg", hint);
   }
   /**
    * List messages in a mailbox.
@@ -87506,10 +87633,12 @@ async function readOriginal(deps, id, cfg) {
     return { original, plainText: extractTextBody(source.raw) };
   }
   const raw = deps.mail.getRawSource(id);
-  if (!raw)
+  if (!raw) {
+    const why = deps.mail.consumeLastMessageLookupError?.();
     throw new Error(
-      "Cannot read the original message source. Re-list the intended mailbox and retry with its message id."
+      `Cannot read the original message source${why ? ` (${why})` : ""}. Re-list the intended mailbox and retry with its message id.`
     );
+  }
   const content = deps.mail.getMessageContent(id);
   return { original: parseOriginalHeaders(raw), plainText: content?.plainText ?? null };
 }
@@ -89151,7 +89280,10 @@ registerTool(
       seedSubject = subjectFromGetMessage(r.info);
     } else {
       const msg = mailManager.getMessageById(id);
-      if (!msg) return errorResponse(`Message with ID "${id}" not found`);
+      if (!msg) {
+        const lookupError = mailManager.consumeLastMessageLookupError();
+        return errorResponse(lookupError ?? `Message with ID "${id}" not found`);
+      }
       seedSubject = msg.subject;
     }
     if (!seedSubject) return errorResponse(`Could not determine the subject of message "${id}"`);

package/docs/IMAP-SETUP.md

@@ -371,3 +371,4 @@ GUI is ignoring.
 | `APPLE_MAIL_MCP_TEMPLATES_FILE`                              | Email-templates store path (default `~/Library/Application Support/apple-mail-mcp/templates.json`).                                                                                                                                                                                                                         |
 | `APPLE_MAIL_MCP_MAX_BUFFER`                                  | Max AppleScript (`osascript`) output buffer in bytes (default 64 MiB).                                                                                                                                                                                                                                                      |
 | `APPLE_MAIL_MAX_SEARCH_MAILBOX`                              | Per-mailbox message-count guard for unscoped AppleScript search (default `5000`; `0` disables). Note: no `_MCP` in the name.                                                                                                                                                                                                |
+| `APPLE_MAIL_MAX_BYID_SCAN_MAILBOX`                           | Per-mailbox message-count guard for the cross-mailbox scan a numeric message id falls back to (default `50000`; `0` disables). Skipped mailboxes are named in the not-found error. Note: no `_MCP` in the name.                                                                                                             |

package/package.json

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