Skip to content

Releases

Mail MCP 3.1.1

Choose a tag to compare

@1amSheldon 1amSheldon released this 14 Oct 18:46
973ed01

Fixed

IMAP keyword combinations now avoid nested negation and mixed OR expressions that some servers parse incorrectly. Required words and exclusions use positive conjunctions and individual exclusions; genuine alternatives are intersected by UID within the same bounded search window.

The intersection happens before page truncation, preserving cursor completeness. Ordinary searches and unconstrained alternatives still need one SEARCH command; combined alternatives need at most two per UID window. No message bodies are downloaded to evaluate these predicates.

3.1.1 includes all 3.1.0 features, including the Zimbra backend and compact on-demand agent references. This patch does not change account configuration or authentication requirements.

Validation: 1,413 unit tests, 8 integration tests, all transport/installation smoke checks and dependency audit passed. Three external IMAP integration cases require credentials and were skipped. Linux and Windows CI passed with Node 20 and 22. Compound search, cursor traversal and full reads were also checked against a real IMAP account without modifying mail. Text matching follows the provider's index and language rules; terms are not interpreted by the MCP.

3.1.0 — Zimbra and mail reliability

Choose a tag to compare

@1amSheldon 1amSheldon released this 14 Oct 18:05
48f1e8b

Zimbra and mail reliability

Mail MCP 3.1.0 adds Zimbra as an optional provider alongside IMAP/SMTP, Apple Mail, Microsoft and Mailtrap. Existing accounts do not need a Zimbra server.

  • Native Zimbra SOAP/REST supports mail search and reads, MIME attachments, draft creation/editing/sending, folders, flags, tags, contacts, groups and directory lookup.
  • Zimbra also supports identities, signatures, preferences, incoming/outgoing rules, sharing, Briefcase files and revisions, calendars, tasks, recurring events, invitations, iCalendar and native scheduled delivery.
  • Authenticate locally with a password and required second factor. Trusted-device login and password storage are optional and disabled by default. Credentials are not MCP arguments.
  • Persist Zimbra send attempts and report uncertain outcomes without automatically resending. Guard edits against reviewed revisions and check configured recipient and attachment policies.
  • Integrate bounded IMAP paging, mailbox-generation checks, message previews, MIME reads and caches; improve threaded reply drafts and attachment-aware replies/forwards.
  • Improve SMTP/OAuth lifecycle, TLS verification, provider pagination, EWS attachment sends and uncertain save/send results.
  • Keep three MCP tools. Load the core workflow and only the required provider/topic instructions, through resources or prompts, instead of loading the entire documentation set.
  • Preserve the public npm update channel and windowless shared Windows service. Codex and Claude receive the same packaged instruction references.

Upgrade notes

Accounts and credentials remain outside the package. Keep persistent draft/send records when moving an installation; an unknown delivery outcome is not permission to resend. Zimbra capabilities depend on the server version, edition, authentication extensions and account permissions. Native scheduling can use later webmail edits, and clearing its metadata cannot recall an already-started send.

Older nonempty IMAP draft journals lack a mailbox-identity binding. The local migration command uses a retained pre-upgrade accounts snapshot, preserves all records and attempts, and writes a backup. Do not delete journals or bind them to an unverified replacement mailbox. See the README for the command and upgrade procedure.

Verification

Release checks cover TypeScript/build, generated documentation, English-only text, unit and loopback integration tests, stdio/HTTP/import/installed-package smoke checks and dependency audit. Dedicated regressions cover cancellation during credential lookup, shutdown during provider creation, persistent draft migration and on-demand documentation. Credential-gated external IMAP integration cases remain skipped without test credentials. Real Zimbra login, delivery and server compatibility are not established by the fixture suite; use a dedicated test account to qualify the target server.

Thanks to starychenko for the Zimbra implementation and mail hardening work. This release integrates the final source across its branches, retains contributor attribution, and adds lifecycle, documentation and public-distribution fixes after review.

3.0.0 — Server drafts and keyword search

Choose a tag to compare

@1amSheldon 1amSheldon released this 21 Sep 13:23
587f09f

Server drafts and keyword search

  • Edit IMAP drafts with updateDraft and send the latest server revision with sendDraft. Stable local draft IDs follow supported webmail UID changes.
  • Persist delivery attempts across restarts. Repeated calls return the saved result; uncertain or partial delivery never triggers an automatic resend. Retain the source draft unless all recipients were accepted and a Sent copy was confirmed.
  • Preserve MIME bodies, attachments, threading, and custom draft metadata. Reject ambiguous routing headers and strip Bcc from the wire while retaining envelope recipients.
  • Search with keywordsAll, keywordsAny, excludeKeywords, body/subject/all scopes, unread/read and flagged/unflagged filters. Searches stay server-side and bind all filters to their pagination cursor.
  • Recognize provider-prefixed Message-IDs during Sent verification without scanning unrelated recent messages.
  • Install a local Windows checkout with --install-codex-local when developing. Published installations keep the windowless direct-Node supervisor and npm updates.
  • Keep the compact three-tool MCP interface; detailed instructions remain available on demand for Codex and Claude.

Upgrade

Accounts, credentials, and HTTP connection settings remain in place. Refresh the MCP client's tool catalog to discover the new draft operations. Draft state is stored under ~/.config/mail-mcp/draft-state; preserve it when moving an installation. Independent sends from webmail or another computer are outside local duplicate prevention. Interrupted draft replacement or stale process locks require inspection rather than an automatic retry.

Verification

npm run release:check includes unit tests, loopback SMTP integration, build, English-only text, stdio/HTTP/import smoke checks, and dependency audit. The loopback test verifies actual MIME delivery, hidden Bcc, attachment preservation, and no duplicate after a restart. A read-only probe against a configured IMAP account verified positive keyword matches, exclusions, and combined text/flag criteria; it did not modify mail or print message contents. Credential-gated provider IMAP integration cases remain skipped when test credentials are absent. Live draft writes and sends were not performed on the user's mailbox.

Thanks to wiederholung for the initial draft workflow contribution. This release adds persistence, MIME, validation, and regression-test fixes after review.

v2.1.3

Choose a tag to compare

@1amSheldon 1amSheldon released this 15 Sep 20:45
f2851fa

Fix console windows flashing during Windows logon and five-minute watchdog checks.

Also remove the runtime npx/cmd.exe chain, which could leave a visible Windows Terminal window. The supervisor installs package updates through a hidden direct Node/npm CLI process with lifecycle scripts disabled, then runs the server entrypoint directly. If a refresh fails, an already installed runtime can still start.

Existing Windows users should run npx -y --prefer-online @1amsheldon/mail-mcp@latest --install-codex once outside a source checkout to replace the old supervisor. Package auto-updates alone do not replace an already running supervisor.

The scheduled task now starts Windows Script Host, a GUI executable, which launches PowerShell hidden at process creation and waits for it to exit. Previously the task started powershell.exe directly; its console could appear before -WindowStyle Hidden took effect.

Existing managed Windows services migrate their exact legacy task action when the updated service starts. The migration preserves triggers, settings and the running service, backs up the old task definition, and leaves unrelated/custom tasks alone. Installations also snapshot the new launcher for rollback.

Stop requests are now observed while the server is running. Upgrading an older supervisor first waits for it to stop; if needed, it terminates only a process tree whose ancestry and exact supervisor command match this installation. Unverified listeners are left untouched.

Validation: 800 tests, full release checks, a local scheduled-task trigger and a successful local installer migration. The live server runs directly beneath its Node supervisor, with no npx or cmd.exe in the chain. HTTP health is ok and no WindowsTerminal/OpenConsole processes remained after replacing the old tree. Mailboxes were not accessed.

v2.1.2

Choose a tag to compare

@1amSheldon 1amSheldon released this 14 Sep 18:39
eb36cfc

Improve IMAP connection recovery and command-line diagnostics.

  • Reject connections that close during setup instead of caching an unusable service. Clean up failed connections while preserving the original error.
  • Prevent service creation during shutdown and discard connections that finish after shutdown begins.
  • Make --validate-accounts return a failing exit code when a probe fails or no IMAP accounts are configured. Always clean up IMAP probes and print passed, failed and skipped totals.
  • Stop requesting a Codex restart after updating an existing Windows HTTP installation when its settings and token are unchanged.
  • Document connection diagnostics and update behavior in the README. The MCP interface remains three tools.

Validation: 797 tests passed; build, English check, stdio/HTTP/import smoke and npm audit passed. An isolated CLI process with no accounts returned exit code 1 and the expected message. Regression tests reproduced the connection lifecycle failures before the fix. No user mailbox operations were performed.

v2.0.2

Choose a tag to compare

@1amSheldon 1amSheldon released this 14 Sep 18:27
d7cd765

Fix a process crash when an idle IMAP connection emits an error. Error and close listeners are registered before connecting; closed clients are removed from the cache so the next request reconnects. Logs retain error codes without server-controlled message text.

Update Nodemailer to 10.0.9 and refresh vulnerable MIME and HTTP dependencies. Node.js requirements remain >=20.19.0. The MCP interface remains three tools.

Thanks to @rlucia for #12 and #13, integrated with additional error-handling and logging tests in #14.

Validation: 792 tests, Node 20/22 CI, three local SMTP integration tests, stdio/HTTP smoke, and zero npm audit findings. Credential-dependent IMAP integration tests were not run.

mail-mcp 2.0.1

Choose a tag to compare

@1amSheldon 1amSheldon released this 01 Sep 07:45
feaa2fc

Fixes Codex chats failing after the managed HTTP service restarts during sleep, idle cleanup, or an automatic package update. Requests carrying an older MCP session ID now recover through a stateless request path, stale optional SSE streams close with the protocol-supported response, and pending write confirmations remain shared across HTTP session instances. Also rejects non-canonical pagination cursor signatures consistently across Node versions.

mail-mcp 2.0.0

Choose a tag to compare

@1amSheldon 1amSheldon released this 31 Aug 17:44
73b291d

Version 2 consolidates the MCP surface into three public tools while retaining 41 query and 50 mutation operations. It adds IMAP/SMTP/ManageSieve, Apple Mail, Microsoft Graph/EWS, and Mailtrap backends; stable message locators and cursor pagination; guarded writes; Codex, Claude Desktop, and Claude Code installers; a shared authenticated Windows HTTP service; transactional upgrades; and the bundled mail-mcp agent skill. This is a breaking MCP tool-surface change: restart the client after upgrading so it refreshes the tool list. Stored account definitions and keychain credentials remain unchanged.

v1.6.0

Choose a tag to compare

@1amSheldon 1amSheldon released this 30 Aug 19:10
167f880

Highlights

  • --install-codex now installs one authenticated shared HTTP service on Windows, so Codex conversations reuse one mail process and connection pool.
  • The service starts at sign-in, prevents duplicate instances, restarts after a crash, rotates logs, and has a five-minute watchdog.
  • It checks npm every six hours and restarts onto the latest release after giving in-flight requests up to eight seconds to finish.
  • Codex stores only the bearer-token environment variable name. The token stays in the Windows user environment.
  • --install-codex-stdio remains available for an explicit per-client stdio setup.
  • Health responses now include the package version, service identity, start time, and active session count.

Upgrade

Run:

npx -y --prefer-online @1amsheldon/mail-mcp@latest --install-codex

Restart Codex once after installation so the app inherits the user-level bearer token. Existing accounts and credentials are preserved.

v1.5.5

Choose a tag to compare

@1amSheldon 1amSheldon released this 30 Aug 18:21
f7249f4

This release makes automatic package resolution reliable even when an older global or project-local mail-mcp binary is present.

  • Codex and Claude Desktop installers now resolve the latest package through a dedicated npm prefix.
  • Explicit npm package selection prevents stale PATH entries from overriding the requested release.
  • Codex installer tests now validate parsed TOML on Windows and Linux.
  • CI uses the current GitHub Actions runtime without deprecation warnings.

Verified with 578 tests, Node.js 20 and 22 CI, stdio and Streamable HTTP smoke checks, import smoke, package inspection, a conflicting-global-install regression test, and an npm audit with 0 vulnerabilities.