SETUP.md — Desktop Mail Assistant

# Set up Desktop Mail Assistant

1. On macOS, configure the account in Apple's Mail app and confirm that Mail can access its Inbox and Sent mailbox.
2. Install the complete package in the skill directory used by your agent harness. Keep `scripts/desktop_mail_assistant.py` beside `SKILL.md` in its `scripts` directory.
3. Run `python3 scripts/desktop_mail_assistant.py accounts` from the skill directory. macOS may prompt the terminal or agent harness to control Mail. Grant Automation access for that calling application in System Settings > Privacy & Security > Automation. If denied, enable Mail there and retry.
4. The first call may time out while the permission prompt is open. Answer the prompt, then retry the read command. A timeout is not proof that a send or draft failed; inspect Mail before any retry of a write.

No API keys, browser login, or tool-owned network permission are needed. The Mail app uses the accounts already configured by the user. The Python process invokes only `/usr/bin/osascript` with a fixed JXA script and passes user content as argument values. The OS may show the name of the calling terminal or harness in the Automation panel.

For send or draft, place the full body in a user-chosen UTF-8 `--body-file` of at most 100,000 characters and 400,000 UTF-8 bytes. Preview with `--dry-run`, review every address and the complete body, then use the printed digest with `--approve DIGEST`. A changed file or field requires a new preview. Draft creation follows the same process. Keep sensitive message files in a location chosen and protected by the user.

The complete send/draft payload is passed to osascript as a single argument. Its JSON encoding, recipients and other process arguments count toward the OS argument-size limit; the body-file bounds are not a guarantee that a live launch fits. If macOS rejects the launch, the CLI reports `could not launch or decode osascript response`. Reduce the message size, preview again and approve the new digest.

The test-only `DESKTOP_MAIL_FAKE_RESPONSES` fixture path works only with `DESKTOP_MAIL_FAKE_TRANSPORT_TEST_ACK=1`; it prints a warning and never launches Mail. Never set these for actual use.

## 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