email

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Email

电子邮件

Read mail with the Spark CLI, and make every change to mail through the Gmail connector, except a draft the user asks to have in Spark. Leave what to do with an email, and when, to the user. For calendar events and free time, use

/calendar

通过 Spark CLI 读取邮件；除用户要求保存在 Spark 中的草稿外，所有邮件更改都通过 Gmail connector 完成。至于如何处理邮件以及何时处理，应由用户决定。对于日历事件和空闲时间，请使用

/calendar

。

When to read mail

何时读取邮件

List, search or read mail, through either tool, only when the user asks for an email task that needs those reads. The mailbox is private, so reading it is the user's call, not the agent's.

When mail would only help another task, such as a coding task that a thread might explain, or when a project or skill instruction says to check mail: say what you would look up and why, and read only after the user agrees.
When the task changes: the user's request covers the email task it was for. Ask again before reading mail for an unrelated task.

无论是通过哪个工具，只有当用户提出需要执行这些读取操作的电子邮件任务时，才能列出、搜索或读取邮件。邮箱是私密的，因此是否读取由用户决定，而不是 Agent 决定。

当邮件只能为其他任务提供帮助时， 例如某个邮件线程可能有助于解释一项编码任务，或项目或 skill 指令要求检查邮件：先说明你准备查找什么以及原因，得到用户同意后再读取。
当任务发生变化时： 用户最初提出的请求涵盖其对应的电子邮件任务。在为无关任务读取邮件前，再次征得用户同意。

Drafts

草稿

When the user asks for a draft without naming Gmail or Spark, such as "draft a mail to the landlord": write the text in chat. Read mail for it only when the request points at mail it needs, such as the email being answered, and ask before any other lookup.
When the user asks for the draft in Gmail or in Spark, in any wording ("save it as a Gmail draft", "put it in my Spark drafts"): save it there, with that tool only. Naming a tool allows that draft, not other changes to mail.
When the named tool can't do it, such as
```
spark draft
```
refused because Spark's access level is read-only: say so, and keep the draft in chat. Don't switch to the other tool unasked.

Every create, update or delete of a saved draft needs the user's own approval in the harness, even after they asked for the draft: a saved draft is a change in their mailbox, and one mistaken call can overwrite a draft they were writing.

/set-up-machine

's ask rows

mail-draft-write

and

mail-cli-draft

make each of these calls ask.

When the harness won't ask the user themselves, keep the draft in chat and say why. That covers Claude Code's
```
bypassPermissions
```
,
```
dontAsk
```
and
```
auto
```
modes and a non-interactive run, Codex with an automatic reviewer, Cursor and opencode in a mode that runs tools without asking, and any harness where the call doesn't ask. An automatic reviewer's approval is not the user's.

当用户要求起草邮件但未指明 Gmail 或 Spark 时， 例如“给房东起草一封邮件”：在聊天中撰写正文。只有当请求指向所需的邮件内容（如要回复的邮件）时才读取邮件，并在进行任何其他查找前征得同意。
当用户要求将草稿保存在 Gmail 或 Spark 中时， 无论使用何种措辞（“保存为 Gmail 草稿”“放到我的 Spark 草稿中”）：只使用该工具保存在那里。指明工具仅授权保存该草稿，不授权对邮件进行其他更改。
当指定工具无法完成时， 例如
```
spark draft
```
因 Spark 访问级别为只读而被拒绝：说明情况，并将草稿保留在聊天中。不要在未经要求的情况下改用另一个工具。

每次创建、更新或删除已保存的草稿，都需要在 harness 中获得用户本人明确批准，即使用户此前已经要求创建草稿：保存草稿属于对邮箱的更改，一次误操作就可能覆盖用户正在撰写的草稿。

/set-up-machine

的 ask 行

mail-draft-write

和

mail-cli-draft

会让每次此类调用都先询问。

当 harness 不会主动询问用户时， 将草稿保留在聊天中并说明原因。这包括 Claude Code 的
```
bypassPermissions
```
、
```
dontAsk
```
和
```
auto
```
模式、非交互式运行、带自动 reviewer 的 Codex、以无需询问即可运行工具的模式运行的 Cursor 和 opencode，以及任何调用不会触发询问的 harness。自动 reviewer 的批准不等同于用户批准。

Safety

安全

The user reviews and sends every email themselves, so go no further than a draft.

Within an email task, archive an email when the task calls for it. Make any other change only after the user asks for that exact change, or after you name it and they agree: a pin, a label, an undo, or a saved draft as above.

用户会亲自审阅并发送每封邮件，因此不要执行超出草稿阶段的操作。

在电子邮件任务中，如果任务要求归档邮件，可以进行归档。只有在用户明确要求该具体更改，或你说明更改内容并获得用户同意后，才进行其他更改，例如置顶、添加标签、撤销，或按上述方式保存草稿。

Gmail tools

Gmail 工具

Tools	Use
`search_threads` , `get_thread` , `get_message` , `list_labels` , `get_draft` , `list_drafts`	For an email task the user asked for.
`unlabel_thread` or `update_message_labels` removing `INBOX`	Archive freely within that task.
`label_` , `unlabel_` and `update_message_labels` for any other label, `create_label` , `update_label`	After the user asks, or agrees when you name it. Never add `TRASH` or `SPAM` , since that trashes or spams the email around the deny rules.
`create_draft` , `update_draft` , `delete_draft`	When the user asks for a Gmail draft, and each call approved by the user in the harness.
`untrash_` , `unmark__spam`	After the user asks, or agrees when you name it.
`delete_label`	Only when the user names that label to delete, since it removes the label from every email.

Claude Code's permission rules deny the rest, and a denied tool doesn't show up to be called:

```
send_message
```
, which also sends existing drafts;
```
reply
```
and
```
forward
```
;
```
trash_message
```
and
```
trash_thread
```
;
```
mark_message_spam
```
and
```
mark_thread_spam
```
;

apply_sensitive_message_label

apply_sensitive_thread_label

and

batch_apply_sensitive_thread_labels

, which can trash or spam.

Google's permission that allows archiving also allows sending, so only those deny rules stop a send.

When a denied tool can be called: the setup is incomplete. Tell the user, never call it, and make no change to mail until the deny rules are fixed.

工具	用途
`search_threads` 、 `get_thread` 、 `get_message` 、 `list_labels` 、 `get_draft` 、 `list_drafts`	用于用户要求的电子邮件任务。
`unlabel_thread` 或 `update_message_labels` 移除 `INBOX`	在该任务范围内可自由归档。
`label_` 、 `unlabel_` 、 `update_message_labels` 用于任何其他标签，以及 `create_label` 、 `update_label`	在用户要求后执行，或在你说明后获得用户同意时执行。绝不添加 `TRASH` 或 `SPAM` ，因为这样会绕过 deny 规则，将邮件移入垃圾箱或标记为垃圾邮件。
`create_draft` 、 `update_draft` 、 `delete_draft`	当用户要求 Gmail 草稿时使用，并且每次调用都须在 harness 中获得用户批准。
`untrash_` 、 `unmark__spam`	在用户要求后执行，或在你说明后获得用户同意时执行。
`delete_label`	仅当用户指明要删除的标签名称时使用，因为它会从每封邮件中移除该标签。

Claude Code 的权限规则会拒绝其余工具，被拒绝的工具不会显示为已调用：

```
send_message
```
，它也会发送现有草稿；
```
reply
```
和
```
forward
```
；
```
trash_message
```
和
```
trash_thread
```
；
```
mark_message_spam
```
和
```
mark_thread_spam
```
；

apply_sensitive_message_label

、

apply_sensitive_thread_label

和

batch_apply_sensitive_thread_labels

，它们可能会将邮件移入垃圾箱或标记为垃圾邮件。

Google 中允许归档的权限同时也允许发送，因此只有上述 deny 规则会阻止发送。

当被拒绝的工具仍可能被调用时： 说明配置不完整。告知用户，绝不调用该工具，并且在修复 deny 规则之前不对邮件做任何更改。

The two tools

两个工具

Tool	Use it for	Speed and size	Needs
Spark CLI, `spark`	Listing, searching and reading mail; Spark's categories, pins and contacts	About 0.1 s, compact tables	Spark Desktop running. Mail access is read-only on the free level.
Gmail connector, `mcp__<server-id>__<tool>`	Every change to mail but a Spark draft	About 1 s, JSON three to four times Spark's size	The connector signed in

Spark reads Spark Desktop's local copy of the mail. The Gmail connector is Google's Gmail MCP server,

gmailmcp.googleapis.com

, connected as a Claude connector.

工具	用途	速度与大小	前置条件
Spark CLI、 `spark`	列出、搜索和读取邮件；Spark 的分类、置顶项和联系人	约 0.1 秒，紧凑表格	需要运行 Spark Desktop。免费级别的邮件访问权限为只读。
Gmail connector、 `mcp__<server-id>__<tool>`	除 Spark 草稿外的所有邮件更改	约 1 秒，JSON 大小为 Spark 的 3 到 4 倍	需要 connector 已登录

Spark 读取 Spark Desktop 的本地邮件副本。Gmail connector 是 Google 的 Gmail MCP server，

gmailmcp.googleapis.com

，作为 Claude connector 接入。

How Spark's view maps to Gmail

Spark 视图与 Gmail 的对应关系

In Spark	In Gmail
Done	The `INBOX` label removed, which archives the email. Spark shows it within about a minute.
Pin	The `STARRED` label. Spark's `is:pinned` and `is:starred` return the same emails.
A folder	A Gmail label.
A category: priority, personal, invitation, notification, newsletter	Spark's own; no Gmail tool changes it.
Today, Last week, a month	Each email's date.

Spark 中	Gmail 中
`Done`	移除 `INBOX` 标签，即归档邮件。Spark 会在约一分钟后显示该状态。
`Pin`	`STARRED` 标签。Spark 的 `is:pinned` 和 `is:starred` 返回相同的邮件。
文件夹	Gmail 标签。
分类：priority、personal、invitation、notification、newsletter	Spark 自己的分类；没有 Gmail 工具可以更改它。
Today、Last week、a month	每封邮件的日期。

Flow

流程

When setting either tool up, checking the deny and ask rules, or when a call fails on sign-in or permission, follow

setup.md

Find the mail with Spark.

bash

spark emails Inbox --filter "category:priority is:unread"   # one Spark category
spark emails --filter "is:pinned"                           # pinned mail
spark search --filter 'from:<sender> newer_than:7d'         # any Gmail-style query
spark thread <id>                                           # one email in full
spark contacts --help                                       # search contacts

List with

spark emails

spark search --filter '<gmail-style query>'

spark search <topic>

returns the full bodies of up to 20 matches, often tens of thousands of tokens, so use it only when you need those bodies.

When you need a command's flags: run
```
spark <command> --help
```
.
```
spark skill
```
prints the full reference, about 13,000 tokens, so reach for it only when
```
--help
```
is not enough.

Find it again in Gmail before changing it, because the two tools number messages differently. Search with
```
search_threads
```
, using
```
from:
```
and
```
subject:
```
from the Spark row. Pass the view
```
THREAD_VIEW_METADATA_ONLY
```
when only the IDs are needed, since it keeps the answer small.
- When more than one thread matches: narrow the search with
```
after:
```
  and
```
before:
```
  around the Spark row's date, or ask the user which one they mean.

Act through Gmail: archive, or make the change the user asked for.

Change	Calls
Mark done	Add `in:inbox` to the search from step 2, then `unlabel_thread` with `["INBOX"]` . `label_thread` with `["INBOX"]` puts it back.
Pin or unpin	`label_thread` or `unlabel_thread` with `["STARRED"]` .
Label	`list_labels` for the label's ID, `create_label` when it does not exist yet, then `label_thread` with that ID.
Save a reply as a Gmail draft	Read the thread with `get_thread` , then `create_draft` with `replyToMessageId` set to the last message's `id` .

Call

get_thread

with

messageFormat: PLAIN_TEXT

, since it keeps the thread small.

For any change but archiving that the user hasn't asked for: name it and wait for their answer.
For a saved draft: end with its
```
viewUrl
```
, where the user reviews and sends it.
For a draft the user asked to have in Spark: run
```
spark draft
```
as a command of its own, so the user approves that call alone, and tell the user where Spark shows the draft.

Check that each change took.
- After marking done: the
```
in:inbox
```
  search returns
```
{}
```
  once the email is archived.

设置任一工具、检查 deny 和 ask 规则，或调用因登录或权限问题失败时，请遵循 setup.md。

使用 Spark 查找邮件。

bash

spark emails Inbox --filter "category:priority is:unread"   # one Spark category
spark emails --filter "is:pinned"                           # pinned mail
spark search --filter 'from:<sender> newer_than:7d'         # any Gmail-style query
spark thread <id>                                           # one email in full
spark contacts --help                                       # search contacts

使用

spark emails

列出邮件，或使用

spark search --filter '<gmail-style query>'

搜索。

spark search <topic>

最多返回 20 条匹配结果的完整正文，通常会占用数万 token，因此仅在需要这些正文时使用。

需要查看某个命令的标志时： 运行
```
spark <command> --help
```
。
```
spark skill
```
会打印完整参考资料，约 13,000 token，因此仅在
```
--help
```
信息不足时使用。

更改前，先在 Gmail 中再次找到该邮件， 因为两个工具对消息的编号方式不同。使用
```
search_threads
```
搜索，并传入 Spark 行中的
```
from:
```
和
```
subject:
```
。只需要 ID 时，传入视图
```
THREAD_VIEW_METADATA_ONLY
```
，这样可减小响应。
- 当匹配到多个线程时： 使用 Spark 行中邮件日期前后的
```
after:
```
  和
```
before:
```
  缩小搜索范围，或询问用户指的是哪一封。

通过 Gmail 执行操作： 归档邮件，或进行用户要求的更改。

更改	调用
标记为完成	在第 2 步的搜索中添加 `in:inbox` ，然后使用 `unlabel_thread` 并传入 `["INBOX"]` 。使用 `label_thread` 并传入 `["INBOX"]` 可将其恢复到收件箱。
置顶或取消置顶	使用 `label_thread` 或 `unlabel_thread` 并传入 `["STARRED"]` 。
添加标签	使用 `list_labels` 获取标签 ID；如果尚不存在则使用 `create_label` ，然后使用 `label_thread` 传入该 ID。
将回复保存为 Gmail 草稿	使用 `get_thread` 读取线程，然后使用 `create_draft` 并将 `replyToMessageId` 设置为最后一条消息的 `id` 。

调用

get_thread

时使用

messageFormat: PLAIN_TEXT

，因为这样可以保持线程内容精简。

对于用户未要求的、归档以外的更改： 说明更改内容并等待用户答复。
对于已保存的草稿： 最后输出其
```
viewUrl
```
，用户可在该页面审阅和发送。
对于用户要求保存在 Spark 中的草稿： 将
```
spark draft
```
作为独立命令运行，让用户只批准该次调用，并告知用户 Spark 中显示草稿的位置。

检查每项更改是否生效。
- 标记为完成后： 邮件归档后，
```
in:inbox
```
  搜索会返回
```
{}
```
  。

References

参考资料

setup.md: setting up Spark and the Gmail connector, the deny and ask rules, and checking each part.

setup.md：设置 Spark 和 Gmail connector、deny 和 ask 规则，以及检查各部分。