apple-mail-mcp 2.4.2 → 2.6.0

package/build/services/imapMultiAccount.js

@@ -0,0 +1,253 @@
+/**
+ * Multi-account read merge (v2.6.0 — prefer-IMAP reads).
+ *
+ * v2.6.0 flips the read tools to PREFER direct IMAP whenever IMAP is configured
+ * (see `shouldUseImap` in imapClient.ts). When a read is issued with NO explicit
+ * account, results must still cover EVERY account the user has — so we:
+ *
+ *   1. fan the IMAP query out over every configured IMAP account
+ *      (`resolveImapConfigs()`), and
+ *   2. ALSO run the existing AppleScript all-accounts path,
+ *
+ * then merge the two, de-duplicating any message that appears in both backends
+ * (e.g. a Gmail account that is both IMAP-configured AND visible to Mail.app's
+ * AppleScript scan) and preferring the IMAP copy (it carries the round-trippable
+ * `imap:` id that the mutation tools need).
+ *
+ * This module holds the backend-agnostic merge/dedup/sort + the per-account IMAP
+ * fan-out so the three message-list sites (search-messages, get-thread,
+ * list-messages) don't each re-implement it.
+ *
+ * @module services/imapMultiAccount
+ */
+import { imapSearchMessages, imapListMessages, resolveImapConfigs, } from "../services/imapClient.js";
+/**
+ * Normalize a Message-ID for comparison: strip surrounding angle brackets and
+ * whitespace, lowercase. Returns undefined when the row has no usable id.
+ */
+function normalizeMessageId(row) {
+    const raw = typeof row.messageId === "string" ? row.messageId.trim() : "";
+    if (!raw)
+        return undefined;
+    const inner = raw.replace(/^<+|>+$/g, "").trim();
+    return inner ? inner.toLowerCase() : undefined;
+}
+/**
+ * Normalize a subject the same way the thread tool does for grouping: drop
+ * leading Re:/Fwd: prefixes, collapse whitespace, lowercase. Kept local (and
+ * deliberately simple) so the merge has no dependency cycle with the thread
+ * module; exactness isn't required — this only feeds the fallback dedup key.
+ */
+function normalizeSubjectForKey(subject) {
+    const s = typeof subject === "string" ? subject : "";
+    return s
+        .replace(/^(\s*(re|fwd|fw|aw|sv|antw)\s*:\s*)+/i, "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+/** Epoch ms of the row's dateReceived (ISO string or Date), or 0 when absent. */
+function dateEpoch(row) {
+    const d = row.dateReceived;
+    if (d instanceof Date)
+        return d.getTime();
+    if (typeof d === "string" && d) {
+        const t = new Date(d).getTime();
+        return Number.isNaN(t) ? 0 : t;
+    }
+    return 0;
+}
+/**
+ * Cross-backend dedup key for a message row.
+ *
+ *   - PREFER the normalized Message-ID when present (`mid:<id>`). It's the only
+ *     globally-unique identity, so two IMAP accounts that both hold the very
+ *     same message (rare, but possible with multi-delivery) collapse to one.
+ *   - FALL BACK to `normalizedSubject|sender|dateReceivedEpoch` when no
+ *     Message-ID is available. The AppleScript backend never exposes a
+ *     Message-ID, so this composite is what actually dedups the common case: a
+ *     Gmail account surfaced by BOTH the IMAP fan-out and the AppleScript
+ *     all-accounts scan. The IMAP and AppleScript copies of one message share
+ *     the same subject, sender, and received timestamp, so they collide here.
+ *
+ * Limitation (note for live testing): the composite key assumes the two backends
+ * report the SAME received timestamp to the second. If Mail.app and the IMAP
+ * server disagree on `dateReceived` (timezone/rounding), a message could escape
+ * dedup and appear twice. Message-ID dedup (IMAP-vs-IMAP) is exact; the
+ * composite is best-effort.
+ */
+export function dedupKey(row) {
+    const mid = normalizeMessageId(row);
+    if (mid)
+        return `mid:${mid}`;
+    const subject = normalizeSubjectForKey(row.subject);
+    const sender = (typeof row.sender === "string" ? row.sender : "").trim().toLowerCase();
+    return `k:${subject}|${sender}|${dateEpoch(row)}`;
+}
+/**
+ * Merge IMAP rows with AppleScript rows: concatenate, de-dup by {@link dedupKey}
+ * preferring the IMAP copy (IMAP rows are passed first and win on collision),
+ * sort newest-first by dateReceived, then apply `limit`.
+ */
+export function mergeMessages(imapRows, appleRows, limit) {
+    const byKey = new Map();
+    // IMAP first so its copy wins; AppleScript only fills keys IMAP didn't supply.
+    for (const r of imapRows) {
+        const k = dedupKey(r);
+        if (!byKey.has(k))
+            byKey.set(k, r);
+    }
+    for (const r of appleRows) {
+        const k = dedupKey(r);
+        if (!byKey.has(k))
+            byKey.set(k, r);
+    }
+    const merged = [...byKey.values()];
+    merged.sort((a, b) => dateEpoch(b) - dateEpoch(a)); // newest first
+    return limit >= 0 ? merged.slice(0, limit) : merged;
+}
+/** Gmail/Workspace IMAP host? Its `[Gmail]/All Mail` virtual mailbox is Gmail-only. */
+export function isGmailHost(host) {
+    return /(^|\.)gmail\.com$/i.test(host.trim());
+}
+/**
+ * Fan an IMAP message query out over EVERY configured IMAP account and return
+ * the concatenated structured rows (not yet merged with AppleScript, not yet
+ * limited — the caller merges + limits). `kind` picks the underlying query so
+ * the mailbox-default and unreadOnly semantics match the single-account path.
+ *
+ * Per-account failures are swallowed (logged) so one unreachable account doesn't
+ * sink the whole read; the returned `accountsQueried`/`accountsFailed` let the
+ * caller surface partial-coverage diagnostics.
+ */
+export async function fanOutImapMessages(args, kind, deps = {}, configs = resolveImapConfigs()) {
+    const rows = [];
+    const accountsQueried = [];
+    const accountsFailed = [];
+    for (const config of configs) {
+        // Default-mailbox resolution is PER-ACCOUNT: the single-account search default
+        // ("[Gmail]/All Mail") is Gmail-only, so fanning it out to a non-Gmail account
+        // (e.g. iCloud) makes that SELECT fail and the account silently drops from the
+        // merged results. When the caller pinned no mailbox, give Gmail hosts their
+        // All-Mail default (undefined → resolved downstream) and every other host a
+        // universal "INBOX". (limit is applied AFTER the cross-account merge so the
+        // global newest-N is correct even when one account dominates.)
+        const mailbox = args.mailbox ?? (isGmailHost(config.host) ? undefined : "INBOX");
+        const perAccountArgs = { ...args, account: undefined, mailbox };
+        try {
+            const res = kind === "search"
+                ? await imapSearchMessages(perAccountArgs, { ...deps, config })
+                : await imapListMessages(perAccountArgs, { ...deps, config });
+            rows.push(...res.messages);
+            accountsQueried.push(config.accountLabel);
+        }
+        catch (e) {
+            accountsFailed.push(config.accountLabel);
+            console.error(`IMAP fan-out failed for account "${config.accountLabel}": ${String(e)}`);
+        }
+    }
+    return { rows, accountsQueried, accountsFailed };
+}
+// ---------------------------------------------------------------------------
+// Account coverage + count partitioning (reads, get-unread-count, get-mail-stats)
+//
+// Coverage is decided per (config, Mail-account) PAIR by configMatchesAccount.
+// - Message-list reads use partitionAccountsForCounts to run AppleScript ONLY
+//   for accounts no IMAP config covers (IMAP fans out over the configs), so an
+//   all-IMAP user runs zero AppleScript and never depends on composite dedup.
+// - Count tools use planCountSources, which assigns each account EXACTLY ONE
+//   source (its matching config, else AppleScript) and adds any config that
+//   matched no account once — so even a heuristic MISS can't double-count.
+//
+// Matching is case-insensitive on the config's accountLabel/user vs. the Mail
+// account's name/email. accountLabel defaults to the login address and users
+// typically set it to the Mail.app account NAME, so checking both against both
+// catches the common setups (label=accountName, label=email, login=email).
+// ---------------------------------------------------------------------------
+/**
+ * Per-pair matcher: does this IMAP config correspond to this Mail.app account?
+ * Compared case-insensitively, the config's `accountLabel` AND `user` against the
+ * Mail account's `name` AND `email`. An empty email can't match (avoids
+ * `"" === ""` false positives). This is the single source of truth for coverage;
+ * everything else delegates here.
+ */
+export function configMatchesAccount(config, account) {
+    const name = account.name.trim().toLowerCase();
+    const email = (account.email ?? "").trim().toLowerCase();
+    const label = config.accountLabel.trim().toLowerCase();
+    const user = config.user.trim().toLowerCase();
+    return (label === name || (!!email && label === email) || user === name || (!!email && user === email));
+}
+/** True when ANY config matches this Mail account (delegates to the per-pair matcher). */
+export function isAccountCoveredByImap(account, configs) {
+    return configs.some((c) => configMatchesAccount(c, account));
+}
+/**
+ * Split Mail.app accounts into those covered by IMAP (counted via IMAP) and the
+ * rest (counted via AppleScript), so reads/counts skip the AppleScript scan for
+ * IMAP-covered accounts.
+ */
+export function partitionAccountsForCounts(accounts, configs) {
+    const imapCovered = [];
+    const appleScriptOnly = [];
+    for (const a of accounts) {
+        if (isAccountCoveredByImap(a, configs))
+            imapCovered.push(a);
+        else
+            appleScriptOnly.push(a);
+    }
+    return { imapCovered, appleScriptOnly };
+}
+/**
+ * Plan the count sources so NO account is double-counted even when the coverage
+ * heuristic mis-matches (the failure mode the naive `Σimap(all configs) +
+ * Σapple(uncovered)` had: a config that fails to match its Mail account lands in
+ * BOTH sums).
+ *
+ * Account-centric: walk the Mail.app accounts; each is counted via its FIRST
+ * matching config (IMAP) or, if none matches, via AppleScript. Then any IMAP
+ * config that matched NO Mail account (configured-but-not-present-in-Mail.app) is
+ * added once as an IMAP source. A config is consumed by at most one Mail account,
+ * so two Mail accounts can't both claim the same config and inflate the total.
+ */
+export function planCountSources(accounts, configs) {
+    const sources = [];
+    const usedConfigs = new Set();
+    for (const account of accounts) {
+        const match = configs.find((c) => !usedConfigs.has(c) && configMatchesAccount(c, account));
+        if (match) {
+            usedConfigs.add(match);
+            sources.push({ kind: "imap", config: match, label: account.name });
+        }
+        else {
+            sources.push({ kind: "applescript", account, label: account.name });
+        }
+    }
+    // IMAP accounts that exist in config but not in Mail.app — count them once.
+    for (const config of configs) {
+        if (!usedConfigs.has(config)) {
+            sources.push({ kind: "imap", config, label: config.accountLabel });
+        }
+    }
+    return sources;
+}
+/**
+ * Render the structured message rows into the human text block the read tools
+ * emit (`  - ID: … | date | subject (from: sender) [read|unread]`). Shared so the
+ * merged path matches the single-backend formatting. `showReadState` mirrors
+ * search/list (which show [read]) vs. plain list rows.
+ */
+export function formatMergedRows(rows, showReadState = true) {
+    return rows
+        .map((m) => {
+        const date = (() => {
+            const e = dateEpoch(m);
+            return e ? new Date(e).toLocaleDateString() : "";
+        })();
+        const subject = typeof m.subject === "string" ? m.subject : "(no subject)";
+        const sender = typeof m.sender === "string" ? m.sender : "(unknown)";
+        const state = showReadState ? ` [${m.isRead ? "read" : "unread"}]` : "";
+        return `  - ID: ${String(m.id)} | ${date} | ${subject} (from: ${sender})${state}`;
+    })
+        .join("\n");
+}

package/build/services/replyForward.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure helpers that turn an existing message (its raw RFC 5322 source plus the
+ * decoded plain-text body) into {@link SmtpSendOptions} for a **threaded reply**
+ * or a **forward** sent over SMTP.
+ *
+ * This is the 2.5.0 "prefer-direct" path: when SMTP is configured we send
+ * replies/forwards ourselves with correct `In-Reply-To`/`References` headers and
+ * a clean MIME body, instead of driving Mail.app's `reply`/`forward` AppleScript
+ * commands (which thread correctly but wrap the injected body in a `blockquote`
+ * on macOS 15+). Kept separate from {@link sendViaSmtp} so the addressing,
+ * subject-prefix, and quoting rules are unit-testable without a live SMTP server.
+ */
+import type { SmtpSendOptions } from "../services/smtpMailer.js";
+/** The subset of an original message's headers we need to reply/forward. */
+export interface OriginalHeaders {
+    /** Raw `Message-ID` including angle brackets, e.g. `<abc@host>`. */
+    messageId?: string;
+    /** Thread chain: every `<id>` from `References` + `In-Reply-To`, in order. */
+    references: string[];
+    /** `From` address(es), bare (no display name). */
+    from: string[];
+    /** `Reply-To` address(es), bare. Preferred over {@link from} for replies. */
+    replyTo: string[];
+    /** `To` address(es), bare. */
+    to: string[];
+    /** `Cc` address(es), bare. */
+    cc: string[];
+    /** `Subject`, unfolded and trimmed (no `Re:`/`Fwd:` normalization). */
+    subject: string;
+    /** `Date` header verbatim, for the reply attribution line. */
+    date?: string;
+}
+/**
+ * Pull bare email addresses out of a header value such as
+ * `"Alice <a@x.com>, bob@y.com"` → `["a@x.com", "bob@y.com"]`. Splits on commas
+ * (address lists are comma-separated) and unwraps `<...>` when present. Anything
+ * without an `@` is dropped, so group syntax / junk is ignored.
+ */
+export declare function extractAddresses(headerValue: string): string[];
+/**
+ * Parse the header block (everything before the first blank line) of a raw
+ * message. Continuation lines (folded headers, leading WSP) are unfolded, and
+ * header names are matched case-insensitively. Only the headers in
+ * {@link OriginalHeaders} are extracted.
+ */
+export declare function parseOriginalHeaders(raw: string): OriginalHeaders;
+/**
+ * Ensure `subject` carries `prefix` exactly once. Existing `Re:`/`Fwd:`/`Fw:`
+ * prefixes (any case) are treated as already-present so we never stack them.
+ */
+export declare function withSubjectPrefix(subject: string, prefix: "Re:" | "Fwd:"): string;
+/** Prefix every line of the original body with `> ` for the quoted reply block. */
+export declare function quoteBody(plainText: string): string;
+/**
+ * Build {@link SmtpSendOptions} for a threaded reply.
+ *
+ * - recipients: `Reply-To` if the original had one, else `From`; with
+ *   `replyAll`, the original `To`+`Cc` (minus our own addresses and the primary
+ *   recipients) become `Cc`.
+ * - subject: `Re: ` prepended unless already present.
+ * - threading: `In-Reply-To` = original `Message-ID`; `References` = original
+ *   chain + that `Message-ID`.
+ * - body: the new text, then an attribution line and the quoted original.
+ */
+export declare function buildReplyOptions(args: {
+    original: OriginalHeaders;
+    originalPlainText: string;
+    body: string;
+    replyAll: boolean;
+    /** Our own addresses, excluded from a reply-all recipient set. */
+    self: string[];
+    /** From override (defaults to the SMTP identity at send time when omitted). */
+    from?: string;
+}): SmtpSendOptions;
+/**
+ * Build {@link SmtpSendOptions} for a forward to new recipients. A forward
+ * starts a new thread, so no `In-Reply-To`/`References` are set — the win over
+ * the AppleScript path is a clean, un-wrapped MIME body.
+ */
+export declare function buildForwardOptions(args: {
+    original: OriginalHeaders;
+    originalPlainText: string;
+    to: string[];
+    body?: string;
+    from?: string;
+}): SmtpSendOptions;
+//# sourceMappingURL=replyForward.d.ts.map

package/build/services/replyForward.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replyForward.d.ts","sourceRoot":"","sources":["../../src/services/replyForward.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,kDAAkD;IAClD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8BAA8B;IAC9B,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,8BAA8B;IAC9B,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAS9D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAkCjE;AAgBD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAIjF;AAED,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,QAAQ,EAAE,eAAe,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,eAAe,CAmClB;AAQD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,QAAQ,EAAE,eAAe,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,eAAe,CAsBlB"}

package/build/services/replyForward.js

@@ -0,0 +1,150 @@
+/**
+ * Pull bare email addresses out of a header value such as
+ * `"Alice <a@x.com>, bob@y.com"` → `["a@x.com", "bob@y.com"]`. Splits on commas
+ * (address lists are comma-separated) and unwraps `<...>` when present. Anything
+ * without an `@` is dropped, so group syntax / junk is ignored.
+ */
+export function extractAddresses(headerValue) {
+    if (!headerValue.trim())
+        return [];
+    return headerValue
+        .split(",")
+        .map((part) => {
+        const angle = part.match(/<([^>]+)>/);
+        return (angle ? angle[1] : part).trim();
+    })
+        .filter((addr) => addr.includes("@"));
+}
+/**
+ * Parse the header block (everything before the first blank line) of a raw
+ * message. Continuation lines (folded headers, leading WSP) are unfolded, and
+ * header names are matched case-insensitively. Only the headers in
+ * {@link OriginalHeaders} are extracted.
+ */
+export function parseOriginalHeaders(raw) {
+    const headerBlock = raw.split(/\r?\n\r?\n/)[0] ?? "";
+    // Unfold: any line starting with a space/tab continues the previous header.
+    const lines = [];
+    for (const line of headerBlock.split(/\r?\n/)) {
+        if (/^[ \t]/.test(line) && lines.length > 0) {
+            lines[lines.length - 1] += " " + line.trim();
+        }
+        else {
+            lines.push(line);
+        }
+    }
+    const get = (name) => {
+        const prefix = `${name.toLowerCase()}:`;
+        const found = lines.find((l) => l.toLowerCase().startsWith(prefix));
+        return found ? found.slice(found.indexOf(":") + 1).trim() : undefined;
+    };
+    const rawMessageId = get("Message-ID");
+    const messageId = rawMessageId?.match(/<[^>]+>/)?.[0] ?? rawMessageId ?? undefined;
+    const references = `${get("References") ?? ""} ${get("In-Reply-To") ?? ""}`.match(/<[^>]+>/g) ?? [];
+    return {
+        messageId,
+        references,
+        from: extractAddresses(get("From") ?? ""),
+        replyTo: extractAddresses(get("Reply-To") ?? ""),
+        to: extractAddresses(get("To") ?? ""),
+        cc: extractAddresses(get("Cc") ?? ""),
+        subject: get("Subject") ?? "",
+        date: get("Date"),
+    };
+}
+/** Case-insensitive de-dupe that preserves first-seen order and casing. */
+function dedupe(addrs) {
+    const seen = new Set();
+    const out = [];
+    for (const a of addrs) {
+        const k = a.toLowerCase();
+        if (!seen.has(k)) {
+            seen.add(k);
+            out.push(a);
+        }
+    }
+    return out;
+}
+/**
+ * Ensure `subject` carries `prefix` exactly once. Existing `Re:`/`Fwd:`/`Fw:`
+ * prefixes (any case) are treated as already-present so we never stack them.
+ */
+export function withSubjectPrefix(subject, prefix) {
+    const s = subject.trim();
+    const present = prefix === "Re:" ? /^re:/i : /^(fwd?|fw):/i;
+    return present.test(s) ? s : `${prefix} ${s}`;
+}
+/** Prefix every line of the original body with `> ` for the quoted reply block. */
+export function quoteBody(plainText) {
+    return plainText
+        .replace(/\s+$/, "")
+        .split(/\r?\n/)
+        .map((l) => (l ? `> ${l}` : ">"))
+        .join("\n");
+}
+/**
+ * Build {@link SmtpSendOptions} for a threaded reply.
+ *
+ * - recipients: `Reply-To` if the original had one, else `From`; with
+ *   `replyAll`, the original `To`+`Cc` (minus our own addresses and the primary
+ *   recipients) become `Cc`.
+ * - subject: `Re: ` prepended unless already present.
+ * - threading: `In-Reply-To` = original `Message-ID`; `References` = original
+ *   chain + that `Message-ID`.
+ * - body: the new text, then an attribution line and the quoted original.
+ */
+export function buildReplyOptions(args) {
+    const { original, originalPlainText, body, replyAll, self, from } = args;
+    const selfSet = new Set(self.filter(Boolean).map((s) => s.toLowerCase()));
+    const to = dedupe((original.replyTo.length ? original.replyTo : original.from).filter(Boolean));
+    const toSet = new Set(to.map((t) => t.toLowerCase()));
+    let cc;
+    if (replyAll) {
+        const extra = dedupe([...original.to, ...original.cc].filter((a) => !selfSet.has(a.toLowerCase()) && !toSet.has(a.toLowerCase())));
+        cc = extra.length ? extra : undefined;
+    }
+    const attribution = buildAttribution(original);
+    const quoted = originalPlainText.trim()
+        ? `\n\n${attribution}${quoteBody(originalPlainText)}`
+        : "";
+    const references = dedupe(original.messageId ? [...original.references, original.messageId] : original.references);
+    return {
+        to,
+        cc,
+        subject: withSubjectPrefix(original.subject, "Re:"),
+        body: `${body}${quoted}`,
+        inReplyTo: original.messageId,
+        references: references.length ? references : undefined,
+        from,
+    };
+}
+/** "On <date>, <sender> wrote:\n" — omits the date clause when unknown. */
+function buildAttribution(original) {
+    const who = original.from[0] ?? original.replyTo[0] ?? "the sender";
+    return original.date ? `On ${original.date}, ${who} wrote:\n` : `${who} wrote:\n`;
+}
+/**
+ * Build {@link SmtpSendOptions} for a forward to new recipients. A forward
+ * starts a new thread, so no `In-Reply-To`/`References` are set — the win over
+ * the AppleScript path is a clean, un-wrapped MIME body.
+ */
+export function buildForwardOptions(args) {
+    const { original, originalPlainText, to, body, from } = args;
+    const headerBlock = [
+        "---------- Forwarded message ----------",
+        original.from.length ? `From: ${original.from.join(", ")}` : "",
+        original.date ? `Date: ${original.date}` : "",
+        `Subject: ${original.subject}`,
+        original.to.length ? `To: ${original.to.join(", ")}` : "",
+        original.cc.length ? `Cc: ${original.cc.join(", ")}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const prefix = body?.trim() ? `${body}\n\n` : "";
+    return {
+        to: dedupe(to),
+        subject: withSubjectPrefix(original.subject, "Fwd:"),
+        body: `${prefix}${headerBlock}\n\n${originalPlainText}`,
+        from,
+    };
+}

package/build/services/smtpMailer.d.ts

@@ -36,6 +36,17 @@ export interface SmtpSendOptions {
      * plain-text clients still get a clean fallback.
      */
     htmlBody?: string;
+    /**
+     * RFC 5322 threading (2.5.0): the message this is replying to — emitted as the
+     * `In-Reply-To` header so SMTP replies/forwards thread correctly in Gmail and
+     * other clients. Pass the original message's `Message-ID`.
+     */
+    inReplyTo?: string;
+    /**
+     * RFC 5322 threading (2.5.0): the `References` chain — the original message's
+     * existing `References` plus its `Message-ID`. nodemailer accepts an array.
+     */
+    references?: string[];
 }
 /** Resolved SMTP connection configuration. */
 export interface SmtpConfig {
@@ -114,4 +125,36 @@ export declare function resolveSmtpConfig(env?: NodeJS.ProcessEnv): SmtpConfig;
  * a transporter factory only in tests.
  */
 export declare function sendViaSmtp(opts: SmtpSendOptions, config?: SmtpConfig, createTransport?: typeof nodemailer.createTransport): Promise<SmtpSendResult>;
+/** One recipient of a mail-merge batch (mirrors the AppleScript serial path). */
+export interface SerialSmtpRecipient {
+    email: string;
+    variables: Record<string, string>;
+}
+/** Per-recipient outcome of a serial SMTP send. */
+export interface SerialSmtpResult {
+    email: string;
+    success: boolean;
+    error?: string;
+}
+/**
+ * Replace every `{{Key}}` token in `template` with the matching value from
+ * `variables`. Keys are escaped so regex metacharacters in a key are literal.
+ * Mirrors the substitution in {@link AppleMailManager.sendSerialEmail} so the
+ * two transports personalize identically.
+ */
+export declare function applyPlaceholders(template: string, variables: Record<string, string>): string;
+/**
+ * Send a personalized mail-merge batch over SMTP — one individual message per
+ * recipient (recipients never see each other), with `{{Key}}` placeholders in
+ * the subject/body replaced per recipient. Returns a per-recipient result list;
+ * a single recipient's failure does not abort the batch.
+ *
+ * `opts.send` and `opts.sleep` are injectable for tests (no real SMTP / no real
+ * delay). The default `sleep` waits `delayMs` (clamped 0–10000) between sends.
+ */
+export declare function sendSerialViaSmtp(recipients: SerialSmtpRecipient[], subject: string, body: string, config: SmtpConfig, opts?: {
+    delayMs?: number;
+    send?: typeof sendViaSmtp;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<SerialSmtpResult[]>;
 //# sourceMappingURL=smtpMailer.d.ts.map

package/build/services/smtpMailer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"smtpMailer.d.ts","sourceRoot":"","sources":["../../src/services/smtpMailer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,UAAU,MAAM,YAAY,CAAC;AAIpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;CASX,CAAC;AAEX;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,EAC7C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,UAAU,GAAE,OAA4B,GACvC,OAAO,CAMT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAcpF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,UAAU,CA8ClF;AAqBD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,EACrB,MAAM,CAAC,EAAE,UAAU,EACnB,eAAe,GAAE,OAAO,UAAU,CAAC,eAA4C,GAC9E,OAAO,CAAC,cAAc,CAAC,CA6CzB"}
+{"version":3,"file":"smtpMailer.d.ts","sourceRoot":"","sources":["../../src/services/smtpMailer.ts"],"names":[],"mappings":"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"}

package/build/services/smtpMailer.js

@@ -198,6 +198,9 @@ export async function sendViaSmtp(opts, config, createTransport = nodemailer.cre
             // When present, nodemailer emits multipart/alternative (text + html).
             html,
             attachments,
+            // RFC 5322 threading for SMTP replies/forwards (2.5.0).
+            inReplyTo: opts.inReplyTo?.trim() || undefined,
+            references: opts.references?.length ? opts.references : undefined,
         });
         return { success: true, messageId: info.messageId };
     }
@@ -211,3 +214,55 @@ export async function sendViaSmtp(opts, config, createTransport = nodemailer.cre
         transporter.close();
     }
 }
+/**
+ * Replace every `{{Key}}` token in `template` with the matching value from
+ * `variables`. Keys are escaped so regex metacharacters in a key are literal.
+ * Mirrors the substitution in {@link AppleMailManager.sendSerialEmail} so the
+ * two transports personalize identically.
+ */
+export function applyPlaceholders(template, variables) {
+    let out = template;
+    for (const [key, value] of Object.entries(variables)) {
+        const safeKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        out = out.replace(new RegExp(`\\{\\{${safeKey}\\}\\}`, "g"), value);
+    }
+    return out;
+}
+/**
+ * Send a personalized mail-merge batch over SMTP — one individual message per
+ * recipient (recipients never see each other), with `{{Key}}` placeholders in
+ * the subject/body replaced per recipient. Returns a per-recipient result list;
+ * a single recipient's failure does not abort the batch.
+ *
+ * `opts.send` and `opts.sleep` are injectable for tests (no real SMTP / no real
+ * delay). The default `sleep` waits `delayMs` (clamped 0–10000) between sends.
+ */
+export async function sendSerialViaSmtp(recipients, subject, body, config, opts = {}) {
+    const send = opts.send ?? sendViaSmtp;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const delay = Math.min(Math.max(opts.delayMs ?? 500, 0), 10000);
+    const results = [];
+    for (let i = 0; i < recipients.length; i++) {
+        const r = recipients[i];
+        try {
+            const res = await send({
+                to: [r.email],
+                subject: applyPlaceholders(subject, r.variables),
+                body: applyPlaceholders(body, r.variables),
+                from: config.from,
+            }, config);
+            results.push({ email: r.email, success: res.success, error: res.error });
+        }
+        catch (error) {
+            results.push({
+                email: r.email,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        if (delay > 0 && i < recipients.length - 1) {
+            await sleep(delay);
+        }
+    }
+    return results;
+}

package/package.json

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