docs(mail): document user sender allow/block commands

[infeng]

Updates the mail command documentation with user sender allow and block workflows.

• Added command references and examples for allow sender operations.
• Added matching block sender coverage, including batch operations.
• Clarified request fields, options, and expected output for these commands.

Summary by CodeRabbit

• New Features

  • Expanded mail workflow guidance with clearer recipient selection, send confirmation, scheduled send handling, template merging, and sender allow/block list management.
  • Added more shortcuts and improved support for safer HTML-based drafting and review.

• Bug Fixes

  • Strengthened safeguards for sending email by treating content as untrusted, requiring confirmation for sensitive actions, and improving post-send status checks.
  • Clarified rules to avoid invalid IDs, incorrect recipient handling, and unsafe raw message creation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4133eba0-0bab-40ea-b0ff-eba06811eab0

📥 Commits

Reviewing files that changed from the base of the PR and between 4c31323 and ca23dfd.

📒 Files selected for processing (1)

• skills/lark-mail/SKILL.md

---

📝 Walkthrough

Walkthrough

skills/lark-mail/SKILL.md is substantially rewritten (+506/−41 lines): it adds safety contracts (user confirmation before sends, no fabricated IDs, forbidden raw EML), expands recipient search, send/recall flows, HTML lint rules, template merge semantics, allow/block sender list APIs, a full API Resources reference, and a permissions scope table.

Changes

lark-mail SKILL.md Rewrite

Layer / File(s)	Summary
Skill metadata, prerequisites, and core concepts skills/lark-mail/SKILL.md	Description text broadened, precondition updated to require reading ../lark-shared/SKILL.md, and a new Rule concept bullet added.
Typical workflow and -h discovery rules skills/lark-mail/SKILL.md	Workflow list rewritten; "常用操作速查" replaced with a CRITICAL section mandating -h before any command and forbidding parameter guessing.
Recipient search flow skills/lark-mail/SKILL.md	New section defines supported query types, candidate filtering and listing rules, disambiguation fields, no-match behavior, and direct email address bypass.
Send preconditions, shared mailbox/alias, delivery status, and recall skills/lark-mail/SKILL.md	Adds required confirmation before sending, --send-time/--confirm-send constraints, --mailbox/--from usage for shared mailboxes and aliases, send_status post-send checks, cancel_scheduled_send, and async recall with progress querying.
IM sharing, calendar invites, HTML format, style rules, and lint contracts skills/lark-mail/SKILL.md	Expands IM sharing prerequisites, calendar invite parameters, HTML-first defaults, adds concrete email style rules, explicitly forbids hand-building raw EML via drafts.create, and documents automatic HTML lint/auto-fix on write paths with +lint-html for preview.
Template merge rules and raw API discovery skills/lark-mail/SKILL.md	Adds template creation/update, slot merge/override precedence, recipient de-duplication warnings in reply scenarios, size limits, and reinforces raw API -h/schema-first discovery.
Allow/block sender lists and shortcuts table skills/lark-mail/SKILL.md	New section documents user_mailbox.allow_sender/user_mailbox.blocked_sender APIs, required scopes, and batch create/remove command shapes; shortcuts table gains +draft-send and per-entry usage notes.
API Resources listing and permissions table skills/lark-mail/SKILL.md	Full API Resources reference added covering all mail resource/method pairs; permissions table expanded with scope requirements through user_mailbox.blocked_sender.*.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• larksuite/cli#749: Adds the same core mail-skill safety contracts around no fabricated IDs and requiring user confirmation before destructive writes.
• larksuite/cli#1527: Edits the same SKILL.md in overlapping sections: lark-shared prereq, -h usage, +message vs +messages, and raw API guidance.
• larksuite/cli#1261: Updates guidance on single vs multi-message read routing between +message and +messages, overlapping with the reading-command clarifications here.

Suggested labels

documentation

Suggested reviewers

• chanthuang

🐇 A hop through the inbox, rules crisp and bright,
HTML lint checks keep the raw EML out of sight.
Confirm before sending, no IDs to fake,
Block lists and shortcuts — what progress we make!
The rabbit stamps docs with a satisfied thump. ✉️

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately describes the main documentation change about user sender allow/block commands.
Description check	✅ Passed	The description covers the summary and main changes, but it omits the template's Test Plan and Related Issues sections.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@ca23dfdfe3b2c2ae9846857857d1946b0cb01682

🧩 Skill update

npx skills add infeng/cli#feat/24e1c62 -y -g

[github-actions]

PR Quality Summary

CI did not complete successfully. Use the failed check links below to decide whether this PR needs a code change or a rerun.

Failed checks

• deterministic-gate — failure — details
• results — failure — details

deterministic-gate

• skill_command_reference — skills/lark-mail/SKILL.md:514 — example references unknown command "mail user_mailbox.allow_sender list" — Action: update the example to use a command present in the command manifest
• skill_command_reference — skills/lark-mail/SKILL.md:517 — example references unknown command "mail user_mailbox.blocked_sender list" — Action: update the example to use a command present in the command manifest
• skill_command_reference — skills/lark-mail/SKILL.md:524 — example references unknown command "mail user_mailbox.allow_sender batch_create" — Action: update the example to use a command present in the command manifest
• skill_command_reference — skills/lark-mail/SKILL.md:528 — example references unknown command "mail user_mailbox.blocked_sender batch_create" — Action: update the example to use a command present in the command manifest
• skill_command_reference — skills/lark-mail/SKILL.md:532 — example references unknown command "mail user_mailbox.blocked_sender batch_remove" — Action: update the example to use a command present in the command manifest
• public_content_jwt_like_token — skills/lark-mail/SKILL.md:732 — public contribution contains a JWT-like token — Action: remove the value from the public contribution and replace it with a non-sensitive placeholder
• public_content_jwt_like_token — skills/lark-mail/SKILL.md:748 — public contribution contains a JWT-like token — Action: remove the value from the public contribution and replace it with a non-sensitive placeholder
• public_content_jwt_like_token — skills/lark-mail/SKILL.md:749 — public contribution contains a JWT-like token — Action: remove the value from the public contribution and replace it with a non-sensitive placeholder
• public_content_jwt_like_token — skills/lark-mail/SKILL.md:751 — public contribution contains a JWT-like token — Action: remove the value from the public contribution and replace it with a non-sensitive placeholder
• public_content_jwt_like_token — skills/lark-mail/SKILL.md:752 — public contribution contains a JWT-like token — Action: remove the value from the public contribution and replace it with a non-sensitive placeholder