dingtalk-mail

DingTalk Email Skill

Prerequisites — Must Read Before Executing Operations

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

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

Shortcuts (preferred when there is no dedicated script/recipe)

The following shortcuts enter both the public catalog and the Runtime Schema. Route according to this skill/recipe; when matched, Shortcuts take priority over atomic commands. For parameters, only check dws schema --cli-path "mail +<shortcut>" --compact --jq '{cli_path,parameters,constraints,confirmation}' -f json; when only result is needed and has been published, check --jq '{cli_path,outcomes:.result.outcomes,pagination}'; for field-level details, then check data_schema; do not infer from Help/examples when missing. Only read the known leaf Help once when the Schema is unavailable;unknown flag correct once with the same leaf Help.unknown command Help is prohibited: erroneous suggestion → already-loaded Skill/reference explicit entry point; if neither exists, report drift. Full Catalog/root/parent/product Help is prohibited; only mapping, interface, or provenance auditing omits --compact. Only when neither the existing routing nor references can locate a low-frequency capability, use dws shortcut list --service mail --format json for discovery.

Shortcut	Risk	Applicable Scenario
dws mail +find-mail-user	read	Search mailbox 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 an email
dws mail +messages	read	Read multiple emails in the requested order and verify the identity of each one
dws mail +search-mail	read	Search emails by KQL keyword and project a list (subject/sender/time/messageId)
dws mail +thread	read	Read a complete email conversation and precisely verify the conversationId
dws mail +triage	read	List or filter email summaries, automatically resolving the 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 <邮箱> --to a@b.com --subject "<标题>" --content "<正文>" --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 "<标题>" --body "<正文>"

Standard SOP (mandatory process)

When the following intents are matched,mustexecute in the order of the corresponding SOP;prohibitedto skip steps, replace commands, or fabricate email/messageId. Each command must include --format json. Recipient emailmustbe actually resolved,prohibitedto guess.

SOP-1 Get mailbox (get-mailbox)

Trigger: my mailbox/need mailbox to send/need mailbox to check email.

1. Execute (mandatory)：dws mail mailbox list --format json, get your own email(default select enterprise mailbox type:ORG); to checksomeone else'smailbox use dws mail user search --keyword "<姓名>" --format json，prohibitedto use mailbox list check others.

Prohibited: treating mailbox list as someone else's email to look up or guess email addresses.

SOP-2 Check / search mail (search-mail)

Trigger: check mail/search mail/mail with a certain subject/mail sent by someone.

1. Get email (required): first get emailper SOP-1; skip if the user has explicitly provided it.
2. Execute (required): browse folder dws mail message list --email <邮箱> --limit <n> --format json; KQL search dws mail message search --email <邮箱> --query "<KQL>" --limit 20 --format json(KQL such as subject:周报、from:alice@x.com、folderId:2、hasAttachments:true，only pass through --query pass）。
3. Get body (required)：dws mail message get --email <邮箱> --id <messageId> --format json；messageId get from the list/search results,Prohibitedfabricating.

Prohibited: splitting KQL into multiple flags, skipping message list/search directly guessing messageId.

SOP-3 Send mail (send-mail)

Trigger: send mail/write mail/mass send.

1. Sender email (required)：dws mail mailbox list get your own email.
2. Recipient email (required): use the address directly; for a name, follow the mail.md "look up someone else's email address" process (mail user search etc.) to obtain it,Prohibitedguessing.
3. Execute (required)：dws mail message send --from <发件邮箱> --to <收件邮箱> --subject "<主题>" --content "<正文>" --format json; as needed --cc/--attachment/--inline-attachment。
4. Verify (required): get the real internetMessageIdfrom the send response, execute dws mail message verify --email <发件邮箱> --internet-message-id <internetMessageId> --format json to check the send status; do not pass an ordinary messageId to verify.

Prohibited: guessing the recipient email, or replying "sent" after sending without confirming the status.

SOP-4 Reply / forward (reply-forward)

Trigger: reply to mail/reply all/forward.

1. Get email + original mail (required): get the email per SOP-1; when the user has not provided messageId ,mustfirst go through SOP-2 to locate the original mail messageId。
2. Execute (required): reply dws mail message reply --from <邮箱> --id <messageId> --content "<正文>" --format json; for reply all use reply-all; forward dws mail message forward --from <邮箱> --to <收件邮箱> --id <messageId> --content "<附言>" --format json。

Prohibited: replying/forwarding without locating the original mail, fabricating messageId.

High-frequency hard constraints

• When the user wants "the full content/look at this mail/body",message search after a hit you must continue calling dws mail message get --email <邮箱> --id <messageId> --format json; do not stop after only listing candidates.
• When multiple mails are found, if the user gave a clear subject, attachment name, sender, or time clue, first select the best-matching one and execute message get; only ask the user when equally valid candidates cannot be distinguished.
• The attachment chain has a fixed three steps:message search → attachment list --email <邮箱> --id <messageId> → attachment download --email <邮箱> --message-id <messageId> --attachment-id <attachmentId> --name <文件名>; there is no batch download command.
• Write-type operations (send, reply, forward, delete, batch move) are confirmed according to the security policy; read-only viewing, search, attachment listing, and download do not require confirmation.
• All dws mail commands add --format json, and reuse the same mail's messageId, do not search again and cause target drift.

Trajectory high-frequency direct rules

• Commands already 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, for example inbox attachment emails:hasAttachments:true AND folderId:2; do not treat adjacent conditions as an implicit AND.
• When the user only wants the first or any single attachment, after the initial search check at most 3 candidates' attachment listby relevance, download matching attachments and stop after one local existence/size check; if none match, only state the range checked and ask whether to continue paging, and do not assert that none exist. When the user requests all/bulk attachments, iterate through all matching pages and emails, then download each attachment one by one.
• "Create mailbox contact" belongs to the mailbox personal address book and must always go through dws mail contact create/list; do not switch to dingtalk-contact. Only "resolve an email recipient address by person name" goes through the cross-product collaboration below.
• When the user asks to generate a unique title using the current time and does not specify a display format, use the compact format date +%H%M%S; only when the user explicitly requests formats such as HH:mm:ss should they be preserved as-is.
• Before bulk deleting emails or moving an entire conversation to Deleted, first show the exact target and a command preview without confirmation parameters and stop; after the user explicitly confirms, the execution flow only appends --yesto the same set of parameters. After a successful operation, do only one read-back against the original ID or unique subject, and stop once the result matches expectations.
• When a creation-type call returns messageId、contactId or internetMessageId , directly reuse the returned ID afterward; do not perform a broad list/search just to relocate the target.
• End the task after one precise read-back has proven the target state; if the read-back conflicts, report the conflict and the executed commands, and do not expand to lower-level APIs or other products to keep probing.

Cross-product collaboration

• The recipient is a person name → first use dingtalk-contact to get orgAuthEmail
• DingTalk internal messages → switch to dingtalk-chat

Local intent and short flows

• Local intent disambiguation；Short flows。