apple-mail-mcp 2.3.0 → 2.4.0

package/README.md

@@ -6,6 +6,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that e
 [![npm downloads](https://img.shields.io/npm/dm/apple-mail-mcp)](https://www.npmjs.com/package/apple-mail-mcp)
 [![node](https://img.shields.io/node/v/apple-mail-mcp)](https://www.npmjs.com/package/apple-mail-mcp)
 [![CI](https://github.com/sweetrb/apple-mail-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sweetrb/apple-mail-mcp/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/sweetrb/apple-mail-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/sweetrb/apple-mail-mcp)
 [![platform: macOS](https://img.shields.io/badge/platform-macOS-111?logo=apple&logoColor=white)](https://www.apple.com/macos/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io)
@@ -255,7 +256,7 @@ Send a new email immediately.
 | `bcc` | string[] | No | BCC recipients |
 | `account` | string | No | Send from specific account (with `transport: "smtp"`, overrides the From address) |
 | `attachments` | (string \| {filename, contentBase64})[] | No | Up to 20 attachments: absolute file paths (e.g., `"/Users/me/report.pdf"`) and/or inline `{filename, contentBase64}` objects for content not on disk |
-| `transport` | `"applescript"` \| `"smtp"` | No | Send transport (default `"applescript"`). Use `"smtp"` to send clean MIME directly, avoiding the macOS 15+ Mail.app `<blockquote>` wrapping — see [SMTP transport](#smtp-transport) |
+| `transport` | `"applescript"` \| `"smtp"` | No | Send transport. If omitted, **SMTP is used automatically when configured** (otherwise AppleScript). Pass `"smtp"` to require clean MIME, or `"applescript"` to force the Mail.app path — see [SMTP transport](#smtp-transport) |
 
 **Example:**
 ```json
@@ -274,8 +275,25 @@ On macOS 15+ (Sequoia/Tahoe), Mail.app wraps any AppleScript-injected body in
 `<blockquote type="cite">` under the `Apple-Mail-URLShareWrapperClass` template,
 so emails sent through the default `applescript` transport render to recipients
 as if they were quoted/forwarded (Apple radar **FB11734014**, open since
-Ventura). Passing `transport: "smtp"` bypasses Mail.app entirely and submits
-clean MIME via SMTP.
+Ventura). The SMTP transport bypasses Mail.app entirely and submits clean MIME
+directly. **Once SMTP is configured, `send-email` uses it automatically** (no
+need to pass `transport` per call); pass `transport: "applescript"` to force the
+Mail.app path.
+
+Two differences to know when SMTP is auto-preferred:
+
+- **No Sent-folder copy.** SMTP submission does not file the message in Mail.app's
+  Sent mailbox (the server's own "save to Sent" may, depending on provider). Use
+  `transport: "applescript"` if you need the local Sent copy.
+- **`account` is a From override, not account selection.** Over SMTP, `account`
+  is used as the From address only when it is an email address; a Mail.app
+  account *label* (e.g. `"Work"`) can't select an account over SMTP, so a call
+  that passes one is left on the AppleScript path automatically. To force
+  account selection, pass `transport: "applescript"` explicitly.
+
+Both plain-text and HTML bodies are supported — over SMTP an HTML body (CLI
+`--html-body-file`) is sent as `multipart/alternative` with the plain-text
+fallback.
 
 Configure SMTP via environment variables on the MCP server. The password is
 read from the macOS **Keychain** by default, so no secret goes in config:
@@ -292,23 +310,48 @@ read from the macOS **Keychain** by default, so no secret goes in config:
 | `APPLE_MAIL_MCP_SMTP_KEYCHAIN_ACCOUNT` | No | = user | Keychain item account |
 
 Store the password in the Keychain once (an app-specific password for Gmail/
-iCloud), e.g.:
+iCloud). A generic-password item with an explicit service name keeps it from
+colliding with the system mail account password, and matches
+`APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE`:
 
 ```bash
+# Fastmail (Keychain service defaults to the host)
 security add-internet-password -s smtp.fastmail.com -a you@example.com -w
+
+# Gmail / Google Workspace, using a dedicated Keychain service name:
+#   APPLE_MAIL_MCP_SMTP_HOST=smtp.gmail.com
+#   APPLE_MAIL_MCP_SMTP_USER=you@gmail.com
+#   APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE=apple-mail-mcp-smtp
+security add-generic-password -s apple-mail-mcp-smtp -a you@gmail.com -w
 ```
 
-Then send:
+Once the env vars are set, a plain `send-email` (no `transport`) already goes
+out clean:
 ```json
 {
   "to": ["colleague@company.com"],
   "subject": "Standings",
-  "body": "Plain body — no blockquote wrapping.",
-  "transport": "smtp"
+  "body": "Plain body — no blockquote wrapping."
 }
 ```
 
-The default `applescript` transport is unchanged; SMTP is opt-in per call.
+###### `apple-mail-send` CLI (no MCP server required)
+
+The package also installs an `apple-mail-send` binary — a standalone CLI over the
+same SMTP path, for cron jobs, scheduled tasks, and scripts that can't run an MCP
+session. It reads the identical `APPLE_MAIL_MCP_SMTP_*` env + Keychain config:
+
+```bash
+apple-mail-send \
+  --from you@example.com --to colleague@company.com \
+  --subject "Standings" --body-file /tmp/body.txt \
+  [--html-body-file /tmp/body.html] [--attach /tmp/report.pdf]
+```
+
+Repeatable `--to`/`--cc`/`--bcc`/`--attach`; an `--html-body-file` is sent as a
+`multipart/alternative` alongside the plain `--body-file`. Exit codes follow
+`sysexits.h`: `0` success, `64` usage error, `66` unreadable body file, `78`
+SMTP not configured.
 
 ##### IMAP backend — opt-in
 

package/build/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { sendViaSmtp, resolveSmtpConfig } from "./services/smtpMailer.js";
+/** sysexits.h codes used so callers can distinguish failure modes. */
+export declare const EX_USAGE = 64;
+export declare const EX_NOINPUT = 66;
+export declare const EX_CONFIG = 78;
+/** Injectable dependencies, defaulted to the real implementations. */
+export interface CliDeps {
+    send?: typeof sendViaSmtp;
+    resolveConfig?: typeof resolveSmtpConfig;
+    readTextFile?: (path: string) => string;
+    stdout?: (line: string) => void;
+    stderr?: (line: string) => void;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Parses argv, sends the email, and returns a process exit code. Pure with
+ * respect to its deps (no direct process/console access) so it can be unit
+ * tested without the network or Keychain.
+ *
+ * @param argv - arguments AFTER `node cli.js` (i.e. `process.argv.slice(2)`)
+ */
+export declare function runCli(argv: string[], deps?: CliDeps): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/build/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAyBA,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAY,MAAM,0BAA0B,CAAC;AAGpF,sEAAsE;AACtE,eAAO,MAAM,QAAQ,KAAK,CAAC;AAC3B,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,SAAS,KAAK,CAAC;AAqB5B,sEAAsE;AACtE,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,EAAE,OAAO,WAAW,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,iBAAiB,CAAC;IACzC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACxC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,OAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAwGhF"}

package/build/cli.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * `apple-mail-send` — standalone clean-SMTP email CLI.
+ *
+ * A thin command-line front end over {@link sendViaSmtp} so scheduled tasks,
+ * cron jobs, and other scripts can send clean MIME (no Mail.app blockquote
+ * wrapping, issue #12) WITHOUT a running MCP server. It reuses the exact same
+ * SMTP config resolution as the MCP `send-email` tool — env vars first, then the
+ * macOS Keychain (see the README "SMTP transport" section).
+ *
+ * The flag surface intentionally mirrors the legacy nhl-bracket-tracker
+ * `send_email.py` (--from/--to/--cc/--bcc/--subject/--body-file/
+ * --html-body-file/--attach) and its exit codes (78 = EX_CONFIG when SMTP is
+ * not configured) so callers can drop this in as a replacement.
+ *
+ * Usage:
+ *   apple-mail-send --from me@example.com --to you@example.com \
+ *     --subject "Hi" --body-file /tmp/body.txt \
+ *     [--html-body-file /tmp/body.html] [--attach /tmp/report.pdf]
+ *
+ * @module cli
+ */
+import { readFileSync, realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { parseArgs } from "util";
+import { sendViaSmtp, resolveSmtpConfig, SMTP_ENV } from "./services/smtpMailer.js";
+/** sysexits.h codes used so callers can distinguish failure modes. */
+export const EX_USAGE = 64;
+export const EX_NOINPUT = 66;
+export const EX_CONFIG = 78;
+const USAGE = `apple-mail-send — send a clean email via SMTP (no Mail.app blockquote wrapping).
+
+Required:
+  --from <addr>         Sender address (must be allowed by the SMTP server)
+  --to <addr>           Recipient (repeatable)
+  --subject <text>      Subject line
+  --body-file <path>    UTF-8 file with the plain-text body
+
+Optional:
+  --cc <addr>           CC recipient (repeatable)
+  --bcc <addr>          BCC recipient (repeatable)
+  --html-body-file <p>  UTF-8 file with an HTML alternative body (sends
+                        multipart/alternative)
+  --attach <path>       Absolute path to a file to attach (repeatable)
+  --help                Show this help
+
+SMTP connection comes from ${SMTP_ENV.host} / ${SMTP_ENV.user} (+ password via
+${SMTP_ENV.password} or the macOS Keychain). See the README "SMTP transport".`;
+/**
+ * Parses argv, sends the email, and returns a process exit code. Pure with
+ * respect to its deps (no direct process/console access) so it can be unit
+ * tested without the network or Keychain.
+ *
+ * @param argv - arguments AFTER `node cli.js` (i.e. `process.argv.slice(2)`)
+ */
+export async function runCli(argv, deps = {}) {
+    const send = deps.send ?? sendViaSmtp;
+    const resolveConfig = deps.resolveConfig ?? resolveSmtpConfig;
+    const readTextFile = deps.readTextFile ?? ((p) => readFileSync(p, "utf8"));
+    const out = deps.stdout ?? ((l) => console.log(l));
+    const err = deps.stderr ?? ((l) => console.error(l));
+    const env = deps.env ?? process.env;
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: argv,
+            options: {
+                from: { type: "string" },
+                to: { type: "string", multiple: true },
+                cc: { type: "string", multiple: true },
+                bcc: { type: "string", multiple: true },
+                subject: { type: "string" },
+                "body-file": { type: "string" },
+                "html-body-file": { type: "string" },
+                attach: { type: "string", multiple: true },
+                help: { type: "boolean" },
+            },
+            allowPositionals: false,
+        }));
+    }
+    catch (e) {
+        err(e instanceof Error ? e.message : String(e));
+        err(USAGE);
+        return EX_USAGE;
+    }
+    if (values.help) {
+        out(USAGE);
+        return 0;
+    }
+    const missing = [];
+    if (!values.from)
+        missing.push("--from");
+    if (!values.to || values.to.length === 0)
+        missing.push("--to");
+    if (!values.subject)
+        missing.push("--subject");
+    if (!values["body-file"])
+        missing.push("--body-file");
+    if (missing.length > 0) {
+        err(`Missing required argument(s): ${missing.join(", ")}`);
+        err(USAGE);
+        return EX_USAGE;
+    }
+    // Resolve the full SMTP config up front (host/user/port + Keychain password)
+    // so a missing password counts as EX_CONFIG (78) — the same actionable
+    // "needs setup" signal as a missing host/user — rather than a generic failure.
+    let config;
+    try {
+        config = resolveConfig(env);
+    }
+    catch (e) {
+        err(e instanceof Error ? e.message : String(e));
+        err(`See the README "SMTP transport" section.`);
+        return EX_CONFIG;
+    }
+    let body;
+    let htmlBody;
+    try {
+        body = readTextFile(values["body-file"]);
+        if (values["html-body-file"])
+            htmlBody = readTextFile(values["html-body-file"]);
+    }
+    catch (e) {
+        err(`Could not read body file: ${e instanceof Error ? e.message : String(e)}`);
+        return EX_NOINPUT;
+    }
+    const attachments = values.attach?.length
+        ? values.attach
+        : undefined;
+    const result = await send({
+        from: values.from,
+        to: values.to,
+        cc: values.cc,
+        bcc: values.bcc,
+        subject: values.subject,
+        body,
+        htmlBody,
+        attachments,
+    }, config);
+    if (!result.success) {
+        err(result.error ?? "SMTP send failed.");
+        return 1;
+    }
+    out(`sent to ${values.to.join(", ")} from ${values.from}`);
+    return 0;
+}
+// Entry point when invoked directly (not when imported by tests). Resolve both
+// sides through the filesystem so it still matches when launched via the npm
+// `bin` symlink (argv[1] is the symlink; import.meta.url is the real build file).
+function isInvokedDirectly() {
+    if (typeof process === "undefined" || !process.argv?.[1])
+        return false;
+    try {
+        return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isInvokedDirectly()) {
+    runCli(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+        console.error(e instanceof Error ? (e.stack ?? e.message) : String(e));
+        process.exit(1);
+    });
+}

package/build/index.js

@@ -26,7 +26,7 @@ import { z } from "zod";
 import { AppleMailManager, isPathWithinAllowedRoots } from "./services/appleMailManager.js";
 import { writeFileSync } from "fs";
 import { resolve as resolvePath, join as joinPath } from "path";
-import { sendViaSmtp } from "./services/smtpMailer.js";
+import { sendViaSmtp, shouldUseSmtp } from "./services/smtpMailer.js";
 import { isImapAccount, resolveImapConfigs, imapSearchMessages, imapListMessages, imapUnreadCount, imapListMailboxes, imapMailStats, imapListAttachments, imapFetchAttachment, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete, imapBatchMove, imapThread, imapCreateMailbox, imapDeleteMailbox, imapRenameMailbox, imapGetMessage, imapMarkRead, imapMarkUnread, imapFlagMessage, imapUnflagMessage, imapMoveMessageById, imapDeleteMessageById, } from "./services/imapClient.js";
 import { successResponse, errorResponse, partialCoverageBlock, withErrorHandling, messageSummary, } from "./tools/respond.js";
 import { routeMessage } from "./services/messageRouter.js";
@@ -413,9 +413,11 @@ server.registerTool("send-email", {
         transport: z
             .enum(["applescript", "smtp"])
             .optional()
-            .describe("Send transport. 'applescript' (default) sends through Mail.app. " +
-            "'smtp' submits clean MIME directly via SMTP, avoiding the macOS 15+ " +
-            "Mail.app <blockquote> wrapping (issue #12); requires APPLE_MAIL_MCP_SMTP_* env config."),
+            .describe("Send transport. 'smtp' submits clean MIME directly via SMTP, avoiding " +
+            "the macOS 15+ Mail.app <blockquote> wrapping (issue #12); requires " +
+            "APPLE_MAIL_MCP_SMTP_* env config. 'applescript' sends through Mail.app. " +
+            "If omitted, SMTP is used automatically when APPLE_MAIL_MCP_SMTP_* is " +
+            "configured, otherwise AppleScript."),
     },
     outputSchema: {
         ok: z.boolean().optional(),
@@ -426,8 +428,17 @@ server.registerTool("send-email", {
 }, withErrorHandling(async ({ to, subject, body, cc, bcc, account, attachments, transport }) => {
     const attachInfo = attachments?.length ? ` with ${attachments.length} attachment(s)` : "";
     const attachmentCount = attachments?.length ?? 0;
-    if (transport === "smtp") {
-        const result = await sendViaSmtp({ to, subject, body, cc, bcc, from: account, attachments });
+    // Prefer SMTP when explicitly requested, or automatically when it is
+    // configured and no transport was specified — except when a non-email
+    // `account` label requests Mail.app account selection (see shouldUseSmtp).
+    // Explicit transport:"applescript" always forces the Mail.app path.
+    if (shouldUseSmtp(transport, account)) {
+        // `account` is a Mail.app account label for the AppleScript path; for SMTP
+        // it only makes sense as a From override when it is an actual address.
+        // A bare label (only possible here via explicit transport:"smtp") must not
+        // corrupt the From — fall back to the configured SMTP From in that case.
+        const smtpFrom = account?.includes("@") ? account : undefined;
+        const result = await sendViaSmtp({ to, subject, body, cc, bcc, from: smtpFrom, attachments });
         if (!result.success) {
             return errorResponse(result.error ?? "Failed to send email via SMTP.");
         }

package/build/services/smtpMailer.d.ts

@@ -9,8 +9,9 @@
  *
  * Connection settings come from environment variables; the password is read
  * from the macOS Keychain via the `security` CLI by default so no secret is
- * ever placed in config. AppleScript remains the default transport — SMTP is
- * opt-in per call (`transport: "smtp"`).
+ * ever placed in config. When SMTP is configured, `send-email` auto-prefers it
+ * over AppleScript (opt out per call with `transport: "applescript"`); see
+ * {@link shouldUseSmtp}.
  *
  * @module services/smtpMailer
  */
@@ -20,6 +21,7 @@ import type { AttachmentInput } from "../types.js";
 export interface SmtpSendOptions {
     to: string[];
     subject: string;
+    /** Plain-text body. Always sent as the text/plain part. */
     body: string;
     cc?: string[];
     bcc?: string[];
@@ -27,6 +29,13 @@ export interface SmtpSendOptions {
     from?: string;
     /** Files to attach: absolute paths and/or inline base64 content (B4). */
     attachments?: AttachmentInput[];
+    /**
+     * Optional HTML body. When provided, the message is sent as
+     * multipart/alternative ({@link SmtpSendOptions.body} as the text/plain part,
+     * this as the text/html part) so clients pick the richer rendering while
+     * plain-text clients still get a clean fallback.
+     */
+    htmlBody?: string;
 }
 /** Resolved SMTP connection configuration. */
 export interface SmtpConfig {
@@ -57,6 +66,28 @@ export declare const SMTP_ENV: {
     readonly keychainService: "APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE";
     readonly keychainAccount: "APPLE_MAIL_MCP_SMTP_KEYCHAIN_ACCOUNT";
 };
+/**
+ * Cheap check for whether the SMTP transport is configured at all, i.e. the two
+ * required settings ({@link SMTP_ENV.host} and {@link SMTP_ENV.user}) are
+ * present. Used to auto-prefer SMTP over AppleScript when no transport is
+ * explicitly requested, and by `doctor`. Does NOT touch the Keychain or verify
+ * the password — a misconfigured password still surfaces a clear error at send
+ * time via {@link resolveSmtpConfig}.
+ */
+export declare function isSmtpConfigured(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Decides whether `send-email` should use the SMTP transport for this call.
+ *
+ * - explicit `"smtp"` → always SMTP (config errors surface, no fallback);
+ * - explicit `"applescript"` → always the Mail.app path;
+ * - omitted → SMTP when configured, **except** when a non-email `account` label
+ *   (a Mail.app account name such as `"Work"`) is supplied. That requests
+ *   account-based sending, which only the AppleScript path can do, so we honor
+ *   the caller's intent instead of silently switching their account. An
+ *   `account` that is an email address is treated as a From override and does
+ *   not block SMTP.
+ */
+export declare function shouldUseSmtp(transport: "applescript" | "smtp" | undefined, account: string | undefined, configured?: boolean): boolean;
 /**
  * Reads a password from the macOS login Keychain via the `security` CLI.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"smtpMailer.d.ts","sourceRoot":"","sources":["../../src/services/smtpMailer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;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,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;CACjC;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;;;;;;;;;;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,CAyCzB"}
+{"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"}

package/build/services/smtpMailer.js

@@ -9,8 +9,9 @@
  *
  * Connection settings come from environment variables; the password is read
  * from the macOS Keychain via the `security` CLI by default so no secret is
- * ever placed in config. AppleScript remains the default transport — SMTP is
- * opt-in per call (`transport: "smtp"`).
+ * ever placed in config. When SMTP is configured, `send-email` auto-prefers it
+ * over AppleScript (opt out per call with `transport: "applescript"`); see
+ * {@link shouldUseSmtp}.
  *
  * @module services/smtpMailer
  */
@@ -32,6 +33,39 @@ export const SMTP_ENV = {
     keychainService: "APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE",
     keychainAccount: "APPLE_MAIL_MCP_SMTP_KEYCHAIN_ACCOUNT",
 };
+/**
+ * Cheap check for whether the SMTP transport is configured at all, i.e. the two
+ * required settings ({@link SMTP_ENV.host} and {@link SMTP_ENV.user}) are
+ * present. Used to auto-prefer SMTP over AppleScript when no transport is
+ * explicitly requested, and by `doctor`. Does NOT touch the Keychain or verify
+ * the password — a misconfigured password still surfaces a clear error at send
+ * time via {@link resolveSmtpConfig}.
+ */
+export function isSmtpConfigured(env = process.env) {
+    return Boolean(env[SMTP_ENV.host]?.trim() && env[SMTP_ENV.user]?.trim());
+}
+/**
+ * Decides whether `send-email` should use the SMTP transport for this call.
+ *
+ * - explicit `"smtp"` → always SMTP (config errors surface, no fallback);
+ * - explicit `"applescript"` → always the Mail.app path;
+ * - omitted → SMTP when configured, **except** when a non-email `account` label
+ *   (a Mail.app account name such as `"Work"`) is supplied. That requests
+ *   account-based sending, which only the AppleScript path can do, so we honor
+ *   the caller's intent instead of silently switching their account. An
+ *   `account` that is an email address is treated as a From override and does
+ *   not block SMTP.
+ */
+export function shouldUseSmtp(transport, account, configured = isSmtpConfigured()) {
+    if (transport === "smtp")
+        return true;
+    if (transport === "applescript")
+        return false;
+    if (!configured)
+        return false;
+    const isAccountLabel = Boolean(account && !account.includes("@"));
+    return !isAccountLabel;
+}
 /**
  * Reads a password from the macOS login Keychain via the `security` CLI.
  *
@@ -152,6 +186,7 @@ export async function sendViaSmtp(opts, config, createTransport = nodemailer.cre
         secure: cfg.secure,
         auth: { user: cfg.user, pass: cfg.pass },
     });
+    const html = opts.htmlBody?.trim() ? opts.htmlBody : undefined;
     try {
         const info = await transporter.sendMail({
             from: opts.from?.trim() || cfg.from,
@@ -160,6 +195,8 @@ export async function sendViaSmtp(opts, config, createTransport = nodemailer.cre
             bcc: opts.bcc,
             subject: opts.subject,
             text: opts.body,
+            // When present, nodemailer emits multipart/alternative (text + html).
+            html,
             attachments,
         });
         return { success: true, messageId: info.messageId };

package/build/tools/doctor.js

@@ -1,5 +1,5 @@
 import { imapHealthCheck, IMAP_ENV, listImapAccountLabels } from "../services/imapClient.js";
-import { SMTP_ENV } from "../services/smtpMailer.js";
+import { SMTP_ENV, isSmtpConfigured } from "../services/smtpMailer.js";
 export async function runDoctor(mailManager) {
     const checks = [];
     // 1. Mail.app reachability + Automation permission (existing health check).
@@ -56,10 +56,10 @@ export async function runDoctor(mailManager) {
     const smtpHost = process.env[SMTP_ENV.host]?.trim();
     checks.push({
         name: "SMTP transport",
-        status: smtpHost ? "ok" : "warn",
-        detail: smtpHost
-            ? `configured (${smtpHost}); send-email transport:"smtp" is available`
-            : `not configured — send-email uses AppleScript (subject to macOS 15+ blockquote wrapping). Set ${SMTP_ENV.host} to enable.`,
+        status: isSmtpConfigured() ? "ok" : "warn",
+        detail: isSmtpConfigured()
+            ? `configured (${smtpHost}); send-email auto-prefers clean SMTP (no Mail.app Sent-folder copy; a non-email "account" label still routes to AppleScript). Pass transport:"applescript" to force Mail.app. The apple-mail-send CLI is also available.`
+            : `not configured — send-email uses AppleScript (subject to macOS 15+ blockquote wrapping). Set ${SMTP_ENV.host} and ${SMTP_ENV.user} (+ password via Keychain) to enable.`,
     });
     const healthy = !checks.some((c) => c.status === "fail");
     return { healthy, checks };

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.3.0",
+  "version": "2.4.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",
   "types": "build/index.d.ts",
   "bin": {
-    "apple-mail-mcp": "build/index.js"
+    "apple-mail-mcp": "build/index.js",
+    "apple-mail-send": "build/cli.js"
   },
   "files": [
     "build",