apple-mail-handler

name: apple-mail-handler description: Use when the user wants to install, inspect, test, or run the Apple Mail Handler plugin that connects Apple Mail rules to Codex CLI and project-local handle-email.md contracts.

Apple Mail Handler

Use this skill for Apple Mail rule automation in this plugin.

Contract

The implementation has one executable path:

1. Apple Mail rule calls scripts/mail_rule_handler.applescript.
2. The AppleScript writes the message body to a temporary UTF-8 file.
3. The AppleScript invokes scripts/apple_mail_handler.py handle-message.
4. The Python bridge writes one message record under the configured state directory.
5. The bridge discovers immediate child projects under ~/IdeaProjects that contain handle-email.md.
6. The bridge invokes Codex CLI exactly once with the email record and the eligible handler file paths.
7. Codex reads the record and the project-local handle-email.md files to decide relevance and action.
8. The bridge appends one JSONL ledger entry after Codex exits successfully.

No reply is sent, moved, or deleted by the bridge. Codex may do so only when a relevant project-local handle-email.md explicitly instructs it.

Commands

Run tests from the repository root:

python3 -m unittest discover -s tests

Handle a manually exported message:

python3 plugins/apple-mail-handler/scripts/apple_mail_handler.py handle-message \
  --message-id example \
  --sender "sender@example.com" \
  --subject "Project Alpha follow-up" \
  --mailbox "INBOX" \
  --body-file /path/to/body.txt \
  --projects-root /Users/velocityworks/IdeaProjects \
  --state-dir /Users/velocityworks/.codex/apple-mail-handler

Project Contract

A project participates only when it contains handle-email.md at the project root.

The bridge does not parse that file or run a separate relevance classifier. Codex reads the file as the project-local contract.

If no project contains handle-email.md, the bridge fails explicitly.

If Codex CLI is missing or exits nonzero, the bridge fails explicitly.