What is automating-mail?

A skill to automate Apple Mail via JXA with dictionary discovery for tasks like reading, composing, filtering, and attachments.

Yes, PyXA is shown as an optional Python path for Mail automation.

What permissions are required?

Automation permissions in System Settings > Privacy > Automation; grant Mail access and Script Editor permissions.

automating-mail

npx machina-cli add skill SpillwaveSolutions/automating-mac-apps-plugin/automating-mail --openclaw

Files (1)

SKILL.md

3.4 KB

Automating Apple Mail (JXA-first, AppleScript discovery)

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

Source

git clone https://github.com/SpillwaveSolutions/automating-mac-apps-plugin/blob/main/plugins/automating-mac-apps-plugin/skills/automating-mail/SKILL.md

View on GitHub

Overview

Automating Apple Mail uses JXA with AppleScript dictionary discovery to control Mail.app. It covers accounts, mailboxes, batch message filtering, composition, attachments, and UI-based actions. This skill enables reliable, repeatable email automation on macOS.

How This Skill Works

Mail's dictionary is AppleScript-first and is discovered in Script Editor. Use JXA with defensive checks, reading and setting specifiers (message.subject(), message.readStatus = true). For advanced tasks, an ObjC bridge enables filesystem operations, and PyXA provides a Python alternative path.

When to Use It

Automate routine email tasks in Mail.app on macOS.
Send mail via script or automation tools.
Build JXA-based Mail automation workflows.
Filter or batch-process messages for performance.
Handle attachments and UI-only steps (signatures, dialogs).

Quick Start

Step 1: Ensure Mail automation permissions and discover the Mail dictionary in Script Editor.
Step 2: Prototype a minimal AppleScript command, then port to JXA with defensive checks.
Step 3: Extend to batch reads and UI-assisted actions like signatures, then test.

Best Practices

Grant Mail automation permissions (System Settings > Privacy > Automation).
Discover the dictionary in Script Editor before scripting.
Prototype minimal AppleScript, then port to JXA with defensive checks.
Use batch reads for processing large message sets.
Rely on UI scripting for signatures or UI-only actions when needed.

Example Use Cases

Read inbox (JXA): read the first message subject.
Compose message (JXA): create and publish a draft with subject/content.
PyXA alternative: automate Mail using Python via PyXA.
Batch filtering: filter and move messages in bulk.
Signature handling: use UI scripting for signature insertion.

Frequently Asked Questions

Add this skill to your agents