@lengelhard/imap-email-mcp 1.9.2 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.10.0
+
+### Added
+- **Replies stay in their thread.** `send_email`, `create_draft` and `update_draft` take `reply_to_uid` (with `reply_to_folder`), `in_reply_to` and `references`. Until now the connector had no way to set In-Reply-To or References, so every message it sent was a new conversation in the recipient's mail client and in Missive, even with the thread's subject line (seen 28 Sep 2026). With `reply_to_uid` the server reads the original's Message-ID, References and Subject and builds the headers as RFC 5322 §3.6.4 describes: In-Reply-To is the parent's Message-ID, References is the parent's References followed by its Message-ID. With `in_reply_to` alone, the chain is completed from the local index when it holds the parent, and is that id alone otherwise; the response says which. The subject is optional when replying and defaults to `Re: ` + the original subject; a caller-supplied subject without a reply prefix gets `Re: ` added, an existing `RE:`/`AW:` is kept. A stale `reply_to_uid` fails before anything is sent. Responses report `message_id`, `in_reply_to`, `references` and `threaded_from`, or `threaded: false`.
+- `list_drafts` and `get_draft` return `message_id`, `in_reply_to` and (on `get_draft`) `references`, and `list_drafts` reports `total`.
+- `findSentFolder`, `findDraftsFolder` and `findTrashFolder` all prefer the mailbox the server flags with SPECIAL-USE (`\Sent`, `\Drafts`, `\Trash`) and fall back to the usual names, so the copy of a sent message lands where the user's other clients look for it.
+
+### Changed
+- **Outgoing messages are built by nodemailer's MailComposer**, in `send_email`, `create_draft` and `update_draft`. The hand-assembled RFC 5322 strings put non-ASCII subjects into headers as raw UTF-8, sent bodies with no Content-Transfer-Encoding, and let a value containing a newline inject a header. Headers are now RFC 2047 encoded and folded, the body is encoded, and Message-ID and Date are set. The copy saved to Sent is the message that went on the wire (same Message-ID, same bytes) plus the Bcc header, which is stripped from the wire copy; previously it was a second, differently structured message assembled by hand.
+- `update_draft` appends the replacement draft first and erases the old one only once the new one is on the server. Previously the old draft was expunged before the new one was appended, so a failed append lost the draft. A `uid` that does not exist now changes nothing and says so.
+- Every tool now runs its IMAP commands under the `IMAP_OP_TIMEOUT_SECONDS` limit introduced in 1.7.3. `list_drafts`, `get_draft`, `create_draft`, `update_draft`, `download_attachment`, `extract_text`, `delete_email`, `flag_email`, `mark_seen`, `move_thread`, `list_folders` and the special-folder lookups still called the underlying library directly, so on a silent connection they waited out the 5-minute lease instead of failing in two.
+- `download_attachment`, `extract_text` and the draft readers open their folder read-only (EXAMINE), so reading never changes flags.
+
+### Fixed
+- **`delete_email` with `expunge: true` and `update_draft` erased every message in the folder flagged `\Deleted`, not just the one asked for.** Both flagged the target and then closed the mailbox with expunge, which is a mailbox-wide operation: a message another client had flagged `\Deleted` but not yet expunged was erased too. They now use UID EXPUNGE (UIDPLUS), scoped to the one message. On a server without UIDPLUS the call fails and takes the flag back off rather than erasing mail nobody asked about. `move_email`/`move_thread` share the same helper, which also closes the 1.9.2 gap where a missing UIDPLUS would have thrown outside the promise.
+- `flag_email`, `mark_seen` and `delete_email` reported `success: true` for a UID that does not exist, because IMAP STORE on a missing UID is a silent no-op. They now check the UID first and fail with the same "UIDs change when a message is moved" hint as `get_email`.
+- `list_folders` joined nested folder names with `.` regardless of the server's hierarchy delimiter, so a nested folder on a `/`-delimited server (Dovecot, Migadu) came back under a name no other tool would accept. It now uses each mailbox's own delimiter.
+
 ## 1.9.2
 
 ### Fixed

package/README.md

@@ -74,6 +74,7 @@ Add to your config file:
 - **Local full-text index** - Optional read-only SQLite index for reliable content search, independent of the server's body search
 - **Compose** - Create and save email drafts
 - **Send** - Send emails directly via SMTP
+- **Reply in thread** - Replies carry In-Reply-To and References, so mail clients keep them in the conversation instead of starting a new one
 - **Manage drafts** - List, read, update, and delete drafts
 - **Find duplicates** - Spot messages filed twice in one folder, or the same message sitting in several folders, matched on Message-ID
 - **Delete emails** - Move to Trash by default, with an explicit opt-in to erase permanently
@@ -140,6 +141,16 @@ A conversation can end up spread across folders without any message being duplic
 - **Honest coverage.** Rows indexed before 1.9.0 have no threading headers until the background sync backfills them, which it does at the end of each scheduled run for up to `INDEX_BACKFILL_SECONDS`, smallest folders first, without ever delaying the indexing of new mail. `coverage.without_thread_headers` and `index_status.thread_headers_pending` show how many are still waiting, and a thread touching such rows is marked `threading: "partial"`.
 - **Nothing is moved.** The tool only reports. `move_email` or `move_thread` are the tools for acting on it.
 
+### Replying in a thread
+
+Mail clients group messages into conversations by the In-Reply-To and References headers, not by subject. A message sent without them is a new conversation in every client, however familiar its subject looks. `send_email`, `create_draft` and `update_draft` therefore take:
+
+- **`reply_to_uid` + `reply_to_folder`** — the message being answered. The server reads its Message-ID, References and Subject and writes `In-Reply-To` and `References` itself (the parent's References followed by the parent's Message-ID, as RFC 5322 requires). Always pass the folder: UIDs are folder-scoped.
+- **`in_reply_to`** — the parent's Message-ID, as returned by `list_emails`, `search_emails` or `get_email`. When the local index holds that message the References chain is completed from it; otherwise References is that id alone, and the response says so.
+- **`references`** — an explicit chain, rarely needed.
+
+The subject is optional when replying and defaults to `Re: ` + the original subject. A caller-supplied subject with no `Re:`/`AW:`-style prefix gets `Re: ` added. The response reports `message_id`, `in_reply_to`, `references` and `threaded_from`, or `threaded: false` when no reply target was given. Messages are composed with nodemailer's MailComposer: non-ASCII headers are RFC 2047 encoded, bodies carry a Content-Transfer-Encoding, and the copy saved to Sent is the message that went out (plus the Bcc header, which is stripped on the wire).
+
 ### Provider Settings
 
 | Provider | IMAP_HOST | SMTP_HOST | Notes |
@@ -165,12 +176,12 @@ A conversation can end up spread across folders without any message being duplic
 | `find_split_threads` | Conversations spread across folders, threaded on In-Reply-To and References so renamed replies stay with their thread |
 | `move_email` | Move one message by UID. If the destination already holds it (same Message-ID) the source copy is removed instead, never duplicated |
 | `move_thread` | Move every message of a thread by subject in one call, with the same duplicate-safe behaviour |
-| `list_drafts` | List all draft emails |
-| `get_draft` | Get a specific draft by UID |
-| `create_draft` | Create a new email draft |
-| `update_draft` | Update an existing draft |
-| `send_email` | Send an email directly |
-| `delete_email` | Delete an email by UID. Moves to Trash unless `expunge: true` |
+| `list_drafts` | List drafts newest first, with `message_id` and `in_reply_to` |
+| `get_draft` | Get a specific draft by UID, with its threading headers |
+| `create_draft` | Create a draft; `reply_to_uid`/`in_reply_to` make it a threaded reply |
+| `update_draft` | Replace a draft: the new one is appended before the old one is erased |
+| `send_email` | Send via SMTP and save to Sent; `reply_to_uid`/`in_reply_to` keep a reply in its thread |
+| `delete_email` | Delete an email by UID. Moves to Trash unless `expunge: true`, which erases that one message (UID EXPUNGE) |
 | `download_attachment` | Download an attachment: ≤700KB returns inline base64, larger saves to disk (ATTACHMENT_DIR) |
 | `extract_text` | Extract plain text from a PDF, xlsx/xlsm/xls, docx, or text attachment in one call, parsed server-side |
 
@@ -181,6 +192,7 @@ Once configured, use natural language:
 - "Check my inbox for unread emails"
 - "Search for emails from john@example.com"
 - "Create a draft email to sarah@example.com about the meeting tomorrow"
+- "Reply to the latest message from Alicia in Action and confirm the figures" (the reply stays in her thread)
 - "Show me my drafts folder"
 
 ## Security Best Practices

package/index.js

@@ -21,15 +21,24 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { createRequire } from 'module';
+import MailComposer from 'nodemailer/lib/mail-composer/index.js';
+import { randomUUID } from 'crypto';
 import {
   setOpTimeout,
-  withTimeout,
   SessionManager,
+  listBoxes,
   openBox,
   queryUids,
   fetchMessages,
   headerOf,
-  buildCriteria
+  buildCriteria,
+  storeFlags,
+  expungeUids,
+  moveUids,
+  appendMessage,
+  uidExists,
+  flattenBoxTree,
+  findSpecialBox
 } from './lib/imap-session.js';
 import { htmlToText, stripDataUris, leafParts } from './lib/mime-text.js';
 import { LocalIndex, normalizeMessageId, parseMessageIdList } from './lib/local-index.js';
@@ -136,16 +145,6 @@ const SMTP_CONFIG = {
 // and the From header is the bare address.
 const SENDER_NAME = process.env.SENDER_NAME || '';
 
-// Build an RFC 5322 From value. ASCII names are quoted; anything else is
-// encoded as an RFC 2047 encoded-word so accents survive transport.
-function formatFrom(address) {
-  if (!SENDER_NAME) return address;
-  const name = /^[\x20-\x7E]*$/.test(SENDER_NAME)
-    ? `"${SENDER_NAME.replace(/["\\]/g, '\\$&')}"`
-    : `=?UTF-8?B?${Buffer.from(SENDER_NAME, 'utf8').toString('base64')}?=`;
-  return `${name} <${address}>`;
-}
-
 // Traverse the raw IMAP MIME struct to find all attachment parts.
 //
 // Detection rules (in priority order):
@@ -217,6 +216,27 @@ function validateConfig() {
   }
 }
 
+// Parameters shared by send_email, create_draft and update_draft that make the
+// outgoing message part of an existing conversation.
+const THREADING_PROPERTIES = {
+  reply_to_uid: {
+    type: 'number',
+    description: 'UID of the message being answered. The server reads its Message-ID, References and Subject and builds In-Reply-To and References itself. Always pass reply_to_folder with it.'
+  },
+  reply_to_folder: {
+    type: 'string',
+    description: 'Folder holding reply_to_uid (default: INBOX). UIDs are folder-scoped, so pass the folder the message was listed from.'
+  },
+  in_reply_to: {
+    type: 'string',
+    description: 'Message-ID of the message being answered (as returned by list_emails, search_emails or get_email; angle brackets optional). Used when reply_to_uid is not given. References is completed from the local index when it holds that message, else it is this id alone.'
+  },
+  references: {
+    type: 'string',
+    description: 'Explicit References chain, space-separated Message-IDs oldest first. Overrides what the server would build. Rarely needed.'
+  }
+};
+
 const server = new Server(
   {
     name: 'imap-email-mcp',
@@ -596,7 +616,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'create_draft',
-        description: 'Create a new draft email',
+        description: 'Create a new draft email. To draft a reply that stays in its thread, pass reply_to_uid (with reply_to_folder) or in_reply_to; see send_email for how threading is resolved.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -606,7 +626,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             subject: {
               type: 'string',
-              description: 'Email subject'
+              description: 'Email subject. Optional when replying (reply_to_uid or in_reply_to): defaults to "Re: " + the original subject.'
             },
             body: {
               type: 'string',
@@ -623,14 +643,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             bcc: {
               type: 'string',
               description: 'BCC recipients, comma-separated'
-            }
+            },
+            ...THREADING_PROPERTIES
           },
-          required: ['to', 'subject']
+          required: ['to']
         }
       },
       {
         name: 'update_draft',
-        description: 'Update an existing draft by deleting old and creating new',
+        description: 'Replace an existing draft: the new draft is appended first, then the old one is erased (UID EXPUNGE), so a failure never loses the draft. Accepts the same threading parameters as send_email.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -644,7 +665,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             subject: {
               type: 'string',
-              description: 'Email subject'
+              description: 'Email subject. Optional when replying (reply_to_uid or in_reply_to): defaults to "Re: " + the original subject.'
             },
             body: {
               type: 'string',
@@ -661,14 +682,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             bcc: {
               type: 'string',
               description: 'BCC recipients'
-            }
+            },
+            ...THREADING_PROPERTIES
           },
-          required: ['uid', 'to', 'subject']
+          required: ['uid', 'to']
         }
       },
       {
         name: 'send_email',
-        description: 'Send an email directly',
+        description: 'Send an email via SMTP and save a copy to Sent. A reply must carry In-Reply-To and References or every mail client shows it as a new conversation: pass reply_to_uid (plus reply_to_folder) and the server fetches the original\'s Message-ID and References and builds the headers, or pass in_reply_to (a Message-ID from list_emails/get_email) and the chain is completed from the local index when available. The subject defaults to "Re: " + the original subject when replying, and a caller-supplied subject gets "Re: " prefixed if it lacks one. The response reports message_id, in_reply_to and references as sent.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -678,7 +700,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             subject: {
               type: 'string',
-              description: 'Email subject'
+              description: 'Email subject. Optional when replying (reply_to_uid or in_reply_to): defaults to "Re: " + the original subject.'
             },
             body: {
               type: 'string',
@@ -695,9 +717,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             bcc: {
               type: 'string',
               description: 'BCC recipients'
-            }
+            },
+            ...THREADING_PROPERTIES
           },
-          required: ['to', 'subject']
+          required: ['to']
         }
       },
       {
@@ -892,6 +915,132 @@ function normalizeSubject(subject) {
   return subject.replace(/^(\s*(Re|Fwd|Fw)\s*:\s*)+/i, '').trim();
 }
 
+// Does the subject already read as a reply? Covers the usual localised prefixes.
+const REPLY_PREFIX = /^\s*(re|aw|sv|antw|vs|r)\s*(\[\d+\])?\s*:/i;
+
+/**
+ * Work out In-Reply-To, References and the subject for an outgoing message.
+ *
+ * Without these headers every mail client files the message as a brand-new
+ * conversation, however familiar the subject looks. RFC 5322 §3.6.4: a reply
+ * carries In-Reply-To = the parent's Message-ID and References = the parent's
+ * References followed by the parent's Message-ID (or its In-Reply-To when it
+ * has no References).
+ *
+ * `connection` may be null when only in_reply_to / references were given.
+ * Returns { inReplyTo, references, subject, source } with ids bracket-free
+ * (MailComposer adds the brackets), or subject alone when not a reply.
+ */
+async function resolveThreading(connection, args) {
+  let parent = null;
+  let source = null;
+
+  if (args.reply_to_uid != null) {
+    const folder = args.reply_to_folder || 'INBOX';
+    const uid = Number(args.reply_to_uid);
+    await openBox(connection, folder, true);
+    const fetched = await fetchMessages(connection, [uid], { bodies: ['HEADER.FIELDS (MESSAGE-ID IN-REPLY-TO REFERENCES SUBJECT)'] });
+    const rec = fetched.get(uid);
+    if (!rec) {
+      throw new Error(`reply_to_uid ${uid} not found in ${folder}. UIDs change when a message is moved; list or search again to get the current uid, and pass reply_to_folder.`);
+    }
+    const h = headerOf(rec, connection.imap.constructor.parseHeader);
+    parent = {
+      message_id: normalizeMessageId(h['message-id']?.[0]),
+      in_reply_to: parseMessageIdList(h['in-reply-to'])[0] || null,
+      references: parseMessageIdList(h.references),
+      subject: h.subject?.[0] || ''
+    };
+    if (!parent.message_id) {
+      throw new Error(`Message uid ${uid} in ${folder} has no Message-ID header, so a reply cannot be threaded to it. Send without reply_to_uid if a new conversation is acceptable.`);
+    }
+    source = `reply_to_uid ${uid} in ${folder}`;
+  } else if (args.in_reply_to) {
+    const id = normalizeMessageId(args.in_reply_to);
+    if (!id) throw new Error('in_reply_to is empty');
+    const indexed = localIndex ? localIndex.lookupMessageId(id) : null;
+    parent = indexed
+      ? { message_id: id, in_reply_to: indexed.in_reply_to, references: indexed.references, subject: indexed.subject }
+      : { message_id: id, in_reply_to: null, references: [], subject: '' };
+    source = indexed ? `in_reply_to (chain completed from the local index)` : 'in_reply_to (parent not in the local index; References is that id alone)';
+  }
+
+  if (!parent) {
+    if (args.references) {
+      // References without a parent: honour it as given, In-Reply-To is the last id.
+      const refs = parseMessageIdList(args.references);
+      if (refs.length) {
+        return { inReplyTo: refs[refs.length - 1], references: refs, subject: args.subject, source: 'references' };
+      }
+    }
+    return { subject: args.subject };
+  }
+
+  let references;
+  if (args.references) {
+    references = parseMessageIdList(args.references);
+  } else {
+    references = parent.references.length ? [...parent.references] : (parent.in_reply_to ? [parent.in_reply_to] : []);
+    if (!references.includes(parent.message_id)) references.push(parent.message_id);
+  }
+
+  let subject = args.subject;
+  if (subject == null || String(subject).trim() === '') {
+    const base = normalizeSubject(parent.subject);
+    if (!base) throw new Error('subject is required: the original message has no subject to derive "Re: ..." from');
+    subject = `Re: ${base}`;
+  } else if (!REPLY_PREFIX.test(subject)) {
+    subject = `Re: ${subject}`;
+  }
+
+  return { inReplyTo: parent.message_id, references, subject, source };
+}
+
+/**
+ * Build an RFC 5322 message with nodemailer's MailComposer: headers are
+ * encoded (RFC 2047 for non-ASCII, folded, no injection through a value with
+ * a newline), the body gets a proper Content-Transfer-Encoding, and a
+ * Message-ID and Date are set. `keepBcc` keeps the Bcc header in the output,
+ * which is right for a draft or a Sent copy and wrong for the wire.
+ * Resolves to { raw, envelope, messageId }.
+ */
+async function composeMessage(fields, threading, { keepBcc = false, messageId = null, date = null } = {}) {
+  const opts = {
+    from: SENDER_NAME ? { name: SENDER_NAME, address: fields.from } : fields.from,
+    to: fields.to,
+    subject: threading.subject,
+    text: fields.body ?? undefined,
+    html: fields.html ?? undefined,
+    cc: fields.cc || undefined,
+    bcc: fields.bcc || undefined,
+    date: date || new Date(),
+    messageId: messageId || undefined
+  };
+  if (threading.inReplyTo) opts.inReplyTo = `<${threading.inReplyTo}>`;
+  if (threading.references && threading.references.length) opts.references = threading.references.map((r) => `<${r}>`);
+  if (!opts.text && !opts.html) opts.text = '';
+  const compiled = new MailComposer(opts).compile();
+  // keepBcc is a MimeNode option, not a mail option: set it on the built root.
+  compiled.keepBcc = !!keepBcc;
+  const envelope = compiled.getEnvelope();
+  const id = compiled.messageId();
+  const raw = await compiled.build();
+  return { raw, envelope, messageId: id };
+}
+
+// Fresh Message-ID for a message that is composed twice (wire copy without
+// Bcc, Sent copy with it) so both carry the same id.
+function newMessageId(address) {
+  const domain = String(address || '').split('@')[1] || os.hostname();
+  return `<${randomUUID()}@${domain}>`;
+}
+
+function describeThreading(threading) {
+  return threading.inReplyTo
+    ? { in_reply_to: threading.inReplyTo, references: threading.references, threaded_from: threading.source }
+    : { threaded: false, note: 'No reply_to_uid or in_reply_to given, so this message starts a new conversation.' };
+}
+
 setOpTimeout(parseFloat(process.env.IMAP_OP_TIMEOUT_SECONDS || '120') * 1000);
 
 // Shared IMAP session. connectIMAP() returns a lease on one persistent
@@ -949,17 +1098,10 @@ async function moveWithoutDuplicates(connection, fromFolder, uids, toFolder) {
   for (const uid of uids) {
     try {
       if (present.has(uid)) {
-        await withTimeout(connection, `remove ${uid}`, new Promise((resolve, reject) => {
-          connection.imap.addFlags(uid, ['\\Deleted'], (err) => {
-            if (err) return reject(err);
-            connection.imap.expunge(uid, (e) => (e ? reject(e) : resolve()));
-          });
-        }));
+        await expungeUids(connection, [uid]);
         results.push({ uid, action: 'already_present', existing_uid: present.get(uid), message_id: idsByUid.get(uid) });
       } else {
-        await withTimeout(connection, `move ${uid}`, new Promise((resolve, reject) => {
-          connection.imap.move(uid, toFolder, (err) => (err ? reject(err) : resolve()));
-        }));
+        await moveUids(connection, [uid], toFolder);
         results.push({ uid, action: 'moved' });
       }
     } catch (err) {
@@ -1014,62 +1156,25 @@ function dateValue(item) {
 }
 
 /**
- * Find the mailbox that holds deleted mail.
- *
- * Prefers the folder the server itself flags as \Trash, since that is what the
- * user's other mail clients will treat as the bin, and falls back to the usual
- * names. Returns null when nothing plausible exists, which the caller reports
- * rather than guessing and writing mail somewhere unexpected.
+ * Special mailboxes. Each prefers the folder the server itself flags
+ * (\Trash, \Drafts, \Sent) when it advertises SPECIAL-USE, since that is what
+ * the user's other mail clients use, and falls back to the usual names.
+ * findTrashFolder returns null when nothing plausible exists, which the
+ * caller reports rather than guessing and writing mail somewhere unexpected.
  */
 async function findTrashFolder(connection) {
-  const boxes = await connection.getBoxes();
-  const walk = (node, prefix = '', out = []) => {
-    for (const [name, box] of Object.entries(node || {})) {
-      const full = prefix ? `${prefix}${box.delimiter || '/'}${name}` : name;
-      const attribs = (box.attribs || []).map((a) => String(a).toLowerCase());
-      if (box.special_use_attrib) attribs.push(String(box.special_use_attrib).toLowerCase());
-      out.push({ name: full, attribs, leaf: name });
-      if (box.children) walk(box.children, full, out);
-    }
-    return out;
-  };
-  const all = walk(boxes);
-  const selectable = all.filter((b) => !b.attribs.includes('\\noselect') && !b.attribs.includes('\\nonexistent'));
-
-  const flagged = selectable.find((b) => b.attribs.includes('\\trash'));
-  if (flagged) return flagged.name;
-
-  const known = ['trash', 'deleted items', 'deleted messages', 'bin', 'papierkorb', 'corbeille'];
-  const byName = selectable.find((b) => known.includes(b.leaf.toLowerCase()));
-  return byName ? byName.name : null;
+  return findSpecialBox(await listBoxes(connection), '\\trash',
+    ['Trash', 'Deleted Items', 'Deleted Messages', 'Bin', 'Papierkorb', 'Corbeille']);
 }
 
-// Helper to find drafts folder (handles different provider conventions)
 async function findDraftsFolder(connection) {
-  const boxes = await connection.getBoxes();
-
-  // Common drafts folder names across providers
-  const draftNames = [
-    'Drafts',
-    'INBOX.Drafts',
-    '[Gmail]/Drafts',
-    '[Google Mail]/Drafts',
-    'Draft',
-    'INBOX/Drafts'
-  ];
-
-  for (const name of draftNames) {
-    if (boxes[name] || name.split('.').reduce((acc, part) => acc?.[part], boxes)) {
-      return name;
-    }
-  }
-
-  // Check for nested Drafts under INBOX
-  if (boxes.INBOX && boxes.INBOX.children && boxes.INBOX.children.Drafts) {
-    return 'INBOX.Drafts';
-  }
+  return findSpecialBox(await listBoxes(connection), '\\drafts',
+    ['Drafts', 'INBOX.Drafts', 'INBOX/Drafts', '[Gmail]/Drafts', '[Google Mail]/Drafts', 'Draft']) || 'Drafts';
+}
 
-  return 'Drafts'; // Default fallback
+async function findSentFolder(connection) {
+  return findSpecialBox(await listBoxes(connection), '\\sent',
+    ['Sent', 'INBOX.Sent', 'INBOX/Sent', 'Sent Items', 'Sent Mail', 'Sent Messages', '[Gmail]/Sent Mail']) || 'Sent';
 }
 
 // Tool handlers
@@ -1095,20 +1200,9 @@ async function handleTool(name, args) {
       case 'list_folders': {
         const connection = await connectIMAP();
         try {
-          const boxes = await connection.getBoxes();
-          const folders = [];
-
-          function extractFolders(obj, prefix = '') {
-            for (const [key, value] of Object.entries(obj)) {
-              const fullPath = prefix ? `${prefix}.${key}` : key;
-              folders.push(fullPath);
-              if (value.children) {
-                extractFolders(value.children, fullPath);
-              }
-            }
-          }
-
-          extractFolders(boxes);
+          // Names are joined with each box's own delimiter, so a nested folder
+          // comes back exactly as the other tools expect it.
+          const folders = flattenBoxTree(await listBoxes(connection)).map((b) => b.name);
           return { content: [{ type: 'text', text: JSON.stringify(folders, null, 2) }] };
         } finally {
           connection.end();
@@ -1268,30 +1362,20 @@ async function handleTool(name, args) {
       }
 
       case 'list_drafts': {
-        const limit = args.limit || 20;
+        const limit = clampLimit(args.limit);
         const connection = await connectIMAP();
 
         try {
           const draftsFolder = await findDraftsFolder(connection);
-          await connection.openBox(draftsFolder);
-
-          const fetchOptions = {
-            bodies: ['HEADER.FIELDS (FROM TO SUBJECT DATE)'],
-            struct: true
-          };
-
-          const messages = await connection.search(['ALL'], fetchOptions);
-          const results = messages.slice(-limit).reverse().map(msg => {
-            const header = msg.parts.find(p => p.which.includes('HEADER'))?.body || {};
-            return {
-              uid: msg.attributes.uid,
-              date: header.date?.[0],
-              to: header.to?.[0],
-              subject: header.subject?.[0]
-            };
-          });
-
-          return { content: [{ type: 'text', text: JSON.stringify({ folder: draftsFolder, drafts: results }, null, 2) }] };
+          await openBox(connection, draftsFolder, true);
+          const uids = await queryUids(connection, ['ALL'], { order: 'arrival' });
+          const results = await summarize(connection, draftsFolder, uids.slice(0, limit), { withFlags: false });
+          const drafts = results.map(({ uid, date, to, subject, message_id, in_reply_to }) => ({
+            uid, date, to, subject,
+            ...(message_id && { message_id }),
+            ...(in_reply_to && { in_reply_to })
+          }));
+          return { content: [{ type: 'text', text: JSON.stringify({ folder: draftsFolder, total: uids.length, drafts }, null, 2) }] };
         } finally {
           connection.end();
         }
@@ -1302,33 +1386,31 @@ async function handleTool(name, args) {
 
         try {
           const draftsFolder = await findDraftsFolder(connection);
-          await connection.openBox(draftsFolder);
-
-          const fetchOptions = {
-            bodies: [''],
-            struct: true
-          };
+          await openBox(connection, draftsFolder, true);
 
-          const messages = await connection.search([['UID', args.uid]], fetchOptions);
-
-          if (messages.length === 0) {
-            return { content: [{ type: 'text', text: 'Draft not found' }] };
+          const uid = Number(args.uid);
+          const fetched = await fetchMessages(connection, [uid], { bodies: [''] });
+          const rec = fetched.get(uid);
+          if (!rec) {
+            return { content: [{ type: 'text', text: `Draft not found: uid ${uid} in ${draftsFolder}` }], isError: true };
           }
 
-          const msg = messages[0];
-          const rawBody = msg.parts.find(p => p.which === '')?.body;
-          const parsed = await simpleParser(rawBody);
+          const parsed = await simpleParser(rec.parts[''] ?? rec.parts[Object.keys(rec.parts)[0]]);
 
           return {
             content: [{
               type: 'text',
               text: JSON.stringify({
-                uid: msg.attributes.uid,
+                uid,
+                folder: draftsFolder,
                 to: parsed.to?.text,
                 cc: parsed.cc?.text,
                 bcc: parsed.bcc?.text,
                 subject: parsed.subject,
                 date: parsed.date,
+                ...(normalizeMessageId(parsed.messageId) && { message_id: normalizeMessageId(parsed.messageId) }),
+                ...(parseMessageIdList(parsed.inReplyTo)[0] && { in_reply_to: parseMessageIdList(parsed.inReplyTo)[0] }),
+                ...(parseMessageIdList(parsed.references).length && { references: parseMessageIdList(parsed.references) }),
                 text: parsed.text,
                 html: parsed.html
               }, null, 2)
@@ -1344,35 +1426,26 @@ async function handleTool(name, args) {
 
         try {
           const draftsFolder = await findDraftsFolder(connection);
+          const threading = await resolveThreading(connection, args);
+          if (!threading.subject) throw new Error('subject is required unless replying (reply_to_uid or in_reply_to)');
+          const { raw, messageId } = await composeMessage(
+            { from: IMAP_CONFIG.imap.user, to: args.to, cc: args.cc, bcc: args.bcc, body: args.body, html: args.html },
+            threading, { keepBcc: true }
+          );
+          await appendMessage(connection, raw, draftsFolder, ['\\Draft']);
 
-          // Build RFC 2822 compliant email message
-          const boundary = `----=_Part_${Date.now()}`;
-          let message = '';
-          message += `From: ${formatFrom(IMAP_CONFIG.imap.user)}\r\n`;
-          message += `To: ${args.to}\r\n`;
-          if (args.cc) message += `Cc: ${args.cc}\r\n`;
-          if (args.bcc) message += `Bcc: ${args.bcc}\r\n`;
-          message += `Subject: ${args.subject}\r\n`;
-          message += `Date: ${new Date().toUTCString()}\r\n`;
-          message += `MIME-Version: 1.0\r\n`;
-
-          if (args.html) {
-            message += `Content-Type: multipart/alternative; boundary="${boundary}"\r\n\r\n`;
-            message += `--${boundary}\r\n`;
-            message += `Content-Type: text/plain; charset=utf-8\r\n\r\n`;
-            message += `${args.body || ''}\r\n`;
-            message += `--${boundary}\r\n`;
-            message += `Content-Type: text/html; charset=utf-8\r\n\r\n`;
-            message += `${args.html}\r\n`;
-            message += `--${boundary}--\r\n`;
-          } else {
-            message += `Content-Type: text/plain; charset=utf-8\r\n\r\n`;
-            message += `${args.body || ''}\r\n`;
-          }
-
-          await connection.append(message, { mailbox: draftsFolder, flags: ['\\Draft'] });
-
-          return { content: [{ type: 'text', text: `Draft created successfully in ${draftsFolder}` }] };
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                success: true,
+                folder: draftsFolder,
+                subject: threading.subject,
+                message_id: normalizeMessageId(messageId),
+                ...describeThreading(threading)
+              }, null, 2)
+            }]
+          };
         } finally {
           connection.end();
         }
@@ -1383,42 +1456,41 @@ async function handleTool(name, args) {
 
         try {
           const draftsFolder = await findDraftsFolder(connection);
-          await connection.openBox(draftsFolder);
-
-          // Delete old draft
-          await connection.addFlags(args.uid, ['\\Deleted']);
-          await connection.closeBox(true); // Expunge
-
-          // Create new draft
-          await connection.openBox(draftsFolder);
-
-          const boundary = `----=_Part_${Date.now()}`;
-          let message = '';
-          message += `From: ${formatFrom(IMAP_CONFIG.imap.user)}\r\n`;
-          message += `To: ${args.to}\r\n`;
-          if (args.cc) message += `Cc: ${args.cc}\r\n`;
-          if (args.bcc) message += `Bcc: ${args.bcc}\r\n`;
-          message += `Subject: ${args.subject}\r\n`;
-          message += `Date: ${new Date().toUTCString()}\r\n`;
-          message += `MIME-Version: 1.0\r\n`;
-
-          if (args.html) {
-            message += `Content-Type: multipart/alternative; boundary="${boundary}"\r\n\r\n`;
-            message += `--${boundary}\r\n`;
-            message += `Content-Type: text/plain; charset=utf-8\r\n\r\n`;
-            message += `${args.body || ''}\r\n`;
-            message += `--${boundary}\r\n`;
-            message += `Content-Type: text/html; charset=utf-8\r\n\r\n`;
-            message += `${args.html}\r\n`;
-            message += `--${boundary}--\r\n`;
-          } else {
-            message += `Content-Type: text/plain; charset=utf-8\r\n\r\n`;
-            message += `${args.body || ''}\r\n`;
+          const oldUid = Number(args.uid);
+
+          // Build and append the replacement first. Only once it is safely in
+          // the folder is the old draft erased, and only that one uid, so a
+          // failure part-way never loses the draft or touches other mail.
+          const threading = await resolveThreading(connection, args);
+          if (!threading.subject) throw new Error('subject is required unless replying (reply_to_uid or in_reply_to)');
+          const { raw, messageId } = await composeMessage(
+            { from: IMAP_CONFIG.imap.user, to: args.to, cc: args.cc, bcc: args.bcc, body: args.body, html: args.html },
+            threading, { keepBcc: true }
+          );
+
+          await openBox(connection, draftsFolder, false);
+          if (!(await uidExists(connection, oldUid))) {
+            return {
+              content: [{ type: 'text', text: `Draft not found: uid ${oldUid} in ${draftsFolder}. Nothing was changed; use list_drafts to get the current uid.` }],
+              isError: true
+            };
           }
+          await appendMessage(connection, raw, draftsFolder, ['\\Draft']);
+          await expungeUids(connection, [oldUid]);
 
-          await connection.append(message, { mailbox: draftsFolder, flags: ['\\Draft'] });
-
-          return { content: [{ type: 'text', text: 'Draft updated successfully' }] };
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                success: true,
+                folder: draftsFolder,
+                replaced_uid: oldUid,
+                subject: threading.subject,
+                message_id: normalizeMessageId(messageId),
+                ...describeThreading(threading)
+              }, null, 2)
+            }]
+          };
         } finally {
           connection.end();
         }
@@ -1432,73 +1504,40 @@ async function handleTool(name, args) {
           };
         }
 
-        const transporter = nodemailer.createTransport(SMTP_CONFIG);
-
-        const mailOptions = {
-          from: SENDER_NAME
-            ? { name: SENDER_NAME, address: SMTP_CONFIG.auth.user }
-            : SMTP_CONFIG.auth.user,
-          to: args.to,
-          subject: args.subject,
-          text: args.body,
-          html: args.html,
-          cc: args.cc,
-          bcc: args.bcc
-        };
-
-        // Send via SMTP and capture the raw RFC 5322 message
-        const info = await transporter.sendMail(mailOptions);
-
-        // Build RFC 5322 message string to APPEND to Sent folder via IMAP
-        // Use the same content that was sent so the Sent copy is identical
-        const sentDate = new Date();
-        const boundary = `----=_Part_${Date.now()}`;
-        let rawMessage = '';
-        rawMessage += `From: ${formatFrom(SMTP_CONFIG.auth.user)}\r\n`;
-        rawMessage += `To: ${args.to}\r\n`;
-        if (args.cc) rawMessage += `Cc: ${args.cc}\r\n`;
-        if (args.bcc) rawMessage += `Bcc: ${args.bcc}\r\n`;
-        rawMessage += `Subject: ${args.subject}\r\n`;
-        rawMessage += `Date: ${sentDate.toUTCString()}\r\n`;
-        rawMessage += `Message-ID: ${info.messageId}\r\n`;
-        rawMessage += `MIME-Version: 1.0\r\n`;
-
-        if (args.html) {
-          rawMessage += `Content-Type: multipart/alternative; boundary="${boundary}"\r\n\r\n`;
-          rawMessage += `--${boundary}\r\n`;
-          rawMessage += `Content-Type: text/plain; charset=utf-8\r\n\r\n`;
-          rawMessage += `${args.body || ''}\r\n`;
-          rawMessage += `--${boundary}\r\n`;
-          rawMessage += `Content-Type: text/html; charset=utf-8\r\n\r\n`;
-          rawMessage += `${args.html}\r\n`;
-          rawMessage += `--${boundary}--\r\n`;
+        // Resolve threading first (needs IMAP when reply_to_uid is given), so a
+        // bad uid fails before anything is sent.
+        let threading;
+        if (args.reply_to_uid != null) {
+          const connection = await connectIMAP();
+          try {
+            threading = await resolveThreading(connection, args);
+          } finally {
+            connection.end();
+          }
         } else {
-          rawMessage += `Content-Type: text/plain; charset=utf-8\r\n\r\n`;
-          rawMessage += `${args.body || ''}\r\n`;
+          threading = await resolveThreading(null, args);
         }
+        if (!threading.subject) throw new Error('subject is required unless replying (reply_to_uid or in_reply_to)');
+
+        // One Message-ID and Date for both copies: the wire copy has no Bcc
+        // header, the Sent copy keeps it, everything else is byte-identical.
+        const from = SMTP_CONFIG.auth.user;
+        const messageId = newMessageId(from);
+        const date = new Date();
+        const fields = { from, to: args.to, cc: args.cc, bcc: args.bcc, body: args.body, html: args.html };
+        const wire = await composeMessage(fields, threading, { keepBcc: false, messageId, date });
+
+        const transporter = nodemailer.createTransport(SMTP_CONFIG);
+        const info = await transporter.sendMail({ envelope: wire.envelope, raw: wire.raw });
 
-        // APPEND to Sent folder via IMAP
+        // Save a copy to Sent via IMAP
         let sentFolderResult = 'skipped';
         try {
+          const sentCopy = args.bcc ? await composeMessage(fields, threading, { keepBcc: true, messageId, date }) : wire;
           const connection = await connectIMAP();
           try {
-            // Try common Sent folder names in order
-            const sentFolderCandidates = ['Sent', 'INBOX.Sent', 'Sent Items', 'Sent Mail', '[Gmail]/Sent Mail'];
-            let sentFolder = 'Sent'; // default fallback
-
-            const folders = await connection.getBoxes();
-            const flatFolders = Object.keys(folders);
-            for (const candidate of sentFolderCandidates) {
-              if (flatFolders.some(f => f.toLowerCase() === candidate.toLowerCase())) {
-                sentFolder = candidate;
-                break;
-              }
-            }
-
-            await connection.append(rawMessage, {
-              mailbox: sentFolder,
-              flags: ['\\Seen']
-            });
+            const sentFolder = await findSentFolder(connection);
+            await appendMessage(connection, sentCopy.raw, sentFolder, ['\\Seen']);
             sentFolderResult = `saved to ${sentFolder}`;
           } finally {
             connection.end();
@@ -1512,7 +1551,12 @@ async function handleTool(name, args) {
             type: 'text',
             text: JSON.stringify({
               success: true,
-              messageId: info.messageId,
+              message_id: normalizeMessageId(messageId),
+              messageId,
+              subject: threading.subject,
+              ...describeThreading(threading),
+              accepted: info.accepted,
+              rejected: info.rejected,
               response: info.response,
               sentFolder: sentFolderResult
             }, null, 2)
@@ -1525,19 +1569,19 @@ async function handleTool(name, args) {
         const connection = await connectIMAP();
 
         try {
-          await connection.openBox(folder);
+          await openBox(connection, folder, true);
 
           // Fetch struct to locate the part
-          const structFetch = await connection.search([['UID', args.uid]], {
-            bodies: [],
-            struct: true
-          });
-
-          if (structFetch.length === 0) {
-            return { content: [{ type: 'text', text: 'Email not found' }] };
+          const uid = Number(args.uid);
+          const structFetch = await fetchMessages(connection, [uid], { bodies: [], struct: true });
+          const msg = structFetch.get(uid);
+          if (!msg) {
+            return {
+              content: [{ type: 'text', text: `Email not found: uid ${uid} in ${folder}. UIDs change when a message is moved; search again to get the current uid.` }],
+              isError: true
+            };
           }
 
-          const msg = structFetch[0];
           let partID = args.part_id;
 
           // If no partID given, find it by filename
@@ -1557,20 +1601,12 @@ async function handleTool(name, args) {
           }
 
           // Fetch the specific MIME part
-          const partFetch = await connection.search([['UID', args.uid]], {
-            bodies: [partID],
-            struct: true
-          });
-
-          if (partFetch.length === 0) {
-            return { content: [{ type: 'text', text: 'Attachment part not found' }] };
-          }
-
-          const partData = partFetch[0].parts.find(p => p.which === partID);
-
-          if (!partData) {
-            return { content: [{ type: 'text', text: `Part ${partID} not found in message` }] };
+          const partFetch = await fetchMessages(connection, [uid], { bodies: [partID] });
+          const partBody = partFetch.get(uid)?.parts?.[partID];
+          if (partBody == null) {
+            return { content: [{ type: 'text', text: `Part ${partID} not found in message uid ${uid}` }], isError: true };
           }
+          const partData = { body: partBody };
 
           const attachmentParts = findAttachmentParts(msg.attributes.struct || []);
           const attachmentInfo = attachmentParts.find(p => p.partID === partID);
@@ -1660,18 +1696,19 @@ async function handleTool(name, args) {
         const connection = await connectIMAP();
 
         try {
-          await connection.openBox(folder);
-
-          const structFetch = await connection.search([['UID', args.uid]], {
-            bodies: [],
-            struct: true
-          });
+          await openBox(connection, folder, true);
 
-          if (structFetch.length === 0) {
-            return { content: [{ type: 'text', text: 'Email not found' }] };
+          // Fetch struct to locate the part
+          const uid = Number(args.uid);
+          const structFetch = await fetchMessages(connection, [uid], { bodies: [], struct: true });
+          const msg = structFetch.get(uid);
+          if (!msg) {
+            return {
+              content: [{ type: 'text', text: `Email not found: uid ${uid} in ${folder}. UIDs change when a message is moved; search again to get the current uid.` }],
+              isError: true
+            };
           }
 
-          const msg = structFetch[0];
           let partID = args.part_id;
 
           if (!partID && args.filename) {
@@ -1689,20 +1726,12 @@ async function handleTool(name, args) {
             };
           }
 
-          const partFetch = await connection.search([['UID', args.uid]], {
-            bodies: [partID],
-            struct: true
-          });
-
-          if (partFetch.length === 0) {
-            return { content: [{ type: 'text', text: 'Attachment part not found' }] };
-          }
-
-          const partData = partFetch[0].parts.find(p => p.which === partID);
-
-          if (!partData) {
-            return { content: [{ type: 'text', text: `Part ${partID} not found in message` }] };
+          const partFetch = await fetchMessages(connection, [uid], { bodies: [partID] });
+          const partBody = partFetch.get(uid)?.parts?.[partID];
+          if (partBody == null) {
+            return { content: [{ type: 'text', text: `Part ${partID} not found in message uid ${uid}` }], isError: true };
           }
+          const partData = { body: partBody };
 
           const attachmentParts = findAttachmentParts(msg.attributes.struct || []);
           const attachmentInfo = attachmentParts.find(p => p.partID === partID);
@@ -1784,12 +1813,17 @@ async function handleTool(name, args) {
           const trash = args.expunge ? null : await findTrashFolder(connection);
           const alreadyInTrash = trash && trash.toLowerCase() === folder.toLowerCase();
 
-          await connection.openBox(folder);
+          const uid = Number(args.uid);
+          await openBox(connection, folder, false);
+          if (!(await uidExists(connection, uid))) {
+            return {
+              content: [{ type: 'text', text: `Email not found: uid ${uid} in ${folder}. Nothing was deleted. UIDs change when a message is moved; search again to get the current uid.` }],
+              isError: true
+            };
+          }
 
           if (trash && !alreadyInTrash) {
-            await new Promise((resolve, reject) => {
-              connection.imap.move(args.uid, trash, (err) => (err ? reject(err) : resolve()));
-            });
+            await moveUids(connection, [uid], trash);
             return {
               content: [{
                 type: 'text',
@@ -1818,8 +1852,8 @@ async function handleTool(name, args) {
             };
           }
 
-          await connection.addFlags(args.uid, ['\\Deleted']);
-          await connection.closeBox(true); // Expunge
+          // UID EXPUNGE: erases this one message, never the folder's other \Deleted mail.
+          await expungeUids(connection, [uid]);
           return {
             content: [{
               type: 'text',
@@ -1844,7 +1878,7 @@ async function handleTool(name, args) {
         const connection = await connectIMAP();
 
         try {
-          await connection.openBox(fromFolder);
+          await openBox(connection, fromFolder, false);
 
           const [r] = await moveWithoutDuplicates(connection, fromFolder, [Number(args.uid)], toFolder);
           if (r.action === 'failed') throw new Error(r.error);
@@ -1875,22 +1909,26 @@ async function handleTool(name, args) {
         const connection = await connectIMAP();
 
         try {
-          await connection.openBox(folder);
-
-          if (args.flagged) {
-            await connection.addFlags(args.uid, ['\\Flagged']);
-          } else {
-            await connection.delFlags(args.uid, ['\\Flagged']);
+          const uid = Number(args.uid);
+          await openBox(connection, folder, false);
+          // STORE on a uid that does not exist is a silent no-op, so check first
+          // rather than report success for a stale uid.
+          if (!(await uidExists(connection, uid))) {
+            return {
+              content: [{ type: 'text', text: `Email not found: uid ${uid} in ${folder}. Nothing was changed. UIDs change when a message is moved; search again to get the current uid.` }],
+              isError: true
+            };
           }
+          await storeFlags(connection, [uid], ['\\Flagged'], !!args.flagged);
 
           return {
             content: [{
               type: 'text',
               text: JSON.stringify({
                 success: true,
-                uid: args.uid,
+                uid,
                 folder,
-                flagged: args.flagged
+                flagged: !!args.flagged
               }, null, 2)
             }]
           };
@@ -1904,22 +1942,24 @@ async function handleTool(name, args) {
         const connection = await connectIMAP();
 
         try {
-          await connection.openBox(folder);
-
-          if (args.seen) {
-            await connection.addFlags(args.uid, ['\\Seen']);
-          } else {
-            await connection.delFlags(args.uid, ['\\Seen']);
+          const uid = Number(args.uid);
+          await openBox(connection, folder, false);
+          if (!(await uidExists(connection, uid))) {
+            return {
+              content: [{ type: 'text', text: `Email not found: uid ${uid} in ${folder}. Nothing was changed. UIDs change when a message is moved; search again to get the current uid.` }],
+              isError: true
+            };
           }
+          await storeFlags(connection, [uid], ['\\Seen'], !!args.seen);
 
           return {
             content: [{
               type: 'text',
               text: JSON.stringify({
                 success: true,
-                uid: args.uid,
+                uid,
                 folder,
-                seen: args.seen
+                seen: !!args.seen
               }, null, 2)
             }]
           };
@@ -1942,7 +1982,7 @@ async function handleTool(name, args) {
         const connection = await connectIMAP();
 
         try {
-          await connection.openBox(from_folder);
+          await openBox(connection, from_folder, false);
 
           // Build IMAP search criteria: match subject header (and optionally sender)
           const searchCriteria = [['SUBJECT', normalizedTarget]];
@@ -1950,12 +1990,10 @@ async function handleTool(name, args) {
             searchCriteria.push(['FROM', from_address]);
           }
 
-          const fetchOptions = {
-            bodies: ['HEADER.FIELDS (SUBJECT FROM)'],
-            struct: false
-          };
-
-          const messages = await connection.search(searchCriteria, fetchOptions);
+          const candidateUids = await queryUids(connection, searchCriteria, { order: 'arrival' });
+          const fetched = await fetchMessages(connection, candidateUids, { bodies: ['HEADER.FIELDS (SUBJECT FROM)'] });
+          const parseHeader = connection.imap.constructor.parseHeader;
+          const messages = candidateUids.filter((u) => fetched.has(u)).map((u) => ({ uid: u, header: headerOf(fetched.get(u), parseHeader) }));
 
           if (messages.length === 0) {
             return {
@@ -1977,10 +2015,9 @@ async function handleTool(name, args) {
           // each message's normalized subject matches the target exactly.
           const matchingUIDs = [];
           for (const msg of messages) {
-            const header = msg.parts.find(p => p.which.includes('HEADER'))?.body || {};
-            const msgSubject = normalizeSubject((header.subject || [])[0] || '');
+            const msgSubject = normalizeSubject((msg.header.subject || [])[0] || '');
             if (msgSubject.toLowerCase() === normalizedTarget.toLowerCase()) {
-              matchingUIDs.push(msg.attributes.uid);
+              matchingUIDs.push(msg.uid);
             }
           }
 

package/lib/imap-session.js

@@ -281,6 +281,113 @@ export function serverSupports(connection, cap) {
   try { return !!connection.imap.serverSupports(cap); } catch { return false; }
 }
 
+/** STORE flags on one UID or a list, under the command time limit. add=false removes them. */
+export function storeFlags(connection, uids, flags, add = true) {
+  const list = [].concat(uids).map(Number);
+  if (!list.length) return Promise.resolve();
+  const verb = add ? 'addFlags' : 'delFlags';
+  return withTimeout(connection, `${add ? 'set' : 'clear'} flags on ${list.length} message(s)`, new Promise((resolve, reject) => {
+    try {
+      connection.imap[verb](list, flags, (err) => (err ? reject(err) : resolve()));
+    } catch (err) {
+      reject(err);
+    }
+  }));
+}
+
+/**
+ * Erase exactly these UIDs from the open mailbox and nothing else.
+ *
+ * CLOSE and a bare EXPUNGE erase every message in the mailbox that carries
+ * \Deleted, including ones another client flagged and has not expunged yet.
+ * UID EXPUNGE (UIDPLUS) is scoped to the given set. On a server without
+ * UIDPLUS the flag is taken back off and the call fails, rather than erasing
+ * mail nobody asked about.
+ */
+export function expungeUids(connection, uids) {
+  const list = [].concat(uids).map(Number);
+  if (!list.length) return Promise.resolve();
+  return withTimeout(connection, `expunge ${list.length} message(s)`, new Promise((resolve, reject) => {
+    try {
+      connection.imap.addFlags(list, ['\\Deleted'], (err) => {
+        if (err) return reject(err);
+        if (!serverSupports(connection, 'UIDPLUS')) {
+          connection.imap.delFlags(list, ['\\Deleted'], () => reject(new Error('server does not support UIDPLUS, so a single message cannot be expunged without erasing every other message flagged \\Deleted; nothing was erased')));
+          return;
+        }
+        try {
+          connection.imap.expunge(list, (e) => (e ? reject(e) : resolve()));
+        } catch (e) {
+          reject(e);
+        }
+      });
+    } catch (err) {
+      reject(err);
+    }
+  }));
+}
+
+/** MOVE one UID or a list to another mailbox, under the command time limit. */
+export function moveUids(connection, uids, mailbox) {
+  const list = [].concat(uids).map(Number);
+  if (!list.length) return Promise.resolve();
+  return withTimeout(connection, `move ${list.length} message(s) to ${mailbox}`, new Promise((resolve, reject) => {
+    try {
+      connection.imap.move(list, mailbox, (err) => (err ? reject(err) : resolve()));
+    } catch (err) {
+      reject(err);
+    }
+  }));
+}
+
+/** APPEND a raw RFC 5322 message to a mailbox, under the command time limit. */
+export function appendMessage(connection, raw, mailbox, flags = []) {
+  return withTimeout(connection, `append to ${mailbox}`, new Promise((resolve, reject) => {
+    try {
+      connection.imap.append(raw, { mailbox, flags }, (err) => (err ? reject(err) : resolve()));
+    } catch (err) {
+      reject(err);
+    }
+  }));
+}
+
+/** True when the UID exists in the open mailbox. STORE on a missing UID is a silent no-op, so check first. */
+export async function uidExists(connection, uid) {
+  const fetched = await fetchMessages(connection, [Number(uid)], { bodies: [] });
+  return fetched.has(Number(uid));
+}
+
+/**
+ * Flatten node-imap's nested mailbox tree into a list of
+ * { name, leaf, delimiter, attribs } using each box's own delimiter, so a
+ * nested folder comes back under the name the server expects.
+ */
+export function flattenBoxTree(boxes, prefix = '', out = []) {
+  for (const [leaf, box] of Object.entries(boxes || {})) {
+    const delimiter = box.delimiter || '/';
+    const name = prefix ? `${prefix}${delimiter}${leaf}` : leaf;
+    const attribs = (box.attribs || []).map((a) => String(a).toLowerCase());
+    if (box.special_use_attrib) attribs.push(String(box.special_use_attrib).toLowerCase());
+    out.push({ name, leaf, delimiter, attribs });
+    if (box.children) flattenBoxTree(box.children, name, out);
+  }
+  return out;
+}
+
+/**
+ * Find a special mailbox: the one the server flags with `specialUse`
+ * (\Trash, \Drafts, \Sent) when it advertises SPECIAL-USE, else the first
+ * selectable box whose leaf name is in `names`. Returns null when neither.
+ */
+export function findSpecialBox(boxes, specialUse, names) {
+  const all = flattenBoxTree(boxes).filter((b) => !b.attribs.includes('\\noselect') && !b.attribs.includes('\\nonexistent'));
+  const flagged = all.find((b) => b.attribs.includes(specialUse.toLowerCase()));
+  if (flagged) return flagged.name;
+  const wanted = names.map((n) => n.toLowerCase());
+  const byName = all.find((b) => wanted.includes(b.leaf.toLowerCase()) || wanted.includes(b.name.toLowerCase()));
+  return byName ? byName.name : null;
+}
+
 /**
  * Return matching UIDs, newest first.
  * order 'arrival' uses the server's internal date (delivery time, preserved on

package/lib/local-index.js

@@ -1078,6 +1078,31 @@ export class LocalIndex {
     };
   }
 
+  /**
+   * Find one indexed message by Message-ID and return its threading headers,
+   * so a reply sent by Message-ID alone can carry the full References chain.
+   * Returns null when the index does not hold it (or holds it without
+   * threading headers yet).
+   */
+  lookupMessageId(messageId) {
+    const id = normalizeMessageId(messageId);
+    if (!id || !this.db) return null;
+    const r = this.db.prepare(`
+      SELECT folder, uid, subject, message_id, in_reply_to, references_ids, thread_headers
+      FROM messages WHERE message_id = ? OR message_id = ? LIMIT 1
+    `).get(`<${id}>`, id);
+    if (!r) return null;
+    return {
+      folder: r.folder,
+      uid: r.uid,
+      subject: r.subject || '',
+      message_id: id,
+      in_reply_to: r.in_reply_to || null,
+      references: r.references_ids ? r.references_ids.split(' ').filter(Boolean) : [],
+      thread_headers: !!r.thread_headers
+    };
+  }
+
   search({ query, folders = null, from = null, since_date = null, before_date = null, field = 'any', match = 'all', prefix = false, sort = 'date', limit = 20, offset = 0 }) {
     const where = ['fts MATCH ?'];
     const params = [ftsQuery(query, { match, prefix, field })];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lengelhard/imap-email-mcp",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "MCP server for Claude Code that provides email capabilities through IMAP/SMTP. Read, search, compose, and manage emails from any IMAP provider.",
   "type": "module",
   "main": "index.js",