@littlebearapps/outlook-assistant 3.11.2 → 3.12.1

package/email/headers.js

@@ -6,6 +6,7 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 
 /**
  * Important headers to highlight (in order of relevance)
@@ -158,6 +159,9 @@ async function handleGetEmailHeaders(args) {
   const groupByType = args.groupByType || false;
   const importantOnly = args.importantOnly || false;
   const raw = args.raw || false;
+  // Shared-mailbox message IDs aren't resolvable under /me — route to the
+  // owning mailbox when a sharedMailbox/email is supplied.
+  const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!emailId) {
     return {
@@ -187,7 +191,7 @@ async function handleGetEmailHeaders(args) {
       'sentDateTime',
     ].join(',');
 
-    const endpoint = `me/messages/${emailId}`;
+    const endpoint = `${prefix}/messages/${emailId}`;
     const queryParams = {
       $select: selectFields,
     };

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; an initial sync larger than `maxResults` arrives over several pages, each returning a continuation token to pass back until a delta token is returned. 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 the messages in a conversation thread by conversationId, oldest first (up to 100; a longer thread is marked truncated — use `export target=conversation` for up to 1000). 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: {
@@ -74,7 +74,7 @@ const emailTools = [
         searchExpression: {
           type: 'string',
           description:
-            'Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:"invoice"`, `from:github.com`, or `foo OR bar`. Quote your own phrases; a single bare token is auto-quoted. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: personal Outlook.com accounts reject field-scoped `$search` outright; since v3.10.0 recognised `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried automatically (a `subject:` term becomes a substring match, so it is close but not identical) (reported as strategy `raw-kql-translated`). Expressions that cannot be translated exactly — free text, `AND`/`OR`, unknown prefixes — are not retried, so use `query` for those there. RELEVANCE, NOT RECENCY: an untranslated expression is answered by Graph `$search` over the whole message including the body, ranked by relevance and not sorted by date, so top hits can look unrelated to a caller expecting a subject match. `query` is the more predictable choice for a term you expect in a subject line; `searchExpression` is the one that reaches body text.',
+            'Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:"invoice"`, `from:github.com`, or `foo OR bar`. Quote your own phrases, escaping any `"` or `\\` inside them with a backslash; a single bare token is auto-quoted and escaped for you. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: personal Outlook.com accounts reject field-scoped `$search` outright; since v3.10.0 recognised `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried automatically (a `subject:` term becomes a substring match, so it is close but not identical) (reported as strategy `raw-kql-translated`). Expressions that cannot be translated exactly — free text, `AND`/`OR`, unknown prefixes — are not retried, so use `query` for those there. RELEVANCE, NOT RECENCY: an untranslated expression is answered by Graph `$search` over the whole message including the body, ranked by relevance and not sorted by date, so top hits can look unrelated to a caller expecting a subject match. `query` is the more predictable choice for a term you expect in a subject line; `searchExpression` is the one that reaches body text.',
         },
         kqlQuery: {
           type: 'string',
@@ -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,12 +142,12 @@ 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',
           description:
-            'Max results per page for delta sync (default: 100, max: 200)',
+            'Delta sync page size (deltaMode only): 1-200, default 100, sent to Graph as the `Prefer: odata.maxpagesize` header. It sizes each page, not the whole sync: while a page returns a continuation token, keep calling with that token until a delta token is returned, and pass the same `maxResults` on every page (an omitted value means 100).',
         },
         // Conversation params
         includeHeaders: {
@@ -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:
@@ -307,7 +327,7 @@ const emailTools = [
   {
     name: 'draft',
     description:
-      'Full draft lifecycle for review-before-send workflows (destructive: covers `send` and `delete`). action=`create` saves a new draft in the Drafts folder and returns its id (use `dryRun: true` to preview without saving; `checkRecipients: true` runs mail-tips first). action=`update` patches an existing draft by `id` (only fields passed are changed). action=`send` dispatches an existing draft — shares the rate limit with `send-email`. action=`delete` removes a draft permanently. action=`reply`/`reply-all` creates a reply draft from a message `id` (use `comment` to prepend text — mutually exclusive with `body`). action=`forward` creates a forward draft (requires `id` and `to`). Recipient allowlist applies to create/update/forward. Returns the draft object on create/update/reply/forward; status confirmation on send/delete.',
+      'Full draft lifecycle for review-before-send workflows (destructive: covers `send` and `delete`). action=`create` saves a new draft in the Drafts folder and returns its id (use `dryRun: true` to preview without saving; `checkRecipients: true` runs mail-tips first). action=`update` patches an existing draft by `id` (only fields passed are changed). action=`send` dispatches an existing draft — shares the rate limit with `send-email`. action=`delete` deletes a draft: it skips Deleted Items and goes to Recoverable Items (restorable for a limited time, depending on your account, via "Recover deleted items" in Outlook). update/send/delete refuse any `id` that is not an unsent draft (received or sent messages are never changed). action=`reply`/`reply-all` creates a reply draft from a message `id` (use `comment` to prepend text — mutually exclusive with `body`). action=`forward` creates a forward draft (requires `id` and `to`). Recipient allowlist applies to create/update/forward. Returns the draft object on create/update/reply/forward; status confirmation on send/delete.',
     annotations: {
       title: 'Draft Operations',
       readOnlyHint: false,
@@ -334,7 +354,7 @@ const emailTools = [
         id: {
           type: 'string',
           description:
-            'Draft or message ID. Required for update/send/delete/reply/reply-all/forward.',
+            'Draft or message ID. Required for update/send/delete/reply/reply-all/forward. update/send/delete need a draft ID; reply/reply-all/forward take any message ID.',
         },
         to: {
           type: 'string',
@@ -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 with a time: a value with `Z` or a ±hh:mm offset is kept as that exact instant; a value without one is read in the configured default timezone (OUTLOOK_DEFAULT_TIMEZONE); date-only or unparseable values are refused before any change). With only `dueDateTime`, the start defaults to 09:00 on the due date in the default timezone, or to the due time if that is earlier. action=`unflag` clears the flag. action=`complete` marks the flag as done. Flag/unflag/complete accept either `id` (single) or `ids` (batch array) — messages in a batch are updated one at a time (one PATCH each, not Graph `$batch`). 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,
@@ -416,40 +436,59 @@ const emailTools = [
         // Flag params
         dueDateTime: {
           type: 'string',
-          description: 'Due date/time for follow-up, ISO 8601 (action=flag)',
+          description:
+            'Due date/time for follow-up (action=flag). ISO 8601 with a time: "2026-03-01T09:00:00Z" or "2026-03-01T09:00:00+10:00" is that exact instant; "2026-03-01T09:00:00" (no zone) is read in the default timezone (OUTLOOK_DEFAULT_TIMEZONE).',
         },
         startDateTime: {
           type: 'string',
-          description: 'Start date/time for follow-up, ISO 8601 (action=flag)',
+          description:
+            'Start date/time for follow-up (action=flag), same format as dueDateTime. Defaults to 09:00 on the due date in the default timezone (capped at the due time) when only dueDateTime is given.',
+        },
+        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 +505,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 +530,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 +577,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 (up to 1000 messages) 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 +654,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,13 +7,18 @@ 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,
   DEFAULT_LIMITS,
 } = require('../utils/response-formatter');
 const { getEmailFields } = require('../utils/field-presets');
-const { escapeODataString } = require('../utils/odata-helpers');
+const {
+  escapeODataString,
+  escapeSearchPhrase,
+  quoteSearchPhrase,
+} = require('../utils/odata-helpers');
 
 // Upper bound on how many recent messages the client-side fallback scans
 // before giving up. Deliberately DECOUPLED from the requested result count so
@@ -71,6 +76,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 +106,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}`);
     }
 
@@ -321,12 +332,13 @@ async function progressiveSearch(
       trimmedKql.includes(':') || /\s/.test(trimmedKql);
     // Already-quoted phrases and KQL-looking expressions (field syntax
     // or multi-word) are passed through as-is; only bare single tokens
-    // are wrapped so Graph treats them as phrase searches.
+    // are wrapped so Graph treats them as phrase searches. The wrapped
+    // token's own `"` and `\` are escaped so they cannot end the phrase. (#251)
     let kqlForSearch;
     if (alreadyQuoted || looksLikeExpression) {
       kqlForSearch = trimmedKql;
     } else {
-      kqlForSearch = `"${trimmedKql}"`;
+      kqlForSearch = `"${escapeSearchPhrase(trimmedKql)}"`;
     }
 
     // Graph rejects field-scoped expressions outright on personal accounts
@@ -1205,7 +1217,7 @@ function buildSearchParams(searchTerms, filterTerms, count, selectFields) {
 
   // Handle search terms - use $search only for free-text query
   if (searchTerms.query) {
-    params.$search = `"${searchTerms.query}"`;
+    params.$search = quoteSearchPhrase(searchTerms.query);
   }
 
   // Build filter conditions array - use $filter for structured fields (more reliable)
@@ -1569,6 +1581,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 +1618,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` removes a folder and its contents; `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 — it does not go to Deleted Items, and Graph doesn't document whether it can be restored (some accounts may offer Outlook's \"Recover deleted items\" for a limited time, but don't rely on it), so move out anything you might need first. 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',