apple-mail-mcp 2.19.18 → 2.19.20

package/README.md

@@ -240,6 +240,7 @@ Search for messages matching criteria. Searches all accounts by default.
 | `dateFrom`  | string  | No       | Start date filter (e.g., "January 1, 2026")                                                                                               |
 | `dateTo`    | string  | No       | End date filter (e.g., "March 1, 2026")                                                                                                   |
 | `limit`     | number  | No       | Max results, 1–500 (default: 50)                                                                                                          |
+| `offset`    | number  | No       | Newest matches to skip, ≥ 0 (for pagination). IMAP accounts only; without a `mailbox`, `offset` + `limit` may not exceed 5,000            |
 
 **Returns:** List of matching messages with ID, date, subject, sender, and read state.
 
@@ -1103,14 +1104,23 @@ which made a filter-less `list-messages` fail on such a mailbox before 2.19.16.
 **Very large IMAP mailboxes are read newest-first in bounded windows**
 ([#256](https://github.com/sweetrb/apple-mail-mcp/issues/256)). Above 10,000
 messages, a filter-less `list-messages`/`search-messages` pages by message
-sequence number from the top of the mailbox — it fetches UIDs and flags for
-just enough of the newest messages to fill `limit` + `offset` (skipping
-`\Deleted` ones) and full rows for the page alone, so `limit: 1` on a
-793,614-message mailbox costs one small `FETCH`, not a whole-mailbox `SEARCH`.
+sequence number: page `offset` of `limit` is sequence numbers
+`N-offset-limit+1 .. N-offset`, so it fetches UIDs and flags for that range
+alone (plus a small margin; `\Deleted` ones are skipped and the page topped up
+from below) and full rows for the page. The cost is the page, not the offset:
+`limit: 1` at offset 790,000 of a 793,614-message mailbox is one ~33-message
+`FETCH`, not a whole-mailbox `SEARCH` or a walk over every skipped message.
+Offsets count sequence positions. iCloud keeps messages awaiting expunge out of
+the sequence space, so there they are exact; on a server that keeps them in it,
+a page shifts by the number of such messages above it (they are never
+returned).
 A filtered search there runs the same criteria over newest-first sequence
 windows (5,000 messages, growing to 50,000) and stops once the page is full;
 the reported total then reads `at least N` unless the walk reached the bottom
-of the mailbox. A `SEARCH` or `FETCH` that fails names the mailbox, its size and
+of the mailbox. A filtered search's deep `offset` has no such shortcut — which
+messages match is only known by searching the skipped windows — so its cost
+still grows with the offset (in 50,000-message `SEARCH` windows); narrow it
+with `dateTo` instead. A `SEARCH` or `FETCH` that fails names the mailbox, its size and
 the server's own reason (or a likely timeout) instead of reporting "no
 messages".
 

package/build/cli.js

@@ -58049,6 +58049,7 @@ __export(imapClient_exports, {
   MAX_COMPOSE_SOURCE_BYTES: () => MAX_COMPOSE_SOURCE_BYTES,
   MAX_RFC822_FILE_BYTES: () => MAX_RFC822_FILE_BYTES,
   MAX_RFC822_INLINE_BYTES: () => MAX_RFC822_INLINE_BYTES,
+  MAX_UNSCOPED_SEARCH_DEPTH: () => MAX_UNSCOPED_SEARCH_DEPTH,
   __resetPool: () => __resetPool,
   __setPoolConnect: () => __setPoolConnect,
   bodyStructureHasAttachments: () => bodyStructureHasAttachments,
@@ -58096,7 +58097,8 @@ __export(imapClient_exports, {
   resolveImapConfig: () => resolveImapConfig,
   resolveImapConfigs: () => resolveImapConfigs,
   resolveMailboxPath: () => resolveMailboxPath,
-  shouldUseImap: () => shouldUseImap
+  shouldUseImap: () => shouldUseImap,
+  unscopedSearchOffsetError: () => unscopedSearchOffsetError
 });
 import { createHash } from "node:crypto";
 function encodeImapId(account, path, uid) {
@@ -58442,6 +58444,10 @@ function messageIdentity(entry) {
   const messageId = raw.replace(/^<+|>+$/g, "").trim().toLowerCase();
   return messageId ? `mid:${messageId}` : `${entry.path}\0${entry.message.uid}`;
 }
+function unscopedSearchOffsetError(offset, limit) {
+  if (offset <= 0 || offset + limit <= MAX_UNSCOPED_SEARCH_DEPTH) return void 0;
+  return `search-messages without a mailbox merges every mailbox's newest offset+limit matches, so it pages at most ${MAX_UNSCOPED_SEARCH_DEPTH.toLocaleString("en-US")} deep (offset ${offset} + limit ${limit} asked). Name a mailbox (e.g. the account's All Mail or Archive) to page deeper, or narrow the search with dateTo.`;
+}
 function isUnfiltered(criteria) {
   const keys = Object.keys(criteria);
   return keys.length === 1 && criteria.deleted === false;
@@ -58565,16 +58571,16 @@ function pageRows(fetch) {
 function omissionReason(fetch) {
   return "the server's FETCH response for this message could not be read, even without BODYSTRUCTURE or ENVELOPE" + (fetch.cause ? ` (${fetch.cause})` : "");
 }
-async function walkWindows(exists, page, firstWindow, readWindow) {
+async function walkWindows(top, page, firstWindow, readWindow, openTop = true) {
   const wanted = page.skip + page.take;
   const uids = [];
   let seen = 0;
   let matched = 0;
-  let hi = exists;
+  let hi = top;
   let width = Math.max(1, Math.min(firstWindow, MAX_WINDOW));
   while (hi >= 1 && seen < wanted) {
     const lo = Math.max(1, hi - width + 1);
-    const live = (await readWindow(lo, hi === exists ? "*" : hi, hi - lo + 1)).slice().sort((a, b) => b - a);
+    const live = (await readWindow(lo, hi === top && openTop ? "*" : hi, hi - lo + 1)).slice().sort((a, b) => b - a);
     matched += live.length;
     for (const uid of live) {
       if (seen >= wanted) break;
@@ -58586,13 +58592,21 @@ async function walkWindows(exists, page, firstWindow, readWindow) {
   }
   return { uids, matched, exhausted: hi < 1 };
 }
+function sequenceTop(client, statusCount) {
+  const mb = client.mailbox;
+  const exists = mb && typeof mb.exists === "number" && mb.exists >= 0 ? mb.exists : void 0;
+  return exists ?? statusCount;
+}
 async function listLargeMailbox(client, exists, page) {
+  const top = sequenceTop(client, exists) - page.skip;
+  if (top < 1 || page.take === 0) {
+    return { messages: [], omitted: [], total: exists, totalExact: true };
+  }
   let deletedSeen = 0;
   const walk = await walkWindows(
-    exists,
-    page,
-    // Room for a few ghosts on the first read without a second round trip.
-    page.skip + page.take + 64,
+    top,
+    { skip: 0, take: page.take },
+    page.take + DELETED_MARGIN,
     async (lo, hi) => {
       const live = [];
       for await (const msg of client.fetch(`${lo}:${hi}`, { uid: true, flags: true })) {
@@ -58600,7 +58614,10 @@ async function listLargeMailbox(client, exists, page) {
         else live.push(msg.uid);
       }
       return live;
-    }
+    },
+    // From the very top the first window is `lo:*`, as before; below it the
+    // range is exact.
+    page.skip === 0
   );
   return {
     ...pageRows(await fetchRows(client, walk.uids)),
@@ -58678,6 +58695,10 @@ async function run(args, listMode, deps) {
       }
       const limit = args.limit ?? 50;
       const offset = args.offset ?? 0;
+      if (unscopedSearch) {
+        const tooDeep = unscopedSearchOffsetError(offset, limit);
+        if (tooDeep) throw new Error(tooDeep);
+      }
       const criteria = buildCriteria(args, listMode);
       const page = unscopedSearch ? { skip: 0, take: offset + limit } : { skip: offset, take: limit };
       const fetched = [];
@@ -59755,7 +59776,7 @@ async function imapThread(id, deps = {}, limit = 50) {
     true
   );
 }
-var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
+var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, MAX_UNSCOPED_SEARCH_DEPTH, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, DELETED_MARGIN, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
 var init_imapClient = __esm({
   "src/services/imapClient.ts"() {
     "use strict";
@@ -59829,6 +59850,7 @@ var init_imapClient = __esm({
     LARGE_MAILBOX_MESSAGES = 1e4;
     FIRST_SEARCH_WINDOW = 5e3;
     MAX_WINDOW = 5e4;
+    MAX_UNSCOPED_SEARCH_DEPTH = 5e3;
     ROW_QUERY = {
       envelope: true,
       flags: true,
@@ -59847,6 +59869,7 @@ var init_imapClient = __esm({
       internalDate: true,
       headers: ["date", "from", "subject", "message-id", "in-reply-to", "content-type"]
     };
+    DELETED_MARGIN = 32;
     poolConnect = defaultConnect;
     pools = /* @__PURE__ */ new Map();
     connecting = /* @__PURE__ */ new Map();

package/build/index.js

@@ -3118,12 +3118,13 @@ var require_data = __commonJS({
   }
 });
 
-// node_modules/.pnpm/fast-uri@3.1.6/node_modules/fast-uri/lib/utils.js
+// node_modules/.pnpm/fast-uri@3.1.8/node_modules/fast-uri/lib/utils.js
 var require_utils = __commonJS({
-  "node_modules/.pnpm/fast-uri@3.1.6/node_modules/fast-uri/lib/utils.js"(exports, module) {
+  "node_modules/.pnpm/fast-uri@3.1.8/node_modules/fast-uri/lib/utils.js"(exports, module) {
     "use strict";
     var isUUID = RegExp.prototype.test.bind(/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu);
     var isIPv4 = RegExp.prototype.test.bind(/^(?:(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)$/u);
+    var isPort = RegExp.prototype.test.bind(/^\d*$/u);
     var isHexPair = RegExp.prototype.test.bind(/^[\da-f]{2}$/iu);
     var isUnreserved = RegExp.prototype.test.bind(/^[\da-z\-._~]$/iu);
     var isPathCharacter = RegExp.prototype.test.bind(/^[A-Za-z0-9\-._~!$&'()*+,;=:@/]$/u);
@@ -3589,8 +3590,12 @@ var require_utils = __commonJS({
         uriTokens.push(host);
       }
       if (typeof component.port === "number" || typeof component.port === "string") {
+        const port = String(component.port);
+        if (!isPort(port)) {
+          throw new TypeError("URI port is malformed.");
+        }
         uriTokens.push(":");
-        uriTokens.push(String(component.port));
+        uriTokens.push(port);
       }
       return uriTokens.length ? uriTokens.join("") : void 0;
     }
@@ -3615,9 +3620,9 @@ var require_utils = __commonJS({
   }
 });
 
-// node_modules/.pnpm/fast-uri@3.1.6/node_modules/fast-uri/lib/schemes.js
+// node_modules/.pnpm/fast-uri@3.1.8/node_modules/fast-uri/lib/schemes.js
 var require_schemes = __commonJS({
-  "node_modules/.pnpm/fast-uri@3.1.6/node_modules/fast-uri/lib/schemes.js"(exports, module) {
+  "node_modules/.pnpm/fast-uri@3.1.8/node_modules/fast-uri/lib/schemes.js"(exports, module) {
     "use strict";
     var { isUUID } = require_utils();
     var URN_REG = /^([\da-z][\d\-a-z]{0,31}):((?:[\w!$'()*+,\-./:;=@]|%[\da-f]{2})+)$/iu;
@@ -3826,9 +3831,9 @@ var require_schemes = __commonJS({
   }
 });
 
-// node_modules/.pnpm/fast-uri@3.1.6/node_modules/fast-uri/index.js
+// node_modules/.pnpm/fast-uri@3.1.8/node_modules/fast-uri/index.js
 var require_fast_uri = __commonJS({
-  "node_modules/.pnpm/fast-uri@3.1.6/node_modules/fast-uri/index.js"(exports, module) {
+  "node_modules/.pnpm/fast-uri@3.1.8/node_modules/fast-uri/index.js"(exports, module) {
     "use strict";
     var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, serializePathEncoding, normalizeQueryFragmentEncoding, encodeQuery, encodeFragment, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
     var { SCHEMES, getSchemeHandler } = require_schemes();
@@ -4033,12 +4038,15 @@ var require_fast_uri = __commonJS({
       }
       return false;
     }
+    function isIPLiteral(host) {
+      return host[0] === "[" && host[host.length - 1] === "]";
+    }
     function hasMalformedComponentPercentEncoding(matches) {
       const host = matches[4];
-      return hasMalformedPercentEncoding(matches[3]) || host !== void 0 && !(host[0] === "[" && host[host.length - 1] === "]") && hasMalformedPercentEncoding(host) || hasMalformedPercentEncoding(matches[6]) || hasMalformedPercentEncoding(matches[7]) || hasMalformedPercentEncoding(matches[8]);
+      return hasMalformedPercentEncoding(matches[3]) || host !== void 0 && !isIPLiteral(host) && hasMalformedPercentEncoding(host) || hasMalformedPercentEncoding(matches[6]) || hasMalformedPercentEncoding(matches[7]) || hasMalformedPercentEncoding(matches[8]);
     }
     function canonicalizeHost(parsed, options, schemeHandler, isIP) {
-      if (!options.unicodeSupport && (!schemeHandler || !schemeHandler.unicodeSupport) && parsed.host && parsed.host[0] !== "[" && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP === false && nonSimpleDomain(parsed.host)) {
+      if (!options.unicodeSupport && (!schemeHandler || !schemeHandler.unicodeSupport) && parsed.host && !isIPLiteral(parsed.host) && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP === false && nonSimpleDomain(parsed.host)) {
         try {
           parsed.host = new URL("http://" + parsed.host).hostname;
         } catch (e) {
@@ -4125,10 +4133,11 @@ var require_fast_uri = __commonJS({
         if (parsed.host) {
           const ipv4result = isIPv4(parsed.host);
           if (ipv4result === false) {
-            const bracketedIPLiteral = parsed.host[0] === "[" && parsed.host[parsed.host.length - 1] === "]";
+            const bracketedIPLiteral = isIPLiteral(parsed.host);
+            const hasIPLiteralBracket = parsed.host.indexOf("[") !== -1 || parsed.host.indexOf("]") !== -1;
             const ipv6result = normalizeIPv6(parsed.host);
             isIP = ipv6result.isIPV6 || ipv6result.isIPVFuture === true;
-            malformedIPLiteral = bracketedIPLiteral && ipv6result.error === true;
+            malformedIPLiteral = hasIPLiteralBracket && (!bracketedIPLiteral || ipv6result.error === true);
             parsed.host = isIP ? ipv6result.host : ipv6result.host.toLowerCase();
             if (malformedIPLiteral) {
               parsed.error = parsed.error || "URI host is malformed.";
@@ -4151,14 +4160,17 @@ var require_fast_uri = __commonJS({
           parsed.error = parsed.error || "URI is not a " + options.reference + " reference.";
         }
         const schemeHandler = getSchemeHandler(options.scheme || parsed.scheme);
-        malformedHost = canonicalizeHost(parsed, options, schemeHandler, isIP);
-        if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
-          if (uri.indexOf("%") !== -1) {
-            if (parsed.host !== void 0 && !malformedIPLiteral) {
-              const host = isIP ? parsed.host : normalizePercentEncoding(parsed.host, true);
-              parsed.host = reescapeHostDelimiters(host, isIP);
-            }
+        if (!malformedIPLiteral) {
+          malformedHost = canonicalizeHost(parsed, options, schemeHandler, isIP);
+        }
+        if (uri.indexOf("%") !== -1 && parsed.host !== void 0 && !malformedIPLiteral) {
+          let host = isIP ? parsed.host : normalizePercentEncoding(parsed.host, true);
+          if (!isIP) {
+            host = normalizePercentEncoding(host.toLowerCase());
           }
+          parsed.host = reescapeHostDelimiters(host, isIP);
+        }
+        if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
           if (parsed.path) {
             parsed.path = normalizePathEncoding(parsed.path);
           }
@@ -65378,6 +65390,7 @@ __export(imapClient_exports, {
   MAX_COMPOSE_SOURCE_BYTES: () => MAX_COMPOSE_SOURCE_BYTES,
   MAX_RFC822_FILE_BYTES: () => MAX_RFC822_FILE_BYTES,
   MAX_RFC822_INLINE_BYTES: () => MAX_RFC822_INLINE_BYTES,
+  MAX_UNSCOPED_SEARCH_DEPTH: () => MAX_UNSCOPED_SEARCH_DEPTH,
   __resetPool: () => __resetPool,
   __setPoolConnect: () => __setPoolConnect,
   bodyStructureHasAttachments: () => bodyStructureHasAttachments,
@@ -65425,7 +65438,8 @@ __export(imapClient_exports, {
   resolveImapConfig: () => resolveImapConfig,
   resolveImapConfigs: () => resolveImapConfigs,
   resolveMailboxPath: () => resolveMailboxPath,
-  shouldUseImap: () => shouldUseImap
+  shouldUseImap: () => shouldUseImap,
+  unscopedSearchOffsetError: () => unscopedSearchOffsetError
 });
 import { createHash } from "node:crypto";
 function encodeImapId(account, path, uid) {
@@ -65771,6 +65785,10 @@ function messageIdentity(entry) {
   const messageId = raw.replace(/^<+|>+$/g, "").trim().toLowerCase();
   return messageId ? `mid:${messageId}` : `${entry.path}\0${entry.message.uid}`;
 }
+function unscopedSearchOffsetError(offset, limit) {
+  if (offset <= 0 || offset + limit <= MAX_UNSCOPED_SEARCH_DEPTH) return void 0;
+  return `search-messages without a mailbox merges every mailbox's newest offset+limit matches, so it pages at most ${MAX_UNSCOPED_SEARCH_DEPTH.toLocaleString("en-US")} deep (offset ${offset} + limit ${limit} asked). Name a mailbox (e.g. the account's All Mail or Archive) to page deeper, or narrow the search with dateTo.`;
+}
 function isUnfiltered(criteria) {
   const keys = Object.keys(criteria);
   return keys.length === 1 && criteria.deleted === false;
@@ -65894,16 +65912,16 @@ function pageRows(fetch) {
 function omissionReason(fetch) {
   return "the server's FETCH response for this message could not be read, even without BODYSTRUCTURE or ENVELOPE" + (fetch.cause ? ` (${fetch.cause})` : "");
 }
-async function walkWindows(exists, page, firstWindow, readWindow) {
+async function walkWindows(top, page, firstWindow, readWindow, openTop = true) {
   const wanted = page.skip + page.take;
   const uids = [];
   let seen = 0;
   let matched = 0;
-  let hi = exists;
+  let hi = top;
   let width = Math.max(1, Math.min(firstWindow, MAX_WINDOW));
   while (hi >= 1 && seen < wanted) {
     const lo = Math.max(1, hi - width + 1);
-    const live = (await readWindow(lo, hi === exists ? "*" : hi, hi - lo + 1)).slice().sort((a, b) => b - a);
+    const live = (await readWindow(lo, hi === top && openTop ? "*" : hi, hi - lo + 1)).slice().sort((a, b) => b - a);
     matched += live.length;
     for (const uid of live) {
       if (seen >= wanted) break;
@@ -65915,13 +65933,21 @@ async function walkWindows(exists, page, firstWindow, readWindow) {
   }
   return { uids, matched, exhausted: hi < 1 };
 }
+function sequenceTop(client, statusCount) {
+  const mb = client.mailbox;
+  const exists = mb && typeof mb.exists === "number" && mb.exists >= 0 ? mb.exists : void 0;
+  return exists ?? statusCount;
+}
 async function listLargeMailbox(client, exists, page) {
+  const top = sequenceTop(client, exists) - page.skip;
+  if (top < 1 || page.take === 0) {
+    return { messages: [], omitted: [], total: exists, totalExact: true };
+  }
   let deletedSeen = 0;
   const walk = await walkWindows(
-    exists,
-    page,
-    // Room for a few ghosts on the first read without a second round trip.
-    page.skip + page.take + 64,
+    top,
+    { skip: 0, take: page.take },
+    page.take + DELETED_MARGIN,
     async (lo, hi) => {
       const live = [];
       for await (const msg of client.fetch(`${lo}:${hi}`, { uid: true, flags: true })) {
@@ -65929,7 +65955,10 @@ async function listLargeMailbox(client, exists, page) {
         else live.push(msg.uid);
       }
       return live;
-    }
+    },
+    // From the very top the first window is `lo:*`, as before; below it the
+    // range is exact.
+    page.skip === 0
   );
   return {
     ...pageRows(await fetchRows(client, walk.uids)),
@@ -66007,6 +66036,10 @@ async function run(args, listMode, deps) {
       }
       const limit = args.limit ?? 50;
       const offset = args.offset ?? 0;
+      if (unscopedSearch) {
+        const tooDeep = unscopedSearchOffsetError(offset, limit);
+        if (tooDeep) throw new Error(tooDeep);
+      }
       const criteria = buildCriteria(args, listMode);
       const page = unscopedSearch ? { skip: 0, take: offset + limit } : { skip: offset, take: limit };
       const fetched = [];
@@ -67084,7 +67117,7 @@ async function imapThread(id, deps = {}, limit = 50) {
     true
   );
 }
-var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
+var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, MAX_UNSCOPED_SEARCH_DEPTH, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, DELETED_MARGIN, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
 var init_imapClient = __esm({
   "src/services/imapClient.ts"() {
     "use strict";
@@ -67158,6 +67191,7 @@ var init_imapClient = __esm({
     LARGE_MAILBOX_MESSAGES = 1e4;
     FIRST_SEARCH_WINDOW = 5e3;
     MAX_WINDOW = 5e4;
+    MAX_UNSCOPED_SEARCH_DEPTH = 5e3;
     ROW_QUERY = {
       envelope: true,
       flags: true,
@@ -67176,6 +67210,7 @@ var init_imapClient = __esm({
       internalDate: true,
       headers: ["date", "from", "subject", "message-id", "in-reply-to", "content-type"]
     };
+    DELETED_MARGIN = 32;
     poolConnect = defaultConnect;
     pools = /* @__PURE__ */ new Map();
     connecting = /* @__PURE__ */ new Map();
@@ -88471,7 +88506,10 @@ registerTool(
       isFlagged: external_exports.boolean().optional().describe("Filter by flagged status"),
       dateFrom: DATE_FILTER_SCHEMA.describe("Start date filter (e.g., 'January 1, 2026')"),
       dateTo: DATE_FILTER_SCHEMA.describe("End date filter (e.g., 'March 1, 2026')"),
-      limit: external_exports.number().int().min(1).max(500).optional().describe("Maximum number of results (default: 50, max: 500)")
+      limit: external_exports.number().int().min(1).max(500).optional().describe("Maximum number of results (default: 50, max: 500)"),
+      offset: external_exports.number().int().min(0).optional().describe(
+        "Number of newest matches to skip (for pagination; IMAP accounts only). Without a mailbox, offset + limit may not exceed 5,000 \u2014 name a mailbox to page deeper."
+      )
     },
     outputSchema: LIST_OUTPUT_SCHEMA
   },
@@ -88482,6 +88520,7 @@ registerTool(
       mailbox,
       account,
       limit = 50,
+      offset = 0,
       dateFrom,
       dateTo,
       from,
@@ -88489,12 +88528,17 @@ registerTool(
       isRead,
       isFlagged
     }) => {
+      if (offset > 0 && !mailbox) {
+        const tooDeep = unscopedSearchOffsetError(offset, limit);
+        if (tooDeep) return errorResponse(tooDeep);
+      }
       if (shouldUseImap(account)) {
         const imapArgs = {
           query,
           body,
           mailbox,
           limit,
+          offset,
           dateFrom,
           dateTo,
           from,
@@ -88513,11 +88557,16 @@ registerTool(
             omittedMessages: r.omittedMessages
           });
         }
-        const fan = await fanOutImapMessages(imapArgs, "search");
         const { appleScriptOnly } = partitionAccountsForCounts(
           mailManager.listAccounts(),
           resolveImapConfigs()
         );
+        if (offset > 0 && appleScriptOnly.length > 0 && !body) {
+          return errorResponse(
+            `offset is supported only on IMAP accounts, and ${appleScriptOnly.map((a) => `"${a.name}"`).join(", ")} ${appleScriptOnly.length === 1 ? "is" : "are"} AppleScript-only. Pass an IMAP account to page, or omit offset.`
+          );
+        }
+        const fan = await fanOutImapMessages(imapArgs, "search");
         if (body) {
           const apple2 = {
             rows: [],
@@ -88548,6 +88597,11 @@ registerTool(
         );
         return mergedMessageResponse(fan, apple, limit, "matched");
       }
+      if (offset > 0) {
+        return errorResponse(
+          `offset is supported only on IMAP accounts; IMAP is not configured for ${account ? `account "${account}"` : "any account"}. Omit offset, or narrow the search with dateFrom/dateTo instead.`
+        );
+      }
       if (body) {
         return errorResponse(
           `Body search requires the IMAP backend, which is not configured for ${account ? `account "${account}"` : "any account"}. Configure IMAP (see the IMAP backend section of the README) or search by query/subject/from instead.`

package/package.json

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