README.md — Desktop Mail Assistant

# Desktop Mail Assistant

Desktop Mail Assistant is a macOS command-line Agent Skill for reading and composing mail through Apple's Mail app. It uses the user's configured Mail accounts through `/usr/bin/osascript`, without API keys or tool-owned network calls. Python 3.10 or newer and the standard library are sufficient.

Synthetic tests require Node.js on PATH for the fixed JXA fake-Mail checks; the CLI requires no Node.js.

The package contains `SKILL.md`, a companion agent, a reference guide, the Python CLI, synthetic tests, and the MIT license. It is free under the MIT license. Skills Outpost is the distribution channel.

## Start

Read [SETUP.md](SETUP.md) to grant macOS Automation access, then run from the package directory:

```text
python3 scripts/desktop_mail_assistant.py accounts
python3 scripts/desktop_mail_assistant.py mailboxes --account ACCOUNT
python3 scripts/desktop_mail_assistant.py recent --account ACCOUNT --mailbox INBOX --limit 10
python3 scripts/desktop_mail_assistant.py send --from FROM_ADDRESS --to TO_ADDRESS --subject "Hello" --body-file ./message.txt --dry-run
```

Use `--help` on the CLI and each command for exact flags. `send` and `draft` require a dry-run digest supplied again with `--approve` for the live operation. A send checks the chosen account's Sent mailbox after Mail accepts it. Treat an unverified send as an uncertain outcome; do not retry blindly.

The CLI's human-readable output escapes untrusted text onto single lines. Recent and search output is bounded to 100 messages, and `read` limits body display. Standard output can still be forwarded by an agent harness, so share only what the user needs. Mail itself manages network access and any account credentials. The CLI does not directly contact network hosts.

## Read scope, input bounds and response errors

macOS is the only supported platform. Unsupported systems fail with a clear error before body-file, fixture or Mail I/O, including dry runs. Send and draft read at most 400,000 UTF-8 bytes plus one overflow byte and reject more than 100,000 decoded characters. Synthetic fixture files are bounded to 2,097,152 bytes plus one overflow byte. Invalid UTF-8, invalid JSON and malformed required response fields fail explicitly. Required Mail scripting properties (message IDs, selected account/mailbox, bodies and Sent recipient lists) still fail explicitly. Optional subject, sender, dates and account email-address properties fall back to empty values if Mail throws; an unavailable address list cannot select a sender account.

The result limits restrict output, not reads: recent and search enumerate every message in the exact chosen mailbox; search reads each subject or sender before filtering and sorting. Read enumerates that mailbox to locate the ID and fetches the entire selected body before truncating display. Sent verification reads metadata and matching fields in the first 100 entries exposed by Mail, without sorting or polling. Automation JSON stdout is captured in memory without a byte limit; Mail can return a large selected body or account/mailbox list. No directory or local output file is created.

The local osascript process receives the operation and selected account/mailbox/ID/search text for reads, or sender, all To/Cc/Bcc addresses, subject and complete body for writes and subsequent Sent correlation. The CLI itself contacts no host or resolver. Mail contacts the provider hosts configured for the selected account (which vary by account) for synchronization and sending; the approved sender, recipients, subject and body go to that provider and the addressed recipients. Reads can cause Mail synchronization. Standard output can be forwarded by the calling harness.

## Sent correlation limits and exact example

A single immediate check examines the first 100 Sent entries exposed by Mail. It compares exact subject and body, sender substring, sorted case-insensitive To/Cc/Bcc addresses, and a sent timestamp at least the attempt start minus five seconds. There is no upper time bound or unique send identifier: another identical message can match. Mail normalization, missing Bcc metadata, delayed synchronization or an entry outside the first 100 can prevent a match. A match is correlation only, not delivery proof or proof of this specific attempt. Inspect Mail before retrying an uncertain write.

```text
python3 scripts/desktop_mail_assistant.py send --from FROM_ADDRESS --to TO_ADDRESS --cc CC_ADDRESS --bcc BCC_ADDRESS --subject "Hello" --body-file ./message.txt --dry-run
python3 scripts/desktop_mail_assistant.py send --from FROM_ADDRESS --to TO_ADDRESS --cc CC_ADDRESS --bcc BCC_ADDRESS --subject "Hello" --body-file ./message.txt --approve DIGEST_FROM_EXACT_PREVIEW
```

Sent correlation runs automatically after this live send; there is no standalone verify command. Use the actual complete arguments and the digest printed for that exact preview.

By Zero Width Lab (zerowidthlab.com)

License: MIT (read it).

Back to the listing