AppleScript + Apple Mail Patterns

Emitting JSON from AppleScript

Scripts emit JSON via ASObjC + NSJSONSerialization (not pipe-delimited text). Use the _wrap_as_json_script(body) helper in mail_connector.py and parse responses with parse_applescript_json(result) from utils.py.

Tell-block contract: the body passed to _wrap_as_json_script must contain a tell application "Mail" ... end tell block and assign the final value to a variable named resultData (list, record, or scalar).

Record key gotcha — always quote `name`: Use |name|:(name of acc), never name:(name of acc). The bare form collides with NSObject's name selector and the key is silently dropped during NSDictionary conversion, leaving records without their name field.

`missing value` gotcha: NSJSONSerialization rejects missing value. For optional properties (e.g., email addresses of an account with none, unread count on some mailboxes), coerce before building the record:

set accEmails to email addresses of acc
if accEmails is missing value then set accEmails to {}

Error propagation: Do NOT wrap the tell-body in try / on error when you want typed exceptions (MailAccountNotFoundError, MailMessageNotFoundError, etc.). Let AppleScript errors bubble via stderr — _run_applescript maps them to the right exception type.

Gmail Label-Based System

Gmail doesn't support standard IMAP move operations. The update_message tool has a gmail_mode parameter (when used with destination_mailbox):

# Standard IMAP (Exchange, iCloud, etc.)
move message to destination_mailbox

# Gmail mode (copy + delete)
duplicate message to destination_mailbox
delete message  # Removes from source label

Bug story: Early versions silently failed when moving Gmail messages. The move appeared to succeed but the message stayed in the source mailbox. gmail_mode was added to handle this.

When to use: Always expose gmail_mode as an optional parameter on any tool that moves or archives messages.

Message ID Lookup

Finding a specific message by ID requires searching across accounts and mailboxes:

tell application "Mail"
    set allAccounts to every account
    repeat with acct in allAccounts
        set allMailboxes to every mailbox of acct
        repeat with mbox in allMailboxes
            set msgs to (messages of mbox whose id is targetId)
            if (count of msgs) > 0 then
                return first item of msgs
            end if
        end repeat
    end repeat
end tell

Performance: This is O(accounts × mailboxes). For users with many accounts, this can be slow. The whose clause makes it tolerable but not fast.

Optimization: If the caller knows the account and mailbox, always accept them as optional parameters to narrow the search.

String Escaping

Always use `escape_applescript_string()` for user-provided text:

# In utils.py — escapes backslashes first, then double quotes
def escape_applescript_string(s: str) -> str:
    return s.replace("\\", "\\\\").replace('"', '\\"')

Bug story: Unescaped quotes in email subjects caused AppleScript blocks to fail silently. The error appears as a generic "Can't make" error in stderr with no indication of the actual cause.

Rule: Every string interpolated into AppleScript MUST go through escape_applescript_string(). No exceptions. Check via check_applescript_safety.sh.

Dates: never use a date "..." literal

AppleScript parses date-string literals against the user's locale, and gets it wrong silently:

date "2026-05-28"           --> year 12196
date "2026-08-09 11:03:51"  --> Wednesday, October 8, 12177

Neither raises. Nothing warns. A filter built on one of these just quietly matches nothing — and because the surrounding code behaves correctly, the bug is invisible above the AppleScript boundary.

Bug story (#436): a date literal bounded a message-search window. The window was ~10,000 years off, so it matched nothing, and the failure surfaced as a clean, plausible MailAnchorLookupIncompleteError for a message sitting at index 1 of the INBOX. Cost a full integration cycle. The trap had already been documented — in a helper docstring inside a 6,000-line module, which is not where anyone writing new AppleScript looks. Hence this section.

Always build dates from components via _construct_as_date_var() in mail_connector.py:

_construct_as_date_var("targetDate", 2026, 8, 9, 39831)  # 39831 = 11:03:51

which emits:

set targetDate to current date
set day of targetDate to 1        -- FIRST: see below
set year of targetDate to 2026
set month of targetDate to 8
set day of targetDate to 9
set time of targetDate to 39831   -- seconds since midnight

Why `set day to 1` comes first: if current date is the 31st and you set month to a 30-day month, AppleScript rolls into the next month. Resetting the day first makes the sequence safe for every date.

Rule: every date in generated AppleScript goes through _construct_as_date_var(). check_applescript_safety.sh (Check 6) fails the build on a date "..." literal in src/. If you are documenting the trap rather than committing it, wrap the example in backticks — that is how the check distinguishes prose from code.

Attachment Handling

Attachments use POSIX file references:

-- Sending attachments
set theAttachment to POSIX file "/Users/user/file.pdf"
make new attachment with properties {file name: theAttachment} at after the last paragraph

-- Saving attachments
save attachment theAttach in POSIX file "/Users/user/Downloads/"

Path conversion: Python Path objects → .as_posix() → AppleScript POSIX file "...".

Security: Always validate:

• File exists before sending
• Directory exists before saving
• No path traversal (.. in path)
• Extension not in blocklist (.exe, .bat, .sh, .app, etc.)
• Size under 25MB limit

whose Clause Filtering

Use AppleScript whose clauses for server-side filtering instead of fetching all messages:

-- GOOD: Server-side filter (fast)
set msgs to (messages of mbox whose sender contains "[email protected]")

-- BAD: Fetch all then filter in Python (slow)
set msgs to every message of mbox
-- then filter in Python

Combine clauses for multi-field search:

messages whose sender contains "user" and subject contains "report"

Limitation: whose clauses don't support OR logic well. For OR conditions, use multiple whose queries and merge results in Python.

Known Mail.app Automation Limitations

1. No scheduled sending — Mail.app has no AppleScript support for delayed/scheduled sends
2. Thread reconstruction is possible but not native — Mail.app has no thread or conversation class. Reconstruct threads by reading headers of msg for in-reply-to, references, and matching against message id of msg (the RFC 822 header value) across candidate messages. See get_thread in mail_connector.py.

`whose message id is "X"` is NOT indexed, and AppleScript runs on Mail's UI thread — so it loads every message in the mailbox and freezes the app, not merely slowly (measured: 33,569 messages in one INBOX, 62,085 in Gmail's All Mail). The _run_applescript timeout does not rescue Mail; it kills our osascript client while Mail keeps grinding.

Resolve an RFC Message-ID by IMAP first — SEARCH HEADER Message-ID is server-indexed (measured 0.14s over 61,880 messages) and returns the arrival date — then binary-search the mailbox by that date. Messages enumerate strictly newest-first with cheap positional access, so that is ~log₂(n) property reads. See find_message_by_message_id (#432/#434). Mail's numeric id is indexed, so whose id is N stays instant and needs none of this.

1. Rule management is partial — Rules are readable (rules collection, name, enabled, conditions/actions), but have no stable id and must be addressed positionally or by non-unique name. Mutation paths (creating, updating, deleting) are more complex and not yet implemented.
2. No smart mailbox access — Smart mailboxes are not exposed to AppleScript
3. Rich text body — content of message returns plain text; HTML body requires alternate approach
4. Read receipt — Cannot request or detect read receipts
5. Draft management — Creating drafts is possible but managing them is limited

Error Handling Pattern

try
    -- operation
    return "result_data"
on error errMsg
    return "ERROR: " & errMsg
end try

Python-side parsing:

if result.startswith("ERROR:"):
    raise MailAppleScriptError(result[7:])

stderr-based errors are caught in _run_applescript() and routed to typed exceptions:

• "Can't get account" → MailAccountNotFoundError
• "Can't get mailbox" → MailMailboxNotFoundError
• "Can't get message" → MailMessageNotFoundError
• Everything else → MailAppleScriptError

Checklist: New AppleScript Operation

1. [ ] All user strings escaped with escape_applescript_string()
2. [ ] All inputs sanitized with sanitize_input()
3. [ ] Any dates built via _construct_as_date_var(), never a date "..." literal
4. [ ] Error handling with try/on error in AppleScript
5. [ ] Timeout considered (complex operations may need > 60s)
6. [ ] Integration test written against real Mail.app
7. [ ] check_applescript_safety.sh passes
8. [ ] Gmail compatibility considered (does this operation work with labels?)