@littlebearapps/outlook-assistant 3.11.2 → 3.12.1

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;

package/folder/move.js

@@ -4,6 +4,7 @@
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { resolveFolder } = require('./resolve');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 
 /**
  * Move emails handler
@@ -15,6 +16,7 @@ async function handleMoveEmails(args) {
   const targetFolder = args.targetFolder || '';
   const targetFolderId = args.targetFolderId || '';
   const sourceFolder = args.sourceFolder || '';
+  const sharedMailbox = args.sharedMailbox || args.email || null;
 
   if (!emailIds) {
     return {
@@ -63,7 +65,7 @@ async function handleMoveEmails(args) {
     const result = await moveEmailsToFolder(
       accessToken,
       ids,
-      { name: targetFolder, id: targetFolderId },
+      { name: targetFolder, id: targetFolderId, mailbox: sharedMailbox },
       sourceFolder
     );
 
@@ -74,6 +76,12 @@ async function handleMoveEmails(args) {
           text: result.message,
         },
       ],
+      _meta: {
+        // Graph assigns a NEW message ID on move (unless immutable IDs are
+        // enabled) — surface the mapping so callers can keep addressing them.
+        moved: result.results?.successful || [],
+        failed: result.results?.failed || [],
+      },
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
@@ -102,7 +110,7 @@ async function handleMoveEmails(args) {
  * Move emails to a folder
  * @param {string} accessToken - Access token
  * @param {Array<string>} emailIds - Array of email IDs to move
- * @param {{name?: string, id?: string}} targetSpec - Target folder name/path or ID
+ * @param {{name?: string, id?: string, mailbox?: string|null}} targetSpec - Target folder name/path or ID, plus optional shared mailbox
  * @param {string} sourceFolderName - Name of the source folder (optional)
  * @returns {Promise<object>} - Result object with status and message
  */
@@ -112,6 +120,7 @@ async function moveEmailsToFolder(
   targetSpec,
   _sourceFolderName
 ) {
+  const prefix = buildMailboxPrefix(targetSpec.mailbox);
   try {
     // Resolve the target folder (supports "Parent/Child" paths, aliases, and
     // explicit IDs — nested folders are now addressable). (#216)
@@ -133,12 +142,20 @@ async function moveEmailsToFolder(
     // Process each email one by one to handle errors independently
     for (const emailId of emailIds) {
       try {
-        // Move the email
-        await callGraphAPI(accessToken, 'POST', `me/messages/${emailId}/move`, {
-          destinationId: targetFolderId,
+        // Move the email. The response carries the moved message, whose id
+        // changes unless immutable IDs are enabled — keep it, the old id is
+        // dead afterwards.
+        const moved = await callGraphAPI(
+          accessToken,
+          'POST',
+          `${prefix}/messages/${emailId}/move`,
+          { destinationId: targetFolderId }
+        );
+
+        results.successful.push({
+          oldId: emailId,
+          newId: moved?.id || emailId,
         });
-
-        results.successful.push(emailId);
       } catch (error) {
         console.error(`Error moving email ${emailId}: ${error.message}`);
         results.failed.push({
@@ -153,6 +170,14 @@ async function moveEmailsToFolder(
 
     if (results.successful.length > 0) {
       message += `Successfully moved ${results.successful.length} email(s) to "${targetLabel}".`;
+      // Small batches: show the id mapping inline so the caller can address
+      // the moved messages without a re-search.
+      if (results.successful.length <= 5) {
+        message += '\n\nNew message IDs (old -> new):';
+        for (const { oldId, newId } of results.successful) {
+          message += `\n- ${oldId} -> ${newId}`;
+        }
+      }
     }
 
     if (results.failed.length > 0) {

package/folder/resolve.js

@@ -1,9 +1,10 @@
 /**
  * Shared, path-aware, ambiguity-aware mail-folder resolver. (#216)
  *
- * Replaces the two top-level-only resolvers (`getFolderIdByName` in
+ * Replaced the top-level-only resolvers (`getFolderIdByName` in
  * email/folder-utils.js and `resolveFolderName` in folder/stats.js) that could
- * not address nested folders. Accepts, in priority order:
+ * not address nested folders (manage-rules folder actions use it since #248).
+ * Accepts, in priority order:
  *   1. an explicit folder ID (never guessed from a name),
  *   2. a well-known alias (inbox, archive, sent, ...),
  *   3. a folder PATH like "Triage/Delete" or "Inbox/Clients/Acme"
@@ -16,8 +17,14 @@
  *
  * `/` is the path separator, so a folder whose display name literally contains
  * `/` cannot be addressed by path — use its folderId (documented on the tool).
+ *
+ * Every function takes an optional `mailbox` (a shared/delegated mailbox email
+ * address). It only changes the Graph path prefix — `me` vs `users/{mailbox}` —
+ * so the same resolution logic reaches custom subfolders and localized folder
+ * names in a shared mailbox exactly as it does in the signed-in account.
  */
 const { callGraphAPI } = require('../utils/graph-api');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 
 // Alias → Graph well-known folder name (usable directly as a path segment).
 const WELL_KNOWN = {
@@ -73,11 +80,17 @@ function ambiguousError(spec, candidates) {
  * @odata.nextLink so folders with many children resolve completely.
  * @returns {Promise<Array<{id, displayName, parentFolderId, childFolderCount}>>}
  */
-async function listChildFolders(accessToken, parentId, select = FOLDER_SELECT) {
+async function listChildFolders(
+  accessToken,
+  parentId,
+  select = FOLDER_SELECT,
+  mailbox = null
+) {
+  const prefix = buildMailboxPrefix(mailbox);
   const all = [];
   let path = parentId
-    ? `me/mailFolders/${parentId}/childFolders`
-    : 'me/mailFolders';
+    ? `${prefix}/mailFolders/${parentId}/childFolders`
+    : `${prefix}/mailFolders`;
   let params = { $top: 100, $select: select };
   // Follow pagination; nextLink already encodes params. Guard against a
   // repeated/malformed nextLink so a bad server response can't loop forever.
@@ -108,22 +121,22 @@ function toRecord(folder, path) {
   };
 }
 
-async function resolveWellKnown(accessToken, alias) {
+async function resolveWellKnown(accessToken, alias, mailbox) {
   const resp = await callGraphAPI(
     accessToken,
     'GET',
-    `me/mailFolders/${WELL_KNOWN[alias]}`,
+    `${buildMailboxPrefix(mailbox)}/mailFolders/${WELL_KNOWN[alias]}`,
     null,
     { $select: FOLDER_SELECT }
   );
   return toRecord(resp, resp.displayName);
 }
 
-async function resolveById(accessToken, id) {
+async function resolveById(accessToken, id, mailbox) {
   const resp = await callGraphAPI(
     accessToken,
     'GET',
-    `me/mailFolders/${id}`,
+    `${buildMailboxPrefix(mailbox)}/mailFolders/${id}`,
     null,
     { $select: FOLDER_SELECT }
   );
@@ -134,8 +147,9 @@ async function resolveById(accessToken, id) {
  * Build a flat list of every folder with its full path, breadth-first.
  * Accepts an already-fetched top-level list to avoid re-fetching.
  */
-async function buildTree(accessToken, topLevel) {
-  const top = topLevel || (await listChildFolders(accessToken, null));
+async function buildTree(accessToken, topLevel, mailbox = null) {
+  const top =
+    topLevel || (await listChildFolders(accessToken, null, undefined, mailbox));
   const out = [];
   const visited = new Set();
   const queue = top.map((f) => ({ folder: f, path: f.displayName, depth: 1 }));
@@ -164,7 +178,12 @@ async function buildTree(accessToken, topLevel) {
             'use an explicit folder path or folderId.'
         );
       }
-      const children = await listChildFolders(accessToken, folder.id);
+      const children = await listChildFolders(
+        accessToken,
+        folder.id,
+        undefined,
+        mailbox
+      );
       for (const child of children) {
         queue.push({
           folder: child,
@@ -186,8 +205,8 @@ function matchName(folders, name) {
  * Resolve a bare display name: a unique top-level match wins (fast path,
  * back-compat); otherwise search the whole tree, reporting ambiguity.
  */
-async function resolveByName(accessToken, name) {
-  const top = await listChildFolders(accessToken, null);
+async function resolveByName(accessToken, name, mailbox) {
+  const top = await listChildFolders(accessToken, null, undefined, mailbox);
   const topMatches = matchName(top, name);
   if (topMatches.length === 1) {
     return toRecord(topMatches[0], topMatches[0].displayName);
@@ -199,7 +218,7 @@ async function resolveByName(accessToken, name) {
     );
   }
   // Not top-level — search nested folders.
-  const tree = await buildTree(accessToken, top);
+  const tree = await buildTree(accessToken, top, mailbox);
   const matches = matchName(tree, name);
   if (matches.length === 0) {
     throw notFoundError(name);
@@ -213,13 +232,13 @@ async function resolveByName(accessToken, name) {
 /**
  * Resolve a path (segments already split/trimmed) by traversing childFolders.
  */
-async function resolvePath(accessToken, segments) {
+async function resolvePath(accessToken, segments, mailbox) {
   let current;
   const first = segments[0];
   if (WELL_KNOWN[first.toLowerCase()]) {
-    current = await resolveWellKnown(accessToken, first.toLowerCase());
+    current = await resolveWellKnown(accessToken, first.toLowerCase(), mailbox);
   } else {
-    const top = await listChildFolders(accessToken, null);
+    const top = await listChildFolders(accessToken, null, undefined, mailbox);
     const matches = matchName(top, first);
     if (matches.length === 0) {
       throw notFoundError(first);
@@ -235,7 +254,12 @@ async function resolvePath(accessToken, segments) {
 
   for (let i = 1; i < segments.length; i++) {
     const seg = segments[i];
-    const children = await listChildFolders(accessToken, current.id);
+    const children = await listChildFolders(
+      accessToken,
+      current.id,
+      undefined,
+      mailbox
+    );
     const matches = matchName(children, seg);
     if (matches.length === 0) {
       throw notFoundError(`${current.path}/${seg}`);
@@ -259,19 +283,34 @@ async function resolvePath(accessToken, segments) {
   return current;
 }
 
+/**
+ * Does a `folder` value look like a raw Graph folder ID rather than a display
+ * name or path? Graph IDs are long base64url-style tokens (`AAMkAG…`,
+ * `AQMkAD…`) with no spaces or `/`; display names that long without a space
+ * are vanishingly rare. Used where `folder` historically accepted raw IDs.
+ * @param {string} value
+ * @returns {boolean}
+ */
+function looksLikeFolderId(value) {
+  return (
+    typeof value === 'string' && /^[A-Za-z0-9_+=-]{60,}$/.test(value.trim())
+  );
+}
+
 /**
  * Resolve a folder from a name/path and/or explicit ID.
  * @param {string} accessToken
- * @param {{name?: string, id?: string}} spec
+ * @param {{name?: string, id?: string, mailbox?: string|null}} spec
  * @returns {Promise<{id: string, displayName: string, parentId: string|null, path: string}>}
  *   `path` is the full slash-separated path when resolved by name/path/alias;
  *   when resolved by ID it is the folder's display name only (ancestors are not
  *   fetched).
  */
 async function resolveFolder(accessToken, spec = {}) {
+  const mailbox = spec.mailbox || null;
   const id = (spec.id || '').trim();
   if (id) {
-    return resolveById(accessToken, id);
+    return resolveById(accessToken, id, mailbox);
   }
   const name = (spec.name || '').trim();
   if (!name) {
@@ -297,18 +336,19 @@ async function resolveFolder(accessToken, spec = {}) {
       );
     }
     if (segments.length === 1) {
-      return resolveFolder(accessToken, { name: segments[0] });
+      return resolveFolder(accessToken, { name: segments[0], mailbox });
     }
-    return resolvePath(accessToken, segments);
+    return resolvePath(accessToken, segments, mailbox);
   }
   if (WELL_KNOWN[name.toLowerCase()]) {
-    return resolveWellKnown(accessToken, name.toLowerCase());
+    return resolveWellKnown(accessToken, name.toLowerCase(), mailbox);
   }
-  return resolveByName(accessToken, name);
+  return resolveByName(accessToken, name, mailbox);
 }
 
 module.exports = {
   WELL_KNOWN,
+  looksLikeFolderId,
   resolveFolder,
   listChildFolders,
   buildTree,

package/folder/stats.js

@@ -7,6 +7,7 @@
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { resolveFolder } = require('./resolve');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 const config = require('../config');
 
 const { VERBOSITY, DEFAULT_LIMITS } = config;
@@ -20,6 +21,8 @@ async function handleGetFolderStats(args) {
   const folderName = args.folder || 'inbox';
   const folderIdArg = args.folderId || '';
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
+  const sharedMailbox = args.sharedMailbox || args.email || null;
+  const prefix = buildMailboxPrefix(sharedMailbox);
 
   try {
     const accessToken = await ensureAuthenticated();
@@ -30,6 +33,7 @@ async function handleGetFolderStats(args) {
       resolved = await resolveFolder(accessToken, {
         name: folderName,
         id: folderIdArg,
+        mailbox: sharedMailbox,
       });
     } catch (resolveError) {
       return {
@@ -42,7 +46,7 @@ async function handleGetFolderStats(args) {
     const folder = await callGraphAPI(
       accessToken,
       'GET',
-      `me/mailFolders/${folderId}`,
+      `${prefix}/mailFolders/${folderId}`,
       null,
       {
         // Note: sizeInBytes is NOT available on mailFolder resource type
@@ -54,7 +58,7 @@ async function handleGetFolderStats(args) {
     // Get recent email dates for context
     let dateRange = null;
     if (verbosity !== VERBOSITY.MINIMAL && folder.totalItemCount > 0) {
-      dateRange = await getEmailDateRange(accessToken, folderId);
+      dateRange = await getEmailDateRange(accessToken, folderId, sharedMailbox);
     }
 
     // Format response based on verbosity
@@ -96,15 +100,17 @@ async function handleGetFolderStats(args) {
  * Get date range of emails in folder
  * @param {string} accessToken - Access token
  * @param {string} folderId - Folder ID
+ * @param {string|null} [mailbox] - Shared mailbox email, or null for the signed-in user
  * @returns {Promise<object|null>} - { oldest, newest } dates or null
  */
-async function getEmailDateRange(accessToken, folderId) {
+async function getEmailDateRange(accessToken, folderId, mailbox = null) {
+  const prefix = buildMailboxPrefix(mailbox);
   try {
     // Get newest email
     const newestResponse = await callGraphAPI(
       accessToken,
       'GET',
-      `me/mailFolders/${folderId}/messages`,
+      `${prefix}/mailFolders/${folderId}/messages`,
       null,
       {
         $select: 'receivedDateTime',
@@ -117,7 +123,7 @@ async function getEmailDateRange(accessToken, folderId) {
     const oldestResponse = await callGraphAPI(
       accessToken,
       'GET',
-      `me/mailFolders/${folderId}/messages`,
+      `${prefix}/mailFolders/${folderId}/messages`,
       null,
       {
         $select: 'receivedDateTime',

package/index.js

@@ -35,8 +35,16 @@ Key environment variables:
   OUTLOOK_CLIENT_SECRET             Client secret VALUE (not the Secret ID)
   OUTLOOK_AUTH_METHOD               device-code (default) | browser
   OUTLOOK_AUTH_AUDIENCE             common | consumers | organizations | <tenant-guid>
-  OUTLOOK_MAX_EMAILS_PER_SESSION    Cap on sends per session
+  OUTLOOK_SHARED_MAILBOX            Opt in to shared mailboxes: read | true (work/school only)
   OUTLOOK_ALLOWED_RECIPIENTS        Comma-separated recipient allowlist
+  OUTLOOK_MAX_EMAILS_PER_SESSION    Default cap per session for every rate-limited tool
+                                    (send-email, draft, manage-rules); 0 or unset = no cap
+  OUTLOOK_MAX_<TOOL>_PER_SESSION    Per-tool cap overriding the default, tool name in upper
+                                    case with _ for -, e.g. OUTLOOK_MAX_SEND_EMAIL_PER_SESSION
+  OUTLOOK_DEFAULT_TIMEZONE          IANA timezone for event times (default Australia/Melbourne)
+  OUTLOOK_IMMUTABLE_IDS             Set to "true" for message IDs that survive folder moves
+  OUTLOOK_SEARCH_SCAN_LIMIT         Local search fallback window (default 500, max 5000)
+  OUTLOOK_REQUEST_TIMEOUT_MS        Graph request inactivity timeout (default 60000)
   USE_TEST_MODE                     Set to "true" to run against mock data
 
 Documentation: https://github.com/littlebearapps/outlook-assistant`;

package/llms-install.md

@@ -21,7 +21,7 @@ Add to your MCP client configuration:
 
 ## Prerequisites
 
-1. **Node.js 18+** must be installed
+1. **Node.js 18.18 or newer** must be installed
 2. **Azure app registration** is required for authentication (free tier works)
 
 ## Getting the Client ID and Secret
@@ -46,16 +46,32 @@ Users must create an Azure app registration to get credentials:
 2. Add: `offline_access`, `User.Read`, `Mail.Read`, `Mail.ReadWrite`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`, `People.Read`, `MailboxSettings.ReadWrite`
 3. Click "Add permissions"
 
+### Enable device code sign-in (the default auth method):
+1. Go to "Authentication" → "Add a platform" → "Mobile and desktop applications"
+2. Check `https://login.microsoftonline.com/common/oauth2/nativeclient` and click "Configure"
+3. Under "Advanced settings", set "Allow public client flows" to **Yes** and save
+
 ## First-Time Authentication
 
-After configuring the MCP server:
+After configuring the MCP server (device code flow, no auth server needed):
+
+1. Use the `auth` tool with `action=authenticate` — it returns a short code and the URL `https://microsoft.com/devicelogin`
+2. Open the URL on any device (a private/incognito window avoids cached sessions), enter the code, sign in and grant permissions
+3. Use the `auth` tool with `action=device-code-complete` — tokens are saved to `~/.outlook-assistant-tokens.json` and refresh automatically
+
+**Browser redirect flow (alternative)**: start the auth server with `npm run auth-server` from a source checkout, or `node "$(npm root -g)/@littlebearapps/outlook-assistant/outlook-auth-server.js"` from a global install, then call `auth` with `action=authenticate` and `method=browser`. The auth server reads `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` from the environment or a `.env` file in the directory you start it from.
+
+## Optional Settings
 
-1. Start the auth server: `npx @littlebearapps/outlook-assistant-auth` (or run `npm run auth-server` from source)
-2. Use the `auth` tool with `action=authenticate` to get an OAuth URL
-3. Open the URL in a browser, sign in with your Microsoft account
-4. Grant permissions — tokens are saved to `~/.outlook-assistant-tokens.json` and refresh automatically
+Add these to the same `env` block if needed:
 
-**Note**: The auth server needs `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` as environment variables. If running it separately from the MCP server, export them in your shell or create a `.env` file.
+| Variable | Purpose |
+|----------|---------|
+| `OUTLOOK_AUTH_AUDIENCE` | `consumers` for Azure apps registered as personal-accounts-only (fixes `AADSTS9002331`); `organizations` or a tenant GUID for work-only apps. Default `common` |
+| `OUTLOOK_DEFAULT_TIMEZONE` | IANA timezone for calendar times (default `Australia/Melbourne`) |
+| `OUTLOOK_MAX_EMAILS_PER_SESSION` | Cap on sends per server session |
+| `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of recipient domains/addresses |
+| `OUTLOOK_SHARED_MAILBOX` | Opt-in shared-mailbox support, work/school accounts only: `read` or `true` (read and organise). Also add `Mail.Read.Shared` (and `Mail.ReadWrite.Shared` for `true`) in Azure, restart, then run `auth` with `action=authenticate` and `force=true` |
 
 ## Configuration Files by Client
 
@@ -76,7 +92,8 @@ File: `~/.codeium/windsurf/mcp_config.json`
 ## Verify Installation
 
 After authentication, test with:
-- `auth` tool with `action=status` — should show "authenticated"
+- `auth` tool with `action=status` — should report "Authenticated and ready"
+- `auth` tool with `action=about` — shows the connected mailbox, version and granted scopes
 - `search-emails` with no parameters — should list recent inbox emails
 
 ## Troubleshooting
@@ -84,7 +101,9 @@ After authentication, test with:
 | Problem | Solution |
 |---------|----------|
 | "Invalid client secret" (AADSTS7000215) | Use the secret **Value**, not the Secret ID. Also check it hasn't expired. v3.11.0+ appends an explanation to Microsoft's raw error |
-| Auth URL doesn't work | Start the auth server first |
+| Auth URL doesn't work | Browser flow only: start the auth server first. With the default device code flow, use `microsoft.com/devicelogin` |
+| Device code "invalid_client" | Enable "Allow public client flows" in Azure → Authentication → Advanced settings |
+| "Shared-mailbox support is turned off" | Set `OUTLOOK_SHARED_MAILBOX`, restart, and re-authenticate with `force=true` (work/school accounts only) |
 | "EADDRINUSE :3333" | Run `npx kill-port 3333` then restart auth server |
 | Empty API responses | Run `auth` tool with `action=status` to check token |
 | Search returns no results (personal account) | Use `from`, `subject`, `to` filters instead of `query` |