@littlebearapps/outlook-assistant 3.11.1 → 3.12.0

package/email/index.js

@@ -33,7 +33,7 @@ const emailTools = [
   {
     name: 'search-emails',
     description:
-      'Search, list, delta-sync, or thread-group emails — six modes selected by parameters (read-only). With no params: lists recent emails in `folder` (default `inbox`). With `query`/`from`/`to`/`subject`/date filters: full search (combines via OData filter). With `searchExpression` (deprecated alias `kqlQuery`): a raw Microsoft Graph `$search` expression for advanced server-side search. With `deltaMode: true`: returns current state plus a `deltaToken`; pass the token back on the next call for incremental changes only — ideal for inbox monitoring. With `groupByConversation: true`: returns conversation threads. With `conversationId`: returns all messages in a single thread. With `internetMessageId`: looks up a message by its RFC Message-ID header. Personal Outlook.com accounts have limited `$search` support — this tool falls back through OData filters / boolean filters / recent listing automatically, but structured filters (`from`/`subject`/`receivedAfter`/`hasAttachments`/`unreadOnly`) return cleaner results. Returns paged messages with id/subject/from/receivedDateTime/preview by default; use `outputVerbosity` to expand.',
+      'Search, list, delta-sync, or thread-group emails — six modes selected by parameters (read-only). With no params: lists recent emails in `folder` (default `inbox`). With `query`/`from`/`to`/`subject`/date filters: full search (combines via OData filter). With `searchExpression` (deprecated alias `kqlQuery`): a raw Microsoft Graph `$search` expression for advanced server-side search. With `deltaMode: true`: returns current state plus a `deltaToken`; pass the token back on the next call for incremental changes only — ideal for inbox monitoring. With `groupByConversation: true`: returns conversation threads. With `conversationId`: returns all messages in a single thread. With `internetMessageId`: looks up a message by its RFC Message-ID header. Set `sharedMailbox` (or alias `email`) to search a shared/delegated mailbox instead of the signed-in account — works with custom folders and nested folder paths. Personal Outlook.com accounts have limited `$search` support — this tool falls back through OData filters / boolean filters / recent listing automatically, but structured filters (`from`/`subject`/`receivedAfter`/`hasAttachments`/`unreadOnly`) return cleaner results. Returns paged messages with id/subject/from/receivedDateTime/preview by default; use `outputVerbosity` to expand.',
     annotations: {
       title: 'Search Emails',
       readOnlyHint: true,
@@ -48,22 +48,22 @@ const emailTools = [
         deltaMode: {
           type: 'boolean',
           description:
-            'Enable delta sync mode. Returns only changes since last sync. Use deltaToken for subsequent calls.',
+            'Enable delta sync mode. Returns only changes since last sync. Use deltaToken for subsequent calls. Honors `sharedMailbox`/`email` (and custom `folder` paths) to sync within a shared/delegated mailbox.',
         },
         internetMessageId: {
           type: 'string',
           description:
-            'Look up email by Message-ID header (e.g. <abc123@example.com>). For threading/deduplication.',
+            'Look up email by Message-ID header (e.g. <abc123@example.com>). For threading/deduplication. Honors `sharedMailbox`/`email` to look up within a shared/delegated mailbox.',
         },
         conversationId: {
           type: 'string',
           description:
-            'Get all messages in a conversation thread by conversationId.',
+            'Get all messages in a conversation thread by conversationId. Honors `sharedMailbox`/`email` to thread within a shared/delegated mailbox.',
         },
         groupByConversation: {
           type: 'boolean',
           description:
-            'List conversations (threads) grouped by conversationId instead of individual emails.',
+            'List conversations (threads) grouped by conversationId instead of individual emails. Honors `sharedMailbox`/`email` (and custom `folder` paths) to group within a shared/delegated mailbox.',
         },
         // Search/list params
         query: {
@@ -83,7 +83,17 @@ const emailTools = [
         },
         folder: {
           type: 'string',
-          description: "Email folder (default: 'inbox')",
+          description:
+            "Email folder (default: 'inbox'). Accepts a well-known name, a custom/localized display name, or a nested path like `Inbox/Subfolder`.",
+        },
+        sharedMailbox: {
+          type: 'string',
+          description:
+            'Email address of a shared/delegated mailbox to search instead of the signed-in account. Combine with `folder` (incl. custom subfolders/paths) or `searchAllFolders`. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
+        },
+        email: {
+          type: 'string',
+          description: 'Alias for `sharedMailbox`.',
         },
         from: {
           type: 'string',
@@ -132,7 +142,7 @@ const emailTools = [
         deltaToken: {
           type: 'string',
           description:
-            'Token from previous delta call for incremental sync (deltaMode only)',
+            'Token from previous delta call for incremental sync (deltaMode only). The token is authoritative — it encodes its own mailbox and folder, so `folder`/`sharedMailbox` are ignored and a token from a different mailbox is rejected.',
         },
         maxResults: {
           type: 'number',
@@ -158,6 +168,7 @@ const emailTools = [
         return handleSearchByMessageId({
           messageId: args.internetMessageId,
           outputVerbosity: args.outputVerbosity,
+          sharedMailbox: args.sharedMailbox || args.email || null,
         });
       }
       if (args.conversationId) {
@@ -189,7 +200,7 @@ const emailTools = [
   {
     name: 'read-email',
     description:
-      'Read a single email by id (read-only). Default: returns the full message body (HTML stripped to text by default), subject, from/to/cc, receivedDateTime, conversationId, attachments metadata, and webLink as Markdown. With `headersMode: true`: returns RFC-822 forensic headers instead (DKIM, SPF, DMARC, Received chain, Message-ID, Authentication-Results) — pair with `importantOnly: true` for the security-relevant subset, `groupByType: true` for category-bucketed view, or `raw: true` for JSON instead of Markdown. With `includeHeaders: true` (non-headers-mode): adds basic headers alongside body. Use `outputVerbosity` (minimal/standard/full) to control field count.',
+      'Read a single email by id (read-only). Default: returns the full message body (HTML stripped to text by default), subject, from/to/cc, receivedDateTime, conversationId, attachments metadata, and webLink as Markdown. With `headersMode: true`: returns RFC-822 forensic headers instead (DKIM, SPF, DMARC, Received chain, Message-ID, Authentication-Results) — pair with `importantOnly: true` for the security-relevant subset, `groupByType: true` for category-bucketed view, or `raw: true` for JSON instead of Markdown. With `includeHeaders: true` (non-headers-mode): adds basic headers alongside body. Use `outputVerbosity` (minimal/standard/full) to control field count. **If the id came from a shared/delegated mailbox (e.g. via `search-emails` or `access-shared-mailbox` with `sharedMailbox` set), you MUST pass the same `sharedMailbox` (or alias `email`) here** — message IDs are mailbox-scoped, and reading a shared-mailbox id without it fails with 404 ErrorInvalidMailboxItemId.',
     annotations: {
       title: 'Read Email',
       readOnlyHint: true,
@@ -203,6 +214,15 @@ const emailTools = [
           type: 'string',
           description: 'ID of the email to read',
         },
+        sharedMailbox: {
+          type: 'string',
+          description:
+            'Email address of the shared/delegated mailbox the id belongs to. Required when the id was obtained from a shared mailbox — message IDs are mailbox-scoped and reading without it returns 404 ErrorInvalidMailboxItemId. Requires delegate access + Mail.Read.Shared. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
+        },
+        email: {
+          type: 'string',
+          description: 'Alias for `sharedMailbox`.',
+        },
         headersMode: {
           type: 'boolean',
           description:
@@ -386,7 +406,7 @@ const emailTools = [
   {
     name: 'update-email',
     description:
-      'Update message state without modifying content (idempotent — safe to retry). action=`mark-read`/`mark-unread` toggles the `isRead` flag on a single message by `id`. action=`flag` sets a follow-up flag with optional `dueDateTime`/`startDateTime` (ISO 8601). action=`unflag` clears the flag. action=`complete` marks the flag as done. Flag/unflag/complete accept either `id` (single) or `ids` (batch array) — batch operations use Graph `$batch` for efficiency. Returns status confirmation per message.',
+      'Update message state without modifying content (idempotent — safe to retry). action=`mark-read`/`mark-unread` toggles the `isRead` flag on a single message by `id`. action=`flag` sets a follow-up flag with optional `dueDateTime`/`startDateTime` (ISO 8601). action=`unflag` clears the flag. action=`complete` marks the flag as done. Flag/unflag/complete accept either `id` (single) or `ids` (batch array) — batch operations use Graph `$batch` for efficiency. Pass `sharedMailbox` (or alias `email`) to update messages in a shared/delegated mailbox instead of the signed-in account (requires Mail.ReadWrite.Shared + delegate access). Returns status confirmation per message.',
     annotations: {
       title: 'Update Email',
       readOnlyHint: false,
@@ -422,34 +442,51 @@ const emailTools = [
           type: 'string',
           description: 'Start date/time for follow-up, ISO 8601 (action=flag)',
         },
+        sharedMailbox: {
+          type: 'string',
+          description:
+            'Email address of a shared/delegated mailbox whose message(s) to update instead of the signed-in account. Requires delegate access + Mail.ReadWrite.Shared. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
+        },
+        email: {
+          type: 'string',
+          description: 'Alias for `sharedMailbox`.',
+        },
       },
       additionalProperties: false,
       required: ['action'],
     },
     handler: async (args) => {
+      const sharedMailbox = args.sharedMailbox || args.email || null;
       switch (args.action) {
         case 'mark-read':
-          return handleMarkAsRead({ id: args.id, isRead: true });
+          return handleMarkAsRead({ id: args.id, isRead: true, sharedMailbox });
         case 'mark-unread':
-          return handleMarkAsRead({ id: args.id, isRead: false });
+          return handleMarkAsRead({
+            id: args.id,
+            isRead: false,
+            sharedMailbox,
+          });
         case 'flag':
           return handleSetMessageFlag({
             messageId: args.id,
             messageIds: args.ids,
             dueDateTime: args.dueDateTime,
             startDateTime: args.startDateTime,
+            sharedMailbox,
           });
         case 'unflag':
           return handleClearMessageFlag({
             messageId: args.id,
             messageIds: args.ids,
             markComplete: false,
+            sharedMailbox,
           });
         case 'complete':
           return handleClearMessageFlag({
             messageId: args.id,
             messageIds: args.ids,
             markComplete: true,
+            sharedMailbox,
           });
         default:
           return {
@@ -466,7 +503,7 @@ const emailTools = [
   {
     name: 'attachments',
     description:
-      'Inspect or retrieve email attachments. action=`list` (default) returns metadata for all attachments on `messageId` (id, name, contentType, size, isInline) — read-only. action=`view` returns inline content for text/JSON/XML attachments via `attachmentId`; binary types require download. action=`download` saves the attachment to disk at `outputDir` (default system tmpdir, auto-created) and returns the saved file path. `messageId` is required for all actions; `attachmentId` is required for view/download. Use `outputVerbosity` to control list field count.',
+      'Inspect or retrieve email attachments. action=`list` (default) returns metadata for all attachments on `messageId` (id, name, contentType, size, isInline) — read-only. action=`view` returns inline content for text/JSON/XML attachments via `attachmentId`; binary types require download. action=`download` saves the attachment to disk at `outputDir` (default system tmpdir, auto-created) and returns the saved file path. `messageId` is required for all actions; `attachmentId` is required for view/download. If `messageId` came from a shared/delegated mailbox, pass the same `sharedMailbox` (or alias `email`) — attachment IDs are scoped to the message and fail under /me otherwise. Use `outputVerbosity` to control list field count.',
     annotations: {
       title: 'Attachments',
       readOnlyHint: false,
@@ -491,6 +528,15 @@ const emailTools = [
           type: 'string',
           description: 'Attachment ID (action=view/download, required)',
         },
+        sharedMailbox: {
+          type: 'string',
+          description:
+            'Email address of the shared/delegated mailbox the messageId belongs to. Required when the message came from a shared mailbox. Requires delegate access + Mail.Read.Shared. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
+        },
+        email: {
+          type: 'string',
+          description: 'Alias for `sharedMailbox`.',
+        },
         outputDir: {
           type: 'string',
           description:
@@ -529,7 +575,7 @@ const emailTools = [
   {
     name: 'export',
     description:
-      'Export emails to file formats for archival, forensics, or programmatic processing. target=`message` (default) exports a single email by `id` to `savePath` — accepts `mime`/`eml`/`markdown`/`json`/`csv`. target=`messages` batch-exports either an explicit `emailIds` array or messages matching `searchQuery` (or `query` shortcut) into `outputDir` — accepts `markdown`/`json`/`csv`. target=`conversation` exports a full thread by `conversationId` into `outputDir` (chronological by default; pass `order: "reverse"` for newest-first) — accepts `eml`/`mbox`/`markdown`/`json`/`html`/`csv`. target=`mime` returns raw RFC-822 MIME bytes for `id` (use `headersOnly` for just headers, `base64` for encoded transport, `maxSize` to cap at default 1MB). `includeAttachments` defaults to true for single-message exports and false for batch. Format support varies by target — see the format param enum.',
+      'Export emails to file formats for archival, forensics, or programmatic processing. target=`message` (default) exports a single email by `id` to `savePath` — accepts `mime`/`eml`/`markdown`/`json`/`csv`. target=`messages` batch-exports either an explicit `emailIds` array or messages matching `searchQuery` (or `query` shortcut) into `outputDir` — accepts `markdown`/`json`/`csv`. target=`conversation` exports a full thread by `conversationId` into `outputDir` (chronological by default; pass `order: "reverse"` for newest-first) — accepts `eml`/`mbox`/`markdown`/`json`/`html`/`csv`. target=`mime` returns raw RFC-822 MIME bytes for `id` (use `headersOnly` for just headers, `base64` for encoded transport, `maxSize` to cap at default 1MB). All targets accept `sharedMailbox` (alias `email`) to export from a shared/delegated mailbox instead of the signed-in account — pass it whenever the id(s)/conversationId/searchQuery come from a shared mailbox, or exports fail with 404 ErrorInvalidMailboxItemId. `includeAttachments` defaults to true for single-message exports and false for batch. Format support varies by target — see the format param enum.',
     annotations: {
       title: 'Export Emails',
       readOnlyHint: false,
@@ -606,6 +652,15 @@ const emailTools = [
           description:
             'Message order (target=conversation, default: chronological)',
         },
+        sharedMailbox: {
+          type: 'string',
+          description:
+            'Email address of a shared/delegated mailbox to export from instead of the signed-in account. Applies to all targets (message/messages/conversation/mime) — pass it whenever the id(s)/conversationId/searchQuery belong to a shared mailbox. Requires delegate access + Mail.Read.Shared. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
+        },
+        email: {
+          type: 'string',
+          description: 'Alias for `sharedMailbox`.',
+        },
         // MIME params
         headersOnly: {
           type: 'boolean',

package/email/list.js

@@ -51,13 +51,20 @@ async function handleListEmails(args) {
   const requestedCount =
     args.count ?? args.maxResults ?? DEFAULT_LIMITS.listEmails;
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
+  // `search-emails` falls through to list mode when no filters are supplied,
+  // so the shared-mailbox scope has to be honoured here too.
+  const sharedMailbox = args.sharedMailbox || args.email || null;
 
   try {
     // Get access token
     const accessToken = await ensureAuthenticated();
 
     // Resolve the folder path
-    const endpoint = await resolveFolderPath(accessToken, folder);
+    const endpoint = await resolveFolderPath(
+      accessToken,
+      folder,
+      sharedMailbox
+    );
 
     // Select fields based on verbosity level
     const fieldPreset = getFieldPresetForVerbosity(verbosity);

package/email/mark-as-read.js

@@ -4,6 +4,7 @@
 const _config = require('../config'); // Reserved for future use
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 
 /**
  * Mark email as read handler
@@ -13,6 +14,7 @@ const { ensureAuthenticated } = require('../auth');
 async function handleMarkAsRead(args) {
   const emailId = args.id;
   const isRead = args.isRead !== undefined ? args.isRead : true; // Default to true
+  const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!emailId) {
     return {
@@ -30,7 +32,7 @@ async function handleMarkAsRead(args) {
     const accessToken = await ensureAuthenticated();
 
     // Make API call to update email read status
-    const endpoint = `me/messages/${emailId}`;
+    const endpoint = `${prefix}/messages/${emailId}`;
     const updateData = {
       isRead: isRead,
     };

package/email/mime.js

@@ -6,6 +6,7 @@
  */
 const { callGraphAPIRaw } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 
 /**
  * Parse MIME headers from raw content
@@ -93,6 +94,8 @@ async function handleGetMimeContent(args) {
   const headersOnly = args.headersOnly || false;
   const returnBase64 = args.base64 || false;
   const maxSize = args.maxSize !== undefined ? args.maxSize : 1024 * 1024; // 1MB default
+  // Mailbox-scoped IDs: route to /users/{mailbox} for a shared/delegated mailbox.
+  const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!emailId) {
     return {
@@ -111,7 +114,7 @@ async function handleGetMimeContent(args) {
 
     try {
       // Fetch raw MIME content
-      const mimeContent = await callGraphAPIRaw(accessToken, emailId);
+      const mimeContent = await callGraphAPIRaw(accessToken, emailId, prefix);
 
       if (!mimeContent) {
         return {

package/email/read.js

@@ -11,6 +11,7 @@ const {
   VERBOSITY,
 } = require('../utils/response-formatter');
 const { getEmailFields } = require('../utils/field-presets');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 
 /**
  * Get field preset based on verbosity and options
@@ -45,6 +46,9 @@ async function handleReadEmail(args) {
   const emailId = args.id;
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
   const includeHeaders = args.includeHeaders || false;
+  // Message IDs are mailbox-scoped: an ID issued by a shared/delegated mailbox
+  // is not resolvable under /me. Route to /users/{mailbox} when supplied.
+  const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!emailId) {
     return {
@@ -66,7 +70,7 @@ async function handleReadEmail(args) {
     const selectFields = getEmailFields(fieldPreset);
 
     // Make API call to get email details
-    const endpoint = `me/messages/${emailId}`;
+    const endpoint = `${prefix}/messages/${emailId}`;
     const queryParams = {
       $select: selectFields,
     };

package/email/search.js

@@ -7,6 +7,7 @@ const _config = require('../config'); // Reserved for future use
 const { callGraphAPI, callGraphAPIPaginated } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { resolveFolderPath } = require('./folder-utils');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 const {
   formatEmailList,
   VERBOSITY,
@@ -71,6 +72,9 @@ async function handleSearchEmails(args) {
   // Trim so a whitespace-only value doesn't send `$search: '""'`. (#169)
   const kqlQuery =
     (args.searchExpression || '').trim() || (args.kqlQuery || '').trim();
+  // Optional: scope the search to a shared/delegated mailbox rather than the
+  // signed-in account. Accepts a custom/localized folder name or nested path.
+  const sharedMailbox = args.sharedMailbox || args.email || null;
 
   // Select fields based on verbosity — but never at the cost of correctness.
   // When more than one search term is supplied, the ladder may satisfy one
@@ -98,13 +102,16 @@ async function handleSearchEmails(args) {
     // Get access token
     const accessToken = await ensureAuthenticated();
 
-    // Determine endpoint - search all folders or specific folder
+    // Determine endpoint - search all folders or specific folder, scoped to
+    // the signed-in account or a shared mailbox.
     let endpoint;
     if (searchAllFolders) {
-      endpoint = 'me/messages';
-      console.error('Searching across all mail folders');
+      endpoint = `${buildMailboxPrefix(sharedMailbox)}/messages`;
+      console.error(
+        `Searching across all mail folders${sharedMailbox ? ` in ${sharedMailbox}` : ''}`
+      );
     } else {
-      endpoint = await resolveFolderPath(accessToken, folder);
+      endpoint = await resolveFolderPath(accessToken, folder, sharedMailbox);
       console.error(`Using endpoint: ${endpoint} for folder: ${folder}`);
     }
 
@@ -1569,6 +1576,8 @@ function formatSearchResults(response, folder, verbosity, searchAllFolders) {
 async function handleSearchByMessageId(args) {
   const messageId = args.messageId;
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
+  // Optional: scope the lookup to a shared/delegated mailbox.
+  const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!messageId) {
     return {
@@ -1604,7 +1613,7 @@ async function handleSearchByMessageId(args) {
     const response = await callGraphAPI(
       accessToken,
       'GET',
-      'me/messages',
+      `${prefix}/messages`,
       null,
       params
     );

package/folder/create.js

@@ -4,6 +4,7 @@
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { resolveFolder, listChildFolders } = require('./resolve');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 
 /**
  * Create folder handler
@@ -14,6 +15,7 @@ async function handleCreateFolder(args) {
   const folderName = (args.name || '').trim();
   const parentFolder = args.parentFolder || '';
   const parentFolderId = args.parentFolderId || '';
+  const sharedMailbox = args.sharedMailbox || args.email || null;
 
   if (!folderName) {
     return {
@@ -34,6 +36,7 @@ async function handleCreateFolder(args) {
     const result = await createMailFolder(accessToken, folderName, {
       name: parentFolder,
       id: parentFolderId,
+      mailbox: sharedMailbox,
     });
 
     return {
@@ -74,10 +77,12 @@ async function handleCreateFolder(args) {
  * Create a new mail folder
  * @param {string} accessToken - Access token
  * @param {string} folderName - Name of the folder to create
- * @param {{name?: string, id?: string}} parentSpec - Parent folder name/path or ID
+ * @param {{name?: string, id?: string, mailbox?: string|null}} parentSpec - Parent folder name/path or ID, plus optional shared mailbox
  * @returns {Promise<object>} - Result object with status and message
  */
 async function createMailFolder(accessToken, folderName, parentSpec) {
+  const mailbox = parentSpec.mailbox || null;
+  const prefix = buildMailboxPrefix(mailbox);
   try {
     // Resolve the parent folder if one was specified (supports "Parent/Child"
     // paths and explicit IDs). Leaf name (folderName) is created, not
@@ -98,7 +103,9 @@ async function createMailFolder(accessToken, folderName, parentSpec) {
     // mailbox — a name may legitimately exist under a different parent. (#216)
     const siblings = await listChildFolders(
       accessToken,
-      parent ? parent.id : null
+      parent ? parent.id : null,
+      undefined,
+      mailbox
     );
     const lower = folderName.toLowerCase();
     if (siblings.some((f) => f.displayName.toLowerCase() === lower)) {
@@ -111,8 +118,8 @@ async function createMailFolder(accessToken, folderName, parentSpec) {
     }
 
     const endpoint = parent
-      ? `me/mailFolders/${parent.id}/childFolders`
-      : 'me/mailFolders';
+      ? `${prefix}/mailFolders/${parent.id}/childFolders`
+      : `${prefix}/mailFolders`;
 
     // Create the folder
     const folderData = {

package/folder/delete.js

@@ -4,6 +4,7 @@
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { resolveFolder, WELL_KNOWN } = require('./resolve');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 
 /**
  * Delete folder handler
@@ -22,6 +23,8 @@ const { resolveFolder, WELL_KNOWN } = require('./resolve');
  */
 async function handleDeleteFolder(args) {
   const { folderId, folderName } = args;
+  const sharedMailbox = args.sharedMailbox || args.email || null;
+  const prefix = buildMailboxPrefix(sharedMailbox);
 
   if (!folderId && !folderName) {
     return {
@@ -56,6 +59,7 @@ async function handleDeleteFolder(args) {
       resolved = await resolveFolder(accessToken, {
         id: folderId,
         name: folderName,
+        mailbox: sharedMailbox,
       });
     } catch (resolveError) {
       return {
@@ -64,7 +68,11 @@ async function handleDeleteFolder(args) {
     }
 
     // Delete the folder
-    await callGraphAPI(accessToken, 'DELETE', `me/mailFolders/${resolved.id}`);
+    await callGraphAPI(
+      accessToken,
+      'DELETE',
+      `${prefix}/mailFolders/${resolved.id}`
+    );
     return {
       content: [
         {

package/folder/index.js

@@ -12,7 +12,7 @@ const folderTools = [
   {
     name: 'folders',
     description:
-      "Manage mail folders (tool-level destructiveHint=true because `delete` permanently removes a folder; `list` and `stats` are read-only sub-actions despite the annotation). Folders can be addressed by name, by a slash-separated PATH for nested folders (e.g. `Triage/Delete`, `Inbox/Clients/Acme`, case-insensitive), or by explicit ID; `list` output includes each folder's full path and `[id: …]`. A bare name resolves a unique top-level folder first, then searches nested folders (ambiguous names return the candidates — disambiguate with a path or ID). action=`list` (default) returns the folder tree (toggle `includeItemCounts` for unread/total, `includeChildren` for hierarchy). action=`create` makes a new folder under the root, or under `parentFolder` (name/path) / `parentFolderId`, and returns its id. action=`move` relocates emails (`emailIds`) into `targetFolder` (name/path) or `targetFolderId`. action=`stats` returns counts (totalItemCount/unreadItemCount) for `folder` (name/path) or `folderId`, suitable for pagination planning. action=`delete` removes a folder (by `folderName`/path or `folderId`) and its contents — on Outlook.com the folder is moved to Deleted Items (recoverable until you empty it); M365/Exchange accounts may hard-delete per retention policy.",
+      "Manage mail folders (tool-level destructiveHint=true because `delete` permanently removes a folder; `list` and `stats` are read-only sub-actions despite the annotation). Folders can be addressed by name, by a slash-separated PATH for nested folders (e.g. `Triage/Delete`, `Inbox/Clients/Acme`, case-insensitive), or by explicit ID; `list` output includes each folder's full path and `[id: …]`. A bare name resolves a unique top-level folder first, then searches nested folders (ambiguous names return the candidates — disambiguate with a path or ID). action=`list` (default) returns the folder tree (toggle `includeItemCounts` for unread/total, `includeChildren` for hierarchy). action=`create` makes a new folder under the root, or under `parentFolder` (name/path) / `parentFolderId`, and returns its id. action=`move` relocates emails (`emailIds`) into `targetFolder` (name/path) or `targetFolderId`. action=`stats` returns counts (totalItemCount/unreadItemCount) for `folder` (name/path) or `folderId`, suitable for pagination planning. action=`delete` removes a folder (by `folderName`/path or `folderId`) and its contents — on Outlook.com the folder is moved to Deleted Items (recoverable until you empty it); M365/Exchange accounts may hard-delete per retention policy. Every action accepts `sharedMailbox` (alias `email`) to target a shared/delegated mailbox instead of the signed-in account — folder names, paths, and IDs are then resolved inside that mailbox. Protected folders cannot be deleted in any mailbox.",
     annotations: {
       title: 'Mail Folders',
       readOnlyHint: false,
@@ -36,6 +36,16 @@ const folderTools = [
           type: 'boolean',
           description: 'Include child folders in hierarchy (action=list)',
         },
+        // shared-mailbox scoping (all actions)
+        sharedMailbox: {
+          type: 'string',
+          description:
+            'Email address of a shared/delegated mailbox to target instead of the signed-in account (all actions). Requires delegate access + Mail.Read.Shared (list/stats) or Mail.ReadWrite.Shared (create/move/delete). Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
+        },
+        email: {
+          type: 'string',
+          description: 'Alias for `sharedMailbox`.',
+        },
         // create params
         name: {
           type: 'string',

package/folder/list.js

@@ -12,38 +12,44 @@ const { listChildFolders } = require('./resolve');
 async function handleListFolders(args) {
   const includeItemCounts = args.includeItemCounts === true;
   const includeChildren = args.includeChildren === true;
+  // Target a shared/delegated mailbox instead of the signed-in account.
+  const sharedMailbox = args.sharedMailbox || args.email || null;
 
   try {
     // Get access token
     const accessToken = await ensureAuthenticated();
 
     // Get all mail folders
-    const folders = await getAllFoldersHierarchy(
+    const { folders, warnings } = await getAllFoldersHierarchy(
       accessToken,
-      includeItemCounts
+      includeItemCounts,
+      sharedMailbox
     );
 
-    // If including children, format as hierarchy
-    if (includeChildren) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: formatFolderHierarchy(folders, includeItemCounts),
-          },
-        ],
-      };
-    } else {
-      // Otherwise, format as flat list
-      return {
-        content: [
-          {
-            type: 'text',
-            text: formatFolderList(folders, includeItemCounts),
-          },
-        ],
-      };
+    let heading = sharedMailbox ? `\n\nMailbox: ${sharedMailbox}` : '';
+    // The walk can skip branches (permission errors, depth cap) — say so
+    // instead of presenting a partial tree as complete.
+    if (warnings.length > 0) {
+      heading += `\n\n**Partial listing — ${warnings.length} branch(es) incomplete:**\n${warnings.map((w) => `- ${w}`).join('\n')}`;
     }
+
+    const body = includeChildren
+      ? formatFolderHierarchy(folders, includeItemCounts)
+      : formatFolderList(folders, includeItemCounts);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: body + heading,
+        },
+      ],
+      _meta: {
+        folderCount: folders.length,
+        partial: warnings.length > 0,
+        warnings,
+      },
+    };
   } catch (error) {
     if (error.message === 'Authentication required') {
       return {
@@ -71,9 +77,14 @@ async function handleListFolders(args) {
  * Get all mail folders with hierarchy information
  * @param {string} accessToken - Access token
  * @param {boolean} includeItemCounts - Include item counts in response
- * @returns {Promise<Array>} - Array of folder objects with hierarchy
+ * @param {string|null} [sharedMailbox] - Shared mailbox email, or null for the signed-in account
+ * @returns {Promise<{folders: Array, warnings: Array<string>}>} - Folders plus any reasons the tree is incomplete
  */
-async function getAllFoldersHierarchy(accessToken, includeItemCounts) {
+async function getAllFoldersHierarchy(
+  accessToken,
+  includeItemCounts,
+  sharedMailbox = null
+) {
   // Determine select fields based on whether to include counts
   const selectFields = includeItemCounts
     ? 'id,displayName,parentFolderId,childFolderCount,totalItemCount,unreadItemCount'
@@ -81,8 +92,14 @@ async function getAllFoldersHierarchy(accessToken, includeItemCounts) {
 
   // Full recursive, paginated walk so nested folders at ANY depth appear with
   // their complete path (not just one level). (#216 review)
-  const top = await listChildFolders(accessToken, null, selectFields);
+  const top = await listChildFolders(
+    accessToken,
+    null,
+    selectFields,
+    sharedMailbox
+  );
   const all = [];
+  const warnings = [];
   const visited = new Set();
   const queue = top.map((folder) => ({
     folder,
@@ -100,14 +117,28 @@ async function getAllFoldersHierarchy(accessToken, includeItemCounts) {
     visited.add(folder.id);
     all.push({ ...folder, path, parentFolder: parentPath, isTopLevel });
 
+    if (folder.childFolderCount > 0 && depth >= 20) {
+      warnings.push(
+        `Depth limit (20) reached at "${path}" [id: ${folder.id}] — its subfolders were not listed.`
+      );
+    }
+
     if (folder.childFolderCount > 0 && depth < 20) {
       let children;
       try {
-        children = await listChildFolders(accessToken, folder.id, selectFields);
+        children = await listChildFolders(
+          accessToken,
+          folder.id,
+          selectFields,
+          sharedMailbox
+        );
       } catch (error) {
         console.error(
           `Error getting child folders for "${folder.displayName}": ${error.message}`
         );
+        warnings.push(
+          `Could not list subfolders of "${path}" [id: ${folder.id}]: ${error.message}`
+        );
         continue;
       }
       for (const child of children) {
@@ -121,7 +152,7 @@ async function getAllFoldersHierarchy(accessToken, includeItemCounts) {
       }
     }
   }
-  return all;
+  return { folders: all, warnings };
 }
 
 /**
@@ -272,3 +303,6 @@ function formatFolderHierarchy(folders, includeItemCounts) {
 }
 
 module.exports = handleListFolders;
+// Named export so the shared-mailbox folder listing in `access-shared-mailbox`
+// reuses this walk instead of carrying its own copy.
+module.exports.getAllFoldersHierarchy = getAllFoldersHierarchy;