references/mail-automation.md — Desktop Mail Assistant

# Mail automation boundaries

Desktop Mail Assistant invokes `/usr/bin/osascript` with fixed JavaScript for Automation (JXA) source. User-supplied text is passed as separate argv values to `run(argv)`; it is never inserted into script source. Every osascript call has a timeout. macOS Automation (TCC) permission controls whether the calling application may control Mail.

Account and top-level mailbox names are resolved inside Mail from the caller's exact values. `read` addresses a message by Mail's numeric scripting ID within the chosen account and mailbox, which differs from the email Message-ID header. Search and recent output is bounded, but Mail may enumerate the selected mailbox before applying the output limit. The body cap limits text displayed by `read`; it does not alter the message in Mail.

For send and draft, the dry run displays all intended message fields and a digest of their canonical content, including the decoded body text. Live mode recomputes and compares the digest before asking Mail to write. The sender address must belong to exactly one configured account; Mail chooses the sending account from the outgoing message's sender property. Send verification checks that account's Sent mailbox after Mail accepts the message. If verification fails or an osascript timeout occurs after a write began, the outcome may be uncertain: inspect Mail before retrying.

The Python tool does not open sockets or contact a host. Mail app synchronization may contact the provider already configured in Mail; those provider hosts vary by user account and are outside the tool's control. Mail manages credentials. The tool reads only the selected body file and test fixture path, along with values passed on the command line. Human output escapes untrusted text onto single lines. Test fixtures require both fake-mode environment variables and cause a warning; they never launch Mail.

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