DingTalk Email Skill

Prerequisites — Read before performing any operation

CRITICAL — Before executing any
dws
operation, you MUST first use the Read tool to fully read
dingtalk-shared
. This lightweight file contains the global execution contract, security baseline, and on-demand loading navigation for shared references; do not pre-load all its references.

Command reference: mail.md. For multi-step email scenarios such as complex search, attachments, batch processing, drafts, see: 09-mail.md.

Shortcuts (preferred when no dedicated script/recipe exists)

The following shortcuts enter both the public catalog and Runtime Schema. Route according to this skill/recipe; when matched, Shortcuts take precedence over atomic commands. For parameters, only query

dws schema --cli-path "mail +<shortcut>" --compact --jq '{cli_path,parameters,constraints,confirmation}' -f json

; when only the published

result

is needed, query

--jq '{cli_path,outcomes:.result.outcomes,pagination}'

, and for field-level details query

data_schema

; do not infer missing parts from Help or examples. Only read a known leaf Help once when the Schema is unavailable; fix an

unknown flag

once with the same leaf Help.

unknown command

forbids Help: wrong suggestion → use the explicit entry in the loaded Skill/reference; if neither exists, report drift. Forbid full Catalog/root/parent/product Help; omit

--compact

only for mapping, interface, or provenance audits. When existing routes and references cannot locate a low-frequency capability, use

dws shortcut list --service mail --format json

to discover.

Shortcut	Risk	Use case
`dws mail +find-mail-user`	read	Search email contacts by keyword and project a list (name/nickname/email/employee ID, etc.)
`dws mail +folder-list`	read	List top-level folders or subfolders under a specified parent folder
`dws mail +message`	read	Read the full body and attachment metadata of one email
`dws mail +messages`	read	Read multiple emails in the requested order and verify identity one by one
`dws mail +search-mail`	read	Search emails by KQL keywords and project a list (subject/sender/time/messageId)
`dws mail +thread`	read	Read the full email conversation and precisely verify conversationId
`dws mail +triage`	read	List or filter email summaries, automatically resolve mailbox and inbox
`dws mail +user-search`	read	Search mailbox users by keyword or employee ID (enterprise mailbox only)

Intent Table

User says	Command
"Send email to a@b.com"	`dws mail mailbox list --format json` → `dws mail message send --from <mailbox> --to a@b.com --subject "<subject>" --content "<body>" --format json`
"Reply / Reply all / Forward"	`dws mail message reply` / `reply-all` / `forward`
"Today's unread emails"	`python scripts/mail_unread_summary.py`
"Send with CC"	`python scripts/mail_send_with_cc.py --to a@b.com --cc c@d.com --subject "<subject>" --body "<body>"`

Standard SOP (Mandatory Process)

When the following intents are matched, you must execute them in the corresponding SOP order; do not skip steps, replace commands, or fabricate email/messageId. Every command must include
--format json
. The recipient mailbox must be actually resolved; do not guess.

SOP-1 Get Mailbox (get-mailbox)

Trigger: my mailbox / sending needs a mailbox / checking email needs a mailbox.

Execute (required):
```
dws mail mailbox list --format json
```
, get your own
```
email
```
(default to enterprise mailbox
```
type:ORG
```
); use
```
dws mail user search --keyword "<name>" --format json
```
to look up other users' mailboxes; do not use
```
mailbox list
```
to look up others.

Forbidden: use

mailbox list

as a query for others' mailboxes, or guess email addresses.

SOP-2 View / Search Email (search-mail)

Trigger: view emails / search emails / emails on a topic / emails from someone.

Get mailbox (required): first obtain
```
email
```
per SOP-1; may skip if the user explicitly provided it.

Execute (required): browse folders

dws mail message list --email <mailbox> --limit <n> --format json

; KQL search

dws mail message search --email <mailbox> --query "<KQL>" --limit 20 --format json

(KQL examples:

subject:weekly report

from:alice@x.com

folderId:2

hasAttachments:true

; only pass via
--query
).

Get body (required):

dws mail message get --email <mailbox> --id <messageId> --format json

; take

messageId

from the list/search results, do not fabricate.

Forbidden: split KQL into multiple flags, skip

message list/search

and guess messageId directly.

SOP-3 Send Email (send-mail)

Trigger: send email / write email / mass send.

Sender mailbox (required): get your own mailbox via
```
dws mail mailbox list
```
.
Recipient mailbox (required): use the address directly; for names, obtain the address per the "find other's email address" flow in mail.md (via
```
mail user search
```
etc.); do not guess.

Execute (required):

dws mail message send --from <sender mailbox> --to <recipient mailbox> --subject "<subject>" --content "<body>" --format json

; add

--cc

--attachment

--inline-attachment

as needed.

Verify (required): get the real

internetMessageId

from the send response, run

dws mail message verify --email <sender mailbox> --internet-message-id <internetMessageId> --format json

to check the sending status; do not pass a normal

messageId

to verify.

Forbidden: guess the recipient mailbox, or reply "sent" without confirming the status after sending.

SOP-4 Reply / Forward (reply-forward)

Trigger: reply to email / reply all / forward.

Get mailbox + original email (required): get mailbox via SOP-1; if the user did not provide a
```
messageId
```
, you must first locate the original email's
```
messageId
```
via SOP-2.

Execute (required): reply

dws mail message reply --from <mailbox> --id <messageId> --content "<body>" --format json

; use

reply-all

for reply all; forward

dws mail message forward --from <mailbox> --to <recipient mailbox> --id <messageId> --content "<note>" --format json

Forbidden: reply/forward without locating the original email, or fabricate messageId.

High-Frequency Hard Constraints

When the user asks for "full content / view this email / body", after a
```
message search
```
hit you must continue to call
```
dws mail message get --email <mailbox> --id <messageId> --format json
```
; do not stop after listing candidates.
When multiple emails are found, if the user gave a clear subject, attachment name, sender, or time clue, first select the best match and run
```
message get
```
; only ask the user when equally matching candidates cannot be distinguished.

The attachment chain is fixed in three steps:

message search

→

attachment list --email <mailbox> --id <messageId>

→

attachment download --email <mailbox> --message-id <messageId> --attachment-id <attachmentId> --name <filename>

; there is no batch download command.

Write operations (send, reply, forward, delete, batch move) require confirmation per security policy; read-only views, searches, attachment listings, and downloads do not require confirmation.
Add
```
--format json
```
to all
```
dws mail
```
commands, and reuse the same email's
```
messageId
```
; do not re-search causing target drift.

High-Frequency Direct Access Rules

For commands precisely covered by this page or
```
09-mail.md
```
, execute directly; do not first probe
```
contact
```
,
```
api
```
,
```
auth
```
,
```
profile
```
, Help, or Schema. Only after the command actually reports a parameter error, read that command's leaf Help once.
Multi-condition KQL must use explicit
```
AND
```
, e.g., inbox emails with attachments:
```
hasAttachments:true AND folderId:2
```
; do not treat adjacent conditions as implicit AND.
When the user only wants the first or any single attachment, after the initial search check at most 3 candidates'
```
attachment list
```
by relevance, download the hit attachment, do a local existence/size check, then stop; if none hit, only state the checked scope and ask whether to continue paging; do not assert it does not exist. When the user asks for all/batch attachments, traverse all matching pages and emails, then download each attachment one by one.
"Create mailbox contact" belongs to the mailbox personal address book; always use
```
dws mail contact create/list
```
, do not switch to
```
dingtalk-contact
```
. Only "resolve email recipient address by person name" uses the cross-product collaboration below.
When the user requires generating a unique title with the current time and no display format is specified, use the compact format
```
date +%H%M%S
```
; only preserve formats like
```
HH:mm:ss
```
when the user explicitly requests them.
Before batch-deleting emails or moving an entire conversation to deleted, first show the precise targets and a command preview without the confirmation parameter, then stop; after the user explicitly confirms, the execution flow appends
```
--yes
```
to the same set of parameters only. After the operation succeeds, do a single readback targeting the original ID or unique subject; stop when the result matches expectations.
When a create-type operation returns
```
messageId
```
,
```
contactId
```
, or
```
internetMessageId
```
, subsequently reuse the returned ID directly; do not do broad list/search to re-locate the target.
End the task after one precise readback has proven the target state; if the readback conflicts, report the conflict and executed commands; do not expand to lower-level APIs or other products to continue probing.

Cross-Product Collaboration

Recipient is a person name → first use
```
dingtalk-contact
```
to get
```
orgAuthEmail
```
DingTalk internal messages → switch to
```
dingtalk-chat
```

Local Intents and Mini-Flows

Local intent disambiguation; mini-flows.

dingtalk-mail

NPX Install

Tags

SKILL.md Content (Chinese)