--- name: email description: > Email operations via ClawEmail CLI. Trigger on send email, check inbox, reply, forward, search mail, download attachments, or manage mailboxes. --- # ClawEmail 邮件收发 `mail-cli` is the command-line client for ClawEmail. It wraps IMAP/SMTP behind a single binary and exposes a stable JSON interface that Claude can parse reliably. This skill is designed to run **inline** (no `context: fork`) because it needs to execute shell commands directly. ## Why `--json` on every command Always append `--json`. The plain-text output is for humans; Claude needs machine-readable output to extract the message ID, subject, or body without fragile string parsing. ## Why filter the JSON before reading into context `mail-cli read body --json` returns 4500+ chars but ~63% is `headerRaw` — raw SMTP headers with DKIM signatures, routing info, spam scores, and other machine-level metadata that is useless for answering the user's question. The fields you actually need are: `id`, `from`, `to`, `subject`, `date`, `priority`, `html.content` (body), and `text` (if a plain-text body exists). **Always pipe through a filter.** This saves ~70% of tokens per call and prevents huge DKIM/signing blobs from polluting the context. ```bash mail-cli read body --id "$id" --json | jq '{ id: .data.id, from: .data.from, to: .data.to, subject: .data.subject, date: .data.date, priority: .data.priority, body: (.data.html.content // .data.text.content) }' ``` Same principle for `mail list`: you only need `id`, `from`, `subject`, `date`, and `read`. Don't pipe raw list output into context without trimming. ```bash mail-cli mail list --fid 1 --unread --limit 50 --json | jq '[.data[] | { id, from, subject, date, read }]' ``` ## Discovering the user's email Never hardcode an email address. Resolve it at runtime: ```bash mail-cli clawemail list --json # → .data.mailbox.email is the active mailbox # → .data.userEmail is the human owner's personal email ``` Use the mailbox email as the "from" identity. Use the user email as the default recipient for reports, summaries, and forwards unless the user specifies otherwise. ## Authentication Before any IMAP operation, verify the profile is authenticated: ```bash mail-cli auth test ``` If this fails with `PROFILE_NOT_FOUND` or an auth error, the user needs to run: ```bash mail-cli auth login --user @claw.163.com ``` This opens a browser for OAuth. After successful login, all subsequent commands work until the token expires. ## Folder IDs | ID | Name | |----|------------| | 1 | 收件箱 | | 2 | 草稿箱 | | 3 | 已发送 | | 4 | 已删除 | | 5 | 垃圾邮件 | | 6 | 病毒文件夹 | The inbox is folder `1`. Use numeric IDs rather than names — names are localized and will break on non-Chinese systems. ## Message IDs Message IDs look like `53:xxxxx` (base64-ish string after a colon). Extract them from `mail list` output under the `id` field. Always quote them in shell commands because they may contain characters that the shell interprets. --- ## Common Workflows These are the patterns that come up repeatedly. Use them as templates rather than inventing new command sequences. ### 1. Check inbox and report new mail The standard "what's in my inbox" flow: list, then read each one. ```bash # Step 1: List unread (filtered — only the fields you need) mail-cli mail list --fid 1 --unread --limit 50 --json | jq '[.data[] | { id, from, subject, date, read }]' # Step 2: For each message, read the body (filtered to skip headerRaw) mail-cli read body --id "53:xxxxx" --json | jq '{ id: .data.id, from: .data.from, to: .data.to, subject: .data.subject, date: .data.date, priority: .data.priority, body: (.data.html.content // .data.text.content) }' # Step 3 (only if user asks to "process" or "handle" — see below) mail-cli mail mark --ids "53:xxxxx" --fid 1 --read ``` **Why this order:** Listing first is cheap (headers only). Reading bodies is expensive. Only read bodies for messages the user actually cares about. **Step 3 is conditional — don't auto-mark as read.** "Check my inbox" or "看看收件箱" is a read-only peek. Marking as read is destructive: the user loses the "unread" signal they rely on to find messages later. Only run Step 3 when the user explicitly asks to process, handle, or mark messages (e.g. "处理一下", "帮我看看这些邮件", "标记已读"). When in doubt, ask: "要帮你标记为已读吗？" ### 2. Send a simple email ```bash mail-cli compose send \ --to "" \ --subject "Subject line" \ --body "Plain text body" ``` For HTML email, add `--html`: ```bash mail-cli compose send \ --to "" \ --subject "Subject" \ --body "

Heading

Body

" --html ``` For long bodies, write to a file first and use `--body-file ./content.txt` to avoid shell quoting nightmares. ### 3. Reply to an email ```bash mail-cli compose reply --id "53:xxxxx" --body "Your reply" ``` Use `--all` to reply-all. Use `--html` if the reply body is HTML. The original message is automatically quoted in the reply. ### 4. Forward an email ```bash # Default "quote" mode — original is inline mail-cli compose forward --id "53:xxxxx" --to "" # "attach" mode — original is an attachment mail-cli compose forward --id "53:xxxxx" --to "" --mode attach ``` Add `--body "Please see attached"` to prepend a note. ### 5. Search and filter ```bash # By keyword (matches subject + body + from) — filter for readability mail-cli mail search --fid 1 --keyword "invoice" --json | jq '[.data[] | { id, from, subject, date }]' # By date range mail-cli mail search --fid 1 --since "2026-05-01" --json | jq '[.data[] | { id, from, subject, date }]' ``` ### 6. Download attachments This is a two-step process because attachments live inside the MIME structure. ```bash # Step 1: Inspect MIME structure — only show attachment entries mail-cli read structure --id "53:xxxxx" --json | jq '[.data[] | select(.filename != null) | { partId, filename, contentType, size }]' # Step 2: Download by partId mail-cli read attachment --id "53:xxxxx" --part --out-file ./downloads/ ``` ### 7. Batch operations When processing many messages, always mark them as read *after* processing to prevent duplicate handling: ```bash # Get all unread IDs (filtered to just ids) ids=$(mail-cli mail list --fid 1 --unread --json | jq -r '.data[].id') # Process each one — filter body to skip headerRaw for id in $ids; do mail-cli read body --id "$id" --json | jq '{ id: .data.id, from: .data.from, subject: .data.subject, date: .data.date, body: (.data.html.content // .data.text.content) }' mail-cli mail mark --ids "$id" --fid 1 --read done ``` ### 8. Real-time monitoring For live notification (not polling — uses WebSocket): ```bash mail-cli mail watch --quiet ``` Outputs one NDJSON line per incoming message. Pipe to `jq` or another tool for processing. Use `--quiet` to suppress connection status on stderr. --- ## Error Handling | Error | Cause | Fix | |--------------------------------|------------------------------------------|-----------------------------------------------| | `PROFILE_NOT_FOUND` | No profile configured | `mail-cli auth login --user ` | | `OPEN_API_1022` API_KEY_INVALID | API key expired or wrong | `mail-cli auth apikey set ` | | `AUTH_EXPIRED` | OAuth token expired | Re-run `mail-cli auth login` | | Empty `data` array | No messages match criteria | Normal — not an error | | `unknown command 'read'` | Used `mail read` instead of `read body` | Use `mail-cli read body --id ` | ## Debugging ```bash mail-cli debug:config # inspect resolved config and transport mail-cli auth test # validate current profile mail-cli auth list # list all profiles and their status ``` ## Sending to the human owner When the skill needs to send a summary, report, or forward to the human user (not to a ClawEmail sub-mailbox), resolve their personal email at runtime: ```bash OWNER_EMAIL=$(mail-cli clawemail list --json | jq -r '.data.userEmail') mail-cli compose send --to "$OWNER_EMAIL" --subject "..." --body "..." ``` This avoids hardcoding personal addresses in the skill. ## Reference Index | Topic | File | Read when | |-------|------|-----------| | GitHub notification triage | [`references/github-triage.md`](references/github-triage.md) | GitHub notifications arriving on a sub-mailbox need automatic P0/P1/P2 routing, buffering, or daily summaries |

email

Install this skill

Comments