Applescript Mail

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