qqmail-organizer

name

qqmail-organizer

description

Agent-facing QQ Mail inbox management over IMAP/SMTP for OpenClaw, Hermes, and other autonomous agents. Use when an agent must read, search, reply to, classify, organize, archive, mark read/unread, or safely clean up a QQ Mail inbox while preserving explicit dry-run/approval boundaries. Especially useful for agentic inbox triage, non-mutating cleanup plans, rule-based organization, newsletter/marketing/GitHub notification sorting, and avoiding accidental destructive email operations.

QQMail Organizer

Agent Contract

Use this skill as an execution protocol for agents, not as a human walkthrough. The agent should operate the bundled scripts, summarize results, preserve safety boundaries, and avoid exposing credentials or unnecessary private email content.

Core behavior:

• Prefer deterministic script calls over hand-written IMAP/SMTP snippets.
• Prefer --json for parent-agent orchestration when using plan-organize or auto-organize.
• Treat plan-organize and default auto-organize as safe read-only planning.
• Treat --apply, archive without --dry-run, mark-* without --dry-run, send without --dry-run, reply without --dry-run, and delete as mutations.
• Require explicit user approval before destructive or externally visible actions.
• Report concise summaries, matched counts, categories, and proposed actions instead of dumping full inbox content.

Credentials are read only from environment variables:

• QQMAIL_USER: QQ email address.
• QQMAIL_AUTH_CODE: QQ Mail IMAP/SMTP authorization code, not the account password.

Never print, persist, or place QQMAIL_AUTH_CODE in prompts, reports, cron jobs, memory, commits, or rule files.

Decision Protocol

1. For "look at my mail", "what is important", "clean my inbox", or ambiguous organization requests, start with:

python3 scripts/qqmail.py plan-organize --limit 50 --json

2. For rule-based cleanup, preview first. This is dry-run by default:

python3 scripts/qqmail.py auto-organize --limit 100 --json

3. Apply only after the user explicitly confirms the rule/action set:

python3 scripts/qqmail.py auto-organize --limit 100 --apply

4. For a specific requested move, mark, send, or reply, run a narrow command. Use --dry-run first for bulk move/mark/delete operations.

5. For permanent deletion, do not infer intent. Ask or require explicit wording such as "delete permanently".

Output Protocol

When reporting to a user or parent agent:

• State whether the operation was read-only, dry-run, or applied.
• Group results by category or action.
• Include sender, subject, date, and count. Avoid full body content unless the user asks to read a specific message.
• For parent agents, parse --json output instead of scraping human-readable text.
• For dry-run cleanup, list the exact actions that would occur and the command needed to apply them.
• If credentials, IMAP, or SMTP fail, report the failing boundary without printing secrets.

Commands For Agents

Read and inspect:

python3 scripts/qqmail.py folders
python3 scripts/qqmail.py inbox --limit 20
python3 scripts/qqmail.py inbox --unread --limit 20
python3 scripts/qqmail.py read --index 1
python3 scripts/qqmail.py search --from "[e-mail]"
python3 scripts/qqmail.py search --subject "keyword" --since "2026-06-01"

Send and reply:

python3 scripts/qqmail.py send --to "[e-mail]" --subject "Hello" --body "Message" --dry-run
python3 scripts/qqmail.py send --to "[e-mail]" --subject "Hello" --body "Message"
python3 scripts/qqmail.py reply --index 1 --body "Reply text" --dry-run
python3 scripts/qqmail.py reply --index 1 --body "Reply text"

Organize safely:

python3 scripts/qqmail.py plan-organize --limit 50 --json
python3 scripts/qqmail.py auto-organize --limit 100 --json
python3 scripts/qqmail.py mkdir "GitHub"
python3 scripts/qqmail.py archive --from "[e-mail]" --target "GitHub" --dry-run
python3 scripts/qqmail.py mark-read --index 1 --dry-run
python3 scripts/qqmail.py mark-unread --from "[e-mail]" --dry-run

Delete is available but should be used only after explicit user confirmation:

python3 scripts/qqmail.py delete --index 1 --dry-run
python3 scripts/qqmail.py delete --index 1 --confirm-delete DELETE

Rules

Rule-based organization uses rules.agent.json by default. This default policy intentionally contains no rules, so packaged skill behavior never archives, marks, or moves mail based on public sample preferences. Agents should generate or select an explicit --rules /path/to/rules.json only after the user has approved the mailbox policy.

Use rules.schema.json as the machine-readable contract for generated policy files. The script also validates rules before planning or applying them.

Rules support matching by sender, subject, or inferred category, and actions such as:

• archive: copy to a target folder, then remove from source.
• mark-read: add the Seen flag.
• mark-unread: remove the Seen flag.
• review: classify only, do not mutate.

For personalized cleanup, write a private rules file outside the public skill repo and call:

python3 scripts/qqmail.py validate-rules --rules /path/to/rules.json --json
python3 scripts/qqmail.py auto-organize --rules /path/to/rules.json --limit 100 --json
python3 scripts/qqmail.py auto-organize --rules /path/to/rules.json --limit 100 --apply --json

Only run the --apply command after the user approves the exact action set from the dry-run JSON.

Safety Policy For Agent Runtimes

• Prefer plan-organize before any mutation.
• Use --dry-run for manual archive, delete, and mark operations before applying.
• auto-organize is dry-run unless --apply is present.
• Use send --dry-run and reply --dry-run before externally visible messages unless the user already approved the exact content.
• delete refuses to run without --confirm-delete DELETE; still require explicit user approval first.
• Never run delete unless the user explicitly asks for permanent deletion.
• Never create automatic reply, delete, or archive cron jobs without explicit user confirmation.
• Do not log or commit QQ Mail authorization codes.
• Do not use this skill as a background auto-responder without a human-approved policy.
• Do not treat marketing/newsletter classification as permission to delete.