@zhengjunyao/dsh-qqmail
A QQ Mail (and any IMAP/SMTP mailbox) plugin for DeepSeek Harness — the agent's mailbox. It registers qqmail_* agent tools that list, search, read, send, reply to, flag, move, delete and download mail over plain IMAP/SMTP, and ships two more entry points over the same core: a qqmail CLI and a qqmail-mcp stdio MCP server for other agents.
Authentication is a provider authorization code, not OAuth: enable IMAP/SMTP in the QQ Mail web console, generate a 16-character code, and paste it in. No OAuth application, no 2FA redirect, no browser round trip.
- Read tools (
qqmail_status, qqmail_config, qqmail_folders, qqmail_list, qqmail_search, qqmail_read, qqmail_attachment) are always registered.
- Write tools (
qqmail_send, qqmail_reply, qqmail_mark, qqmail_move, qqmail_delete) are not registered at all while readOnly is on (the default), so nothing can send or delete by accident.
- Deletion defaults to moving into the Trash folder. Permanent
\Deleted + EXPUNGE requires an explicit permanent: true.
- The authorization code never reaches the model: tool results and the web panel only ever show a mask.
Getting the QQ Mail authorization code
- Open QQ Mail in a browser → 设置 / Settings → 账号 / Account.
- Find IMAP/SMTP服务 → enable it (a verification step is required).
- Copy the generated 16-character authorization code.
- Configure the plugin with it:
qqmail_config email: "someone@qq.com" authCode: "<the 16-character code>"
Then verify with qqmail_status probe: true — it connects to both servers for real and reports which side failed, in plain language (a wrong password vs. a missing service toggle are different messages).
The authorization code is not your QQ password. It can be revoked in the same screen without touching your account.
Installation
# from a GitHub repo tagged with the `dsh-plugin` topic
dsh plugin --profile web add github:zhengjy01/dsh-qqmail
# or from npm
dsh plugin --profile web add @zhengjunyao/dsh-qqmail
# local development
dsh plugin --profile web add link:/path/to/dsh-qqmail
Restart dsh web afterwards; the plugin appears as the QQ 邮箱 card in Settings.
The three entry points
1. Agent tools (the main one)
Twelve qqmail_* tools, described in the system prompt so the model knows they exist:
| Tool | What it does |
|---|
qqmail_status | Config + probe: true for a real IMAP/SMTP connection check |
qqmail_config | Set address, authorization code, provider preset, switches |
qqmail_folders | List folders with message/unseen counts |
qqmail_list | Newest-first listing of a folder |
qqmail_search | Search by sender / recipient / subject / body / date / unread / flagged / size |
qqmail_read | Read one or many messages in full (batch uids is much faster) |
qqmail_attachment | Download attachment N of a message to disk |
qqmail_send | Send a message (files as attachments) |
qqmail_reply | Reply with Re:, In-Reply-To, References and a quoted original |
qqmail_mark | Read/unread, starred/unstarred |
qqmail_move | Move between folders |
qqmail_delete | Move to Trash (default) or delete permanently |
2. CLI
qqmail status --probe
qqmail folders
qqmail list --mailbox INBOX --limit 20 --unseen
qqmail search --from finance --since 2026-09-01
qqmail read 12345 12346
qqmail send --to a@b.com --subject "Hi" --text "Body" --attach ./report.pdf
qqmail reply 12345 --text "收到"
qqmail mark 12345 --seen --flag
qqmail move 12345 --to "Archive"
qqmail delete 12345
Every command accepts --json for the structured payload. The CLI reads the same <DSH_HOME>/dsh-qqmail.json, so configuring the mailbox once is enough — and QQMAIL_AUTH_CODE (or --auth-code - reading stdin) keeps the secret out of the process list.
3. MCP stdio server
For agents that cannot host a DSH plugin:
// Claude Code / Codex / any MCP client
{
"mcpServers": {
"qqmail": {
"command": "npx",
"args": ["-y", "@zhengjunyao/dsh-qqmail", "qqmail-mcp"]
}
}
}
npx @zhengjunyao/dsh-qqmail qqmail-mcp runs the server directly; bin also exposes it as qqmail-mcp. Tool schemas are generated from the same definitions the DSH tools use, so the two never drift. Only stderr carries diagnostics — stdout belongs to the JSON-RPC transport.
Write tools follow the configured readOnly switch; pass --allow-write to expose them regardless.
Configuration
Stored in <DSH_HOME>/dsh-qqmail.json (mode 0600; DSH_HOME defaults to ~/.dsh).
| Key | Default | Meaning |
|---|
preset | inferred from the address | qq / qq-exmail / 163 / 126 / gmail / outlook / custom |
email | — | Full address; also the IMAP/SMTP login |
authCode | — | Provider authorization code (the secret) |
imapHost / imapPort / imapSecure | preset | Override the IMAP endpoint |
smtpHost / smtpPort / smtpSecure | preset | Override the SMTP endpoint |
smtpRequireTls | true | Refuse to send over a non-upgraded plaintext session |
fromName / signature | '' | Display name and plain-text signature |
sentFolder | auto-detect | Where the Sent copy is appended |
downloadDir | <DSH_HOME>/dsh-qqmail/attachments | Default attachment directory |
readOnly | true | false registers the write tools |
timeoutMs | 30000 | Connect / command budget |
maxParseMb / maxSendMb | 40 | Size caps in both directions |
previewInList | false | Include a body preview in listings |
saveSent | true | Append a copy of outgoing mail to Sent |
Provider presets and their credential instructions are in src/core/presets.ts. Enterprise QQ Mail (exmail) uses a custom domain, so its preset must be selected explicitly.
Behaviour worth knowing
- Chinese search terms are filtered locally. RFC 3501
SEARCH has no charset negotiation QQ Mail honours in practice, so a Chinese keyword would come back as a silent zero-match. Those searches scan a recent window (about 400 messages) in-process and report mode: "local".
- An ASCII body search that matches nothing is re-checked locally. Non-ASCII bodies are MIME-encoded, so an ASCII word inside a Chinese body is invisible to the server. Reporting "no matches" there would be a false negative.
hasAttachments in listings is structural. ImapFlow's parsed BODYSTRUCTURE does not expose content-disposition, so the flag is derived from part types, name parameters and Content-IDs. The authoritative attachment list comes from qqmail_read.- Connections are pooled and serialized. One IMAP connection per account, commands serialized (IMAP has a single selected mailbox per connection), closed after 60 s idle; the CLI closes it immediately.
- Sent copies reuse the exact bytes that were sent, so the archived message has the same
Message-ID as the delivered one and threads correctly in other clients.
Security notes
- The authorization code is written to
<DSH_HOME>/dsh-qqmail.json with mode 0600. It is never returned by a tool, a route or the panel, and never logged.
- Write tools are absent from the registry while
readOnly is on — not merely refused at call time.
- TLS certificates are verified; the plugin does not offer an "ignore certificate errors" switch.
smtpRequireTls only exists for servers that genuinely speak plaintext (a local relay).
- Deletion is a move to Trash unless
permanent: true is passed explicitly.
Development
pnpm install
pnpm run build # tsc --noEmit declarations + tsdown + shebang/chmod postbuild
pnpm run typecheck
pnpm test # 90 unit + 68 end-to-end + 37 CLI/MCP assertions
pnpm run verify # portability gate (isolated DSH_HOME, real install)
The end-to-end suites drive the real code over real sockets against the in-process fake SMTP/IMAP servers in tests/fakes.mjs, so session pooling, envelope parsing, body-part previews, flag stores, folder moves, the Sent append and attachment download are all exercised without touching a real mailbox.
See PORTABILITY-SOP.md for the release gate this plugin is verified against.
License
MIT
