Automating Apple Mail (JXA-first, AppleScript discovery)

Contents

• Relationship to macOS automation skill

• Core Framing

• Workflow

• Quick Start Examples

• Validation Checklist

• When Not to Use

• What to load

Relationship to the macOS automation skill

• Use automating-mac-apps for permissions, shell, and UI scripting guidance.

• PyXA Installation: See automating-mac-apps skill (PyXA Installation section).

Core Framing

• Mail dictionary is AppleScript-first; discover in Script Editor.

• Objects are specifiers: read via method calls (message.subject() ), modify via assignments (message.readStatus = true ).

• ObjC bridge available for advanced filesystem operations.

Workflow (default)

• Ensure Mail configured and automation permissions enabled.

• Discover terms in Script Editor (Mail dictionary).

• Prototype minimal AppleScript command.

• Port to JXA with defensive checks.

• Use batch reads for performance.

• Use UI scripting for signature and UI-only actions.

Quick Start Examples

Read inbox (JXA):

const Mail = Application('Mail'); const message = Mail.inbox.messages[0]; console.log(message.subject());

Compose message (JXA):

const msg = Mail.OutgoingMessage({ subject: "Status Update", content: "All systems go." }); Mail.outgoingMessages.push(msg); msg.visible = true;

PyXA alternative:

import PyXA mail = PyXA.Mail() inbox = mail.inboxes()[0] message = inbox.messages()[0] print(f"Subject: {message.subject()}")

Validation Checklist

• Automation permissions granted (System Settings > Privacy > Automation)

• Inbox access works: Mail.inbox.messages.length

• Message property reads return expected values

• Composition creates visible draft

• Batch operations complete without errors

When Not to Use

• For cross-platform email automation (use IMAP/SMTP libraries)

• For bulk email sending (use transactional email services like SendGrid)

• When processing untrusted email content (security risk)

• For non-macOS platforms

What to load

• Mail JXA basics: automating-mail/references/mail-basics.md

• Recipes (filter, move, compose): automating-mail/references/mail-recipes.md

• Advanced patterns (batch ops, HTML, signatures): automating-mail/references/mail-advanced.md

• Dictionary translation table: automating-mail/references/mail-dictionary.md

• Rule scripts: automating-mail/references/mail-rules.md

• HTML + signature workflow: automating-mail/references/html-signature-workflow.md

• Attachment extraction pipeline: automating-mail/references/attachment-extraction.md

• Mailbox archiver: automating-mail/references/mailbox-archiver.md

• HTML data merge: automating-mail/references/html-data-merge.md

• PyXA API Reference (complete class/method docs): automating-mail/references/mail-pyxa-api-reference.md