# Apple Mail

> read, search, safely draft, and recoverably delete emails from macos Mail data. optional server draft adapters are explicit and disabled by default.

- **Type:** Skill
- **Install:** `agentstack add skill-don-yin-apple-mail-apple-mail`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Don-Yin](https://agentstack.voostack.com/s/don-yin)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Don-Yin](https://github.com/Don-Yin)
- **Source:** https://github.com/Don-Yin/apple-mail

## Install

```sh
agentstack add skill-don-yin-apple-mail-apple-mail
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# apple mail skill

read, search, and safely draft emails from macos mail data via cli. when this skill is called alone without any specific instruction, see `references/default-task.md`.

## quick start

```bash
# verify setup (mail.app running, full disk access, dependencies)
.cursor/skills/apple-mail/scripts/check-setup.sh

# build the search index (required for search and content previews)
.cursor/skills/apple-mail/scripts/mail.sh build-index

# list a focused recent batch with content previews where already available
.cursor/skills/apple-mail/scripts/mail.sh list-recent --limit 50 --include-content
```

## important: symlink path

this skill lives under `.cursor/skills/apple-mail/` which may be a symlink. all script invocations should use the resolved path from this skill directory. run `.cursor/skills/apple-mail/scripts/check-setup.sh` to see resolved paths.

## production write/delete policy

production must not drive visible Apple Mail compose windows, draft deletion, sending, forwarding, replies, or arbitrary moves. those paths have crashed Mail during testing, including crashes in Mail's scripting delete handlers. `delete-email` is the one production exception: after user confirmation, it moves the message to its own account's Trash/Deleted Items and remains recoverable.

`compose-draft` uses the `auto` backend. by default, `auto` uses the verified hidden Mail.app path: it creates a message with `visible:false`, saves it, restores the previous foreground app, and succeeds only when a matching durable Drafts item is found.

Exchange server drafting is an optional external adapter contract, not a bundled authentication implementation. Set `APPLE_MAIL_WEB_EXCHANGE_CLI` to an executable protocol-v1 adapter and list routed accounts in `APPLE_MAIL_EXCHANGE_REST_ACCOUNTS`. Put account-specific values in `~/.config/apple-mail/env`, which the launcher loads automatically and which must stay outside Git. Private draft data is sent as JSON over stdin, and successful responses must identify the authenticated account. When either setting is absent, `auto` continues to Mail.app. For a pure local file, use `compose-draft --backend artifact`.

`delete-email` is enabled by default and implemented as a same-account move to Trash inside the safety envelope. the following other live Mail mutation commands remain disabled by default: `amend-draft`, `send-draft`, `reply-draft`, `forward-draft`, `delete-draft`, `move-email`, and `batch-move`. they return `MAIL_UI_MUTATION_DISABLED` unless `--allow-live-mail-mutation` is passed for that exact command. this override is development-only and should only be used on a disposable mailbox until the local mutation E2E suite passes repeatedly for that operation. direct developer calls must set both `APPLE_MAIL_ALLOW_UI_MUTATION=1` and `APPLE_MAIL_ALLOW_UI_MUTATION_COMMAND=`.

authorized local Mail mutations now run inside a safety envelope: pre/post Mail health checks, foreground-app capture/restore, and Mail crash-report delta checks. use `local-mutation-preflight` for a non-destructive check of that envelope before any live mutation testing.

the dev focus/cleanup E2E script is also disabled by default. it requires both `APPLE_MAIL_ALLOW_LIVE_E2E=1` and `APPLE_MAIL_ALLOW_UI_MUTATION=1`.

the generated-message local mutation E2E is `scripts/dev/local_mutation_e2e.py full --account EMAIL --to TEST_RECIPIENT --move-folder EXISTING_FOLDER`. it is disabled unless `APPLE_MAIL_ALLOW_LIVE_E2E=1`, `APPLE_MAIL_ALLOW_UI_MUTATION=1`, and `APPLE_MAIL_ALLOW_LOCAL_MUTATION_E2E=1` are all set. it creates only generated canary subjects, then verifies draft create, amend, draft delete, send, move, delete, focus restoration, Mail health, and crash-report deltas.

## tool reference

all commands are invoked via `.cursor/skills/apple-mail/scripts/mail.sh  [args]`.

all output is json with this contract:

```json
{"success": bool, "data": ..., "error": ..., "warnings": [], "meta": {...}}
```

| command                                                                     | what it does                                | speed     |
| --------------------------------------------------------------------------- | ------------------------------------------- | --------- |
| `server-info`                                                               | skill version and metadata                  | instant   |
| `check-health`                                                              | verify mail.app is responding               | ~1 s      |
| `local-mutation-preflight`                                                  | non-destructive health/focus/crash-report safety-envelope check | ~1 s |
| `list-accounts`                                                             | list all mail accounts                      | ~0.15 s   |
| `list-folders --account EMAIL`                                              | list folders with email counts              | ~1-2 s    |
| `list-recent [--limit N] [--include-content]`                               | recent emails from all inboxes              | ~0.3 s    |
| `list-emails --account EMAIL --folder NAME [--limit N] [--include-content]` | emails in a folder                          | ~0.3 s    |
| `list-drafts [--limit N] [--include-content]`                               | drafts across all accounts                  | ~0.25 s   |
| `read-email --message-id MID` or `--id ID`                                  | metadata plus cached/disk content           | ~1-2 s    |
| `search --query TEXT [--scope all\|subject\|sender] [--limit N]`            | search emails                               | ~1 ms     |
| `compose-draft --account EMAIL --subject TEXT --body TEXT --to ADDR... [--font arial\|provider-default] [--attachments PATH...]` | auto-route to an explicitly configured Exchange adapter or verified Mail.app Drafts | ~1-15 s |
| `exchange-auth-status --account EMAIL` | query configured Exchange adapter readiness without Mail.app | network |
| `exchange-auth-login --account EMAIL` | request interactive auth from the configured Exchange adapter | network |
| `compose-draft --backend artifact --account EMAIL --subject TEXT --body TEXT --to ADDR... [--attachments PATH...] [--output-dir DIR]` | create non-ui RFC 5322 `.eml` draft artifact | instant   |
| `amend-draft --id ID [--subject TEXT] [--body TEXT] [--attachments PATH...]`                        | dev-only Mail.app draft mutation; disabled by default | ~2 s      |
| `send-draft --id ID`                                                        | dev-only Mail.app send; disabled by default  | ~2 s      |
| `reply-draft --message-id MID --body TEXT [--reply-all] [--attachments PATH...]` or `--id ID`       | dev-only Mail.app reply draft; disabled by default | ~2 s      |
| `forward-draft --message-id MID --account EMAIL --body TEXT --to ADDR... [--attachments PATH...]`   | dev-only Mail.app forward draft; disabled by default | ~2 s      |
| `delete-email --message-ids MID [MID...]` or `--ids ID [ID...]`             | confirmed deletion by recoverable same-account move to Trash | ~1-3 s    |
| `delete-draft --id ID`                                                      | dev-only Mail.app draft deletion; disabled by default | ~1 s      |
| `move-email --message-id MID --to FOLDER [--to-account EMAIL]` or `--id ID` | dev-only Mail.app move; disabled by default | ~3-5 s    |
| `batch-move --message-ids MID [MID...] --to FOLDER [--to-account EMAIL]`    | dev-only Mail.app batch move; disabled by default | ~5-15 s   |
| `fix-spotlight`                                                             | disable Spotlight for ~/Library/Mail         | instant   |
| `build-index`                                                               | build/rebuild fts5 search index             | ~30-120 s |

array arguments use space separation: `--to a@b.com c@d.com --cc x@y.com`

for detailed parameter docs and return shapes, see `references/tool-reference.md`.

## workflows

### triage inbox

1. `list-recent --limit 50 --include-content` -- scan a focused recent batch with previews where available (note the `message_id` field in output)
2. `read-email --message-id MID` -- open specific email content from the index or disk cache (prefer `--message-id` over `--id`)
3. propose an action to the user. after explicit confirmation, `delete-email` may move the message to its account's Trash; `move-email` remains development-only.

### reply to an email

1. `read-email --message-id MID` -- read the email
2. draft the reply as a hidden synced draft with `compose-draft --account me@example.com --subject "Re: ..." --body "..." --to sender@example.com`
3. verify with `list-drafts --limit 10` after a short delay; do not delete cleanup drafts through Mail.app scripting

### search and act

1. `search --query "invoice" --scope all` -- find matching emails
2. `read-email --message-id MID` -- read full content
3. take action (reply, forward, move, delete)

### compose and send

1. `compose-draft --account me@example.com --subject "Hello" --body "..." --to recipient@example.com`
2. for Mail.app, require `verified: true` and a stable Drafts item; for an Exchange adapter, require `server_written: true`, `verified: true`, `exchange_id`, and `message_id`
3. if an adapter returns `EXCHANGE_AUTH_REQUIRED`, run `exchange-auth-login --account me@example.com` explicitly and retry once
4. for revisions, create a new draft. do not use live `amend-draft` or `send-draft` in production
5. to prefer Arial locally without changing public defaults, set `APPLE_MAIL_DRAFT_FONT=arial`; non-Exchange backends reject unverifiable font requests
6. if Mail becomes unstable, use `APPLE_MAIL_DRAFT_BACKEND=artifact` or `compose-draft --backend artifact`

### bulk triage

for moving or deleting many emails at once, always use live data (not search):

1. `list-emails --account EMAIL --folder Inbox --limit 0` -- get live listing with stable message_ids
2. filter results by subject, sender, or date to identify target emails
3. confirm the list with the user
4. present the confirmed list to the user, then delete with `delete-email --message-ids ...`. It moves each message to the corresponding account's Trash and remains recoverable. `batch-move` stays development-only.

important: never use `search --scope all` as the source of truth for bulk operations. the FTS index can be stale. always verify against live `list-emails` or `list-recent` output.

## safety rules

1. production write/delete safety -- production Mail writes are limited to hidden `compose-draft` create/save and confirmed `delete-email` same-account moves to Trash. do not use visible compose windows or live Mail.app amend/send/move/reply/forward commands in production.
2. always draft first -- never send without creating and confirming a draft
3. never delete without confirmation -- after confirmation, use `delete-email` with stable message IDs whenever possible; deletion is recoverable from Trash/Deleted Items
4. prefer `--message-id` over `--id` -- the RFC 2822 message-id (the `message_id` field from list commands) is stable across exchange syncs; integer ids can shift
5. verify draft outputs -- Mail.app must return `verified: true` and a durable Drafts item; Exchange adapters must return `server_written: true`, `verified: true`, `exchange_id`, and `message_id`; artifact paths must exist and report `mail_app_written: false`
6. content previews are partial -- previews are the first ~5000 chars, not full content. use `read-email` for cached/disk content and expect `content_source: "unavailable"` when safe sources have no body
7. exchange sync delay -- move operations on exchange accounts need ~3 s for server sync when the development override is explicitly enabled
8. draft previews -- `--include-content` may not work for drafts on exchange accounts. use `read-email` for full draft content
9. never delete `/tmp/apple-mail-skill.lock`. if a command reports a lock timeout, wait or ask the user; deleting the lock can create concurrent Mail.app readers and freeze macos.

## verify after writes

prove every safe write took effect before yielding. if a verification fails, surface it to the user before chaining another action -- do not silently retry.

1. after Mail.app `compose-draft`, require `verified: true`, `draft_id`, `message_id`, and `folder_name: "Drafts"`.
2. after Exchange adapter `compose-draft`, require `server_written: true`, `verified: true`, `exchange_id`, `message_id`, and the requested font result.
3. after `compose-draft --backend artifact`, verify the returned `.eml` and `.json` paths and `mail_app_written: false`.
4. after `delete-email`, confirm the response reports a move to Trash/Deleted Items and re-list the source folder when verification matters.

if verification is ambiguous (exchange sync taking longer than expected, partial bulk delete with mixed success/failure, unsure whether the user wanted draft-only or send-now), ask the user with a bounded question rather than guessing.

## id shift recovery

mail.app integer ids can change after exchange sync. use `--message-id` (the stable RFC 2822 header) to avoid this problem entirely:

- list commands (list-emails, list-recent, list-drafts) return both `id` (integer) and `message_id` (stable string) for each email
- read, delete, move, reply, and forward commands all accept `--message-id` as the preferred identifier
- `--id` (integer) still works as a fallback for backward compatibility

if a `--message-id` lookup fails (edge case), re-list the folder:
```bash
.cursor/skills/apple-mail/scripts/mail.sh list-emails --account EMAIL --folder FOLDER
```

## content previews

when `--include-content` is used and some emails aren't in the index, the system:
1. tries to find `.emlx` files on disk (instant)
2. returns partial results if content is still missing

this is intentional: the skill never pulls full message bodies through Mail.app as a normal fallback because large HTML/inline-content messages can freeze low-memory Macs. if content is unavailable, use metadata plus the available preview, or run `build-index` before a deeper triage session.

## spotlight indexing

macos Spotlight indexes `~/Library/Mail` by default. this is redundant (the skill has its own FTS5 search index) and can cause `mds_stores` to consume 100%+ CPU indefinitely if the Spotlight index becomes corrupted.

on any new mac where this skill is used, run `fix-spotlight` during setup:

```bash
.cursor/skills/apple-mail/scripts/mail.sh fix-spotlight
```

this places a `.metadata_never_index` marker and (with sudo) adds `~/Library/Mail` to the Spotlight exclusion plist. `check-setup.sh` detects and warns if this hasn't been done.

## writing style

see `references/writing-style.md` for email composition guidelines.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Don-Yin](https://github.com/Don-Yin)
- **Source:** [Don-Yin/apple-mail](https://github.com/Don-Yin/apple-mail)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-don-yin-apple-mail-apple-mail
- Seller: https://agentstack.voostack.com/s/don-yin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.