skills.rest
roman-pinchuk
roman-pinchukCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

apple-mail-jxa

Automate macOS Mail.app operations through inline JXA and SQLite metadata search.

Updated Jul 20, 2026
Search Tags:#sqlite#jxa#macos automation#osascript#email search#apple mail#mail.app
One-click install
npx skills add https://github.com/roman-pinchuk/agent-skills --skill apple-mail-jxa-roman-pinchuk
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: apple-mail-jxa
Source: https://github.com/roman-pinchuk/agent-skills/tree/main/skills/apple-mail-jxa
Command: npx skills add https://github.com/roman-pinchuk/agent-skills --skill apple-mail-jxa-roman-pinchuk

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Automating Apple Mail on macOS is error-prone: external scripts drift out of date, UI automation is fragile, and searching large mailboxes through AppleScript is slow. This Skill provides a controlled, inline JXA approach for reading, searching, drafting, sending, and managing Mail.app messages with explicit permission and confirmation boundaries. ## Core Features & Use Cases - Hybrid backend search: Use Mail.app JXA for scoped mailbox operations and the local Envelope Index SQLite database for fast global or account-wide metadata search. - Full message lifecycle: Discover accounts and mailboxes, read bounded message bodies, create visible drafts, send, reply, forward, move, delete, and change read or flagged state. - Safety controls: JSON output with sanitized errors, explicit confirmation before every mutation, no credential access, and no silent fallback between backends. - Use Case: Ask the agent to find all unread messages from a specific sender across every account, summarize them, then draft a reply to one message and confirm before sending. ## Quick Start Use the apple-mail-jxa skill to search my Mail for unread messages from [email protected] and show me the subjects and dates.

Frequently Asked Questions about apple-mail-jxa

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I automate Apple Mail with JavaScript on macOS?▼

Use inline JXA via osascript -l JavaScript to control Mail.app directly. The Mail application object exposes accounts, mailboxes, and messages, letting you read, draft, send, move, and delete messages without external scripts or UI automation.

How to search all Apple Mail messages fast from a script?▼

Query Mail's local Envelope Index SQLite database in read-only mode for global metadata search across accounts. Resolve each result back through Mail.app JXA before reading bodies or changing state, since SQLite IDs can become stale after synchronization.

Does Mail.app JXA automation require special macOS permissions?▼

Yes. Mail.app JXA requires macOS Automation permission for the launching terminal or agent. Searching the Envelope Index database additionally requires Full Disk Access, and the skill stops and reports the requirement if access is denied.

Can JXA send email from Mail.app without user confirmation?▼

It can technically call send, but this skill requires creating a visible draft first, showing recipients, subject, and body summary, then obtaining explicit confirmation before sending. The same confirmation rule applies to replies, forwards, moves, and deletions.

Why does SQLite search of the Envelope Index fail on some systems?▼

The Envelope Index schema is private and can change between macOS versions. The skill preflights required tables like messages, subjects, addresses, and mailboxes, and stops with an error instead of guessing if the schema is unsupported.

Related Skills

Explore More Personal & Entrepreneur Skills→
Aayush9029Aayush9029
10

apple-mail-exporter

Search Apple Mail's local database by keyword, sender, or subject and export matching emails.

Community
Intermediate
73ai73ai
4

gws-workflow-email-to-task

Convert a Gmail message into a Google Tasks entry using subject and snippet.

Official
Intermediate
storyclaw-officialstoryclaw-official

local-tools

Manage calendar events on macOS and Windows via JXA and PowerShell.

Official
Intermediate
spamschspamsch
29

Mail Assistant

Search and manage emails on IMAP servers without Mail.app.

Community
Intermediate