Apple Mail (MacOS)

Use local CLI to manage Gmail, Outlook, iCloud, Yahoo, Fastmail, and other mail accounts synced in Apple Mail on macOS, without APIs or OAuth.

Security Scan

The skill's requirements, runtime instructions, and local file usage are coherent with its stated goal of controlling Mail.app on macOS; it does not request unrelated credentials or remote installs and emphasizes dry-runs and confirmations before writes.

Purpose & Capability

Name and description match the requested tooling: AppleScript (osascript), Shortcuts, and sqlite3 are reasonable ways to read and automate Mail.app. The declared config path ~/apple-mail-macos/ is consistent with the skill's local-memory approach and no external credentials or cloud APIs are required.

Instruction Scope

SKILL.md stays within the stated scope (read, draft, send, move, archive, delete via Mail.app). It explicitly requires terminal automation permission to control Mail (osascript) and reads the local Envelope Index via sqlite3 for read-only lookups. This is appropriate for the purpose but carries elevated system automation privileges — the user must grant their terminal app permission to control Mail, which realistically allows local mailbox modification via the terminal.

Install Mechanism

Instruction-only skill with no install spec or remote downloads. This minimizes supply-chain risk because nothing is written to disk except the documented local memory files under ~/apple-mail-macos/ which are created only after explicit onboarding.

Credentials

No environment variables, API keys, or unrelated credentials are requested. The only filesystem access is the declared config path and (for read-only probes) Mail.app data under ~/Library/Mail, which is proportional to the described functionality.

Persistence & Privilege

The skill stores state locally in its own folder and does not request always:true or system-wide configuration changes. The default allowing autonomous invocation (disable-model-invocation: false) is platform normal and not by itself a concern here.

Assessment

This skill appears to do what it says: manipulate accounts already configured in Apple Mail by using osascript/Shortcuts/sqlite3 and keeping state in ~/apple-mail-macos/. Before installing or enabling it, verify: (1) you really want to grant your terminal app Automation permission to control Mail (that permission allows local scripts to read and change mailboxes); (2) Mail.app accounts are already configured and any Proton Mail usage has a running Bridge if needed; (3) you review and keep the safety defaults (dry-run and confirmation gates) enabled so the agent cannot send or delete without explicit confirmation. Because automation uses local system permissions, treat granting those permissions to the terminal as equivalent to granting local mailbox control — only proceed if you trust the environment and the agent's prompts.

Setup

On first use, follow setup.md to define provider scope, command path preferences, and safety defaults before any write action.

When to Use

User wants to control Apple Mail from CLI while keeping account sync managed by Mail.app. Agent handles read, search, triage, draft, send, move, archive, and delete workflows across accounts already connected in Apple Mail.

Requirements

• macOS with Mail.app account access enabled for terminal automation.
• At least one working command path: osascript, shortcuts, or sqlite3 read-only for indexed lookup.
• Provider accounts already connected in Mail.app (Gmail, Outlook, iCloud, Yahoo, Fastmail, and Proton via Bridge if used).
• Explicit confirmation before sending, deleting, or bulk actions.

Architecture

Memory lives in ~/apple-mail-macos/. See memory-template.md for structure.

~/apple-mail-macos/
├── memory.md               # Status, provider map, safety defaults
├── command-paths.md        # Working command path and fallback notes
├── provider-coverage.md    # Provider-specific behavior and caveats
├── safety-log.md           # Send/delete confirmations and rollback notes
└── operation-log.md        # Operation IDs, verification evidence, outcomes

Quick Reference

Topic	File
Setup and first-run behavior	setup.md
Memory structure	memory-template.md
Command hierarchy and probes	command-paths.md
Provider behavior matrix	provider-coverage.md
Safety checklist before writes	safety-checklist.md
Deterministic operation patterns	operation-patterns.md
Failure handling and recovery	troubleshooting.md

Data Storage

All skill files are stored in ~/apple-mail-macos/. Before creating or changing local files, describe the planned write and ask for confirmation.

Core Rules

1. Treat Mail.app as the Unified Account Layer

• Assume provider sync is already configured in Apple Mail and operate on that local unified mailbox layer.
• Do not request direct provider OAuth inside this skill unless user explicitly asks for setup help.

2. Detect Command Path Before Every Operation

• Probe command paths in strict order: osascript, then shortcuts, then sqlite3 for read-only indexed lookup.
• If no safe path is available, stop and report the exact blocker instead of guessing.

3. Default to Dry-Run for Write Intents

• For compose, reply, move, archive, and delete workflows, first produce a dry-run preview with impacted messages and fields.
• Do not execute live changes until user confirms the dry-run summary.

4. Enforce High-Risk Confirmation Gates

• Require explicit confirmation for send, delete, bulk move, bulk archive, forwarding, and reply-all expansions.
• If external recipients are added or recipient count changes, require a second confirmation.

5. Use Operation IDs and Idempotency

• Generate a unique operation ID for every write workflow and include it in local operation logs.
• Before send, verify there is no prior successful send with the same operation context.

6. Read First, Write Once, Verify Immediately

• Resolve message identity with at least two fields (message ID plus sender or date) before any write action.
• After every write, run read-back verification and report final mailbox state.

7. Keep Exposure Minimal and Local-First

• Use only required fields for the requested task and avoid broad mailbox exports by default.
• Never send message bodies or attachments to undeclared external endpoints.

Common Traps

• Sending from draft without final recipient review -> wrong recipient incidents.
• Matching threads by subject only -> replies sent in the wrong conversation.
• Bulk archive or delete without dry-run count -> accidental data loss.
• Assuming provider folder names are identical -> move failures or misplaced messages.
• Skipping read-back verification -> false success reports.

Security & Privacy

Data that stays local:

• Operational context and defaults in ~/apple-mail-macos/.
• Message metadata needed to execute the requested task.

Data that may leave your machine:

• Email content only when user confirms a send, reply, or forward through already configured provider accounts.

This skill does NOT:

• Send mail without explicit user confirmation.
• Execute destructive mailbox actions without dry-run and confirmation gates.
• Request undeclared API keys or call undeclared third-party APIs.

Related Skills

Install with clawhub install <slug> if user confirms:

• macos - macOS command workflows and system automation patterns.
• mail - cross-platform mailbox handling patterns and protocol references.
• events - event extraction and action-item framing from communications.
• schedule - scheduling workflows linked to message-driven tasks.
• productivity - execution and prioritization frameworks for daily work.

Feedback

• If useful: clawhub star apple-mail-macos
• Stay updated: clawhub sync