Skip to content

v3.0.0: Native transport, Exchange support, and background Gmail Archive

Choose a tag to compare

View all tags
@0xSMW 0xSMW released this 20 Oct 03:33
v3.0.0
d482aa0
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Mail.app CLI 3.0 sends typed Apple Events to Mail.app and reads Mail's local data through embedded SQLite. This reduces subprocess overhead and Mail rendering stalls. Exchange search, moves, and drafts are more reliable. Gmail Inbox Archive runs in a background viewer, so you can keep working while an agent archives. Connected Gmail accounts can manage labels. Existing commands and JSON schema version 1 remain compatible.

Native transport

  • Native is the default on macOS builds with cgo. Apple Events handle metadata, message changes, composition, rules, and signatures. Read-only embedded SQLite handles local lists and searches.
  • Bodies, headers, and attachments come from Mail's cached MIME when the cached copy is complete. Missing local content falls back to scoped Mail reads where supported.
  • --backend legacy or MAIL_APP_CLI_BACKEND=legacy selects the scripting backend, which non-cgo builds use automatically. Failed native changes never retry through legacy.

Exchange and search

  • Exchange mailboxes are recognized in Inbox and other folders, so search and cached content include previously missing messages.
  • Scoped reads recover from a lagging local index and confirm the requested account and mailbox.
  • Incomplete searches fail unless you request partial results.
  • Moves and archives stay verifiable when sync changes a local ID or size. Matching uses RFC message identity, account, sender, subject, and sent time. Ambiguous matches report as unverified.

Drafts and sending

  • On the native backend, compose, reply, reply all, and forward use Apple Events in the CLI and TUI and keep Mail's original message relationships. send and drafts create accept --reply-to, --reply-all, and --forward-of.
  • You can create, update, and send saved plain-text drafts with ordinary attachments. Recipients, blank paragraphs, Unicode filenames, and file contents are preserved.
  • Both backends record the draft before sending. After Mail acknowledges submission, they delete the draft only if it is unchanged. Uncertain sends are never resubmitted automatically. Acknowledgment does not confirm delivery, and Mail may normalize newlines in text attachments.
  • Drafts with custom formatting, inline content, signing, encryption, or reply headers stay in Mail.

Gmail

  • In 2.4, Gmail Inbox Archive opened a separate window. It now uses a background viewer with the preview hidden, on both backends. It never activates Mail, raises windows, or changes focus, and it closes only its own viewer. It stops before pressing if the message or button is missing or ambiguous, and it never repeats an uncertain archive.
  • New label commands connect through OAuth and store tokens in Keychain. They list labels and add or remove Important and existing custom labels, with dry runs, receipts, and verification against Gmail. A mismatched identity stops the change. Labels apply to Gmail only.

Upgrade and permissions

  • The module path is now github.com/0xSMW/mail.app-cli/v3, and the install script installs /v3.
  • Native source builds need macOS, Go 1.25 or newer, and Xcode Command Line Tools.
  • Grant Automation access to Mail and Full Disk Access to the app running the CLI. Gmail Inbox Archive also needs Accessibility access. mail-app-cli doctor reports access and the active backend.

Install

CGO_ENABLED=1 go install github.com/0xSMW/mail.app-cli/v3/cmd/mail-app-cli@v3.0.0
Assets 2
Loading