majiayu000 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-appsfor permissions, shell, and UI scripting guidance. - PyXA Installation: See
automating-mac-appsskill (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