email

メール

Spark CLI でメールを読み、メールへの変更はすべて Gmail コネクターを通じて行います。ただし、ユーザーが Spark で作成するよう依頼した下書きは除きます。メールに何をするか、いつするかはユーザーに委ねます。カレンダーの予定や空き時間については、/calendar を使用します。

メールを読む場合

ユーザーから、メールを読む必要のあるメール関連タスクを依頼された場合に限り、どちらかのツールを使ってメールを一覧表示、検索、または閲覧します。メールボックスはプライベートなものなので、メールを読むかどうかはエージェントではなくユーザーが決めます。

• メールが別のタスクに役立つだけの場合、 たとえば、スレッドの内容がコーディングタスクの参考になる場合や、プロジェクトまたはスキルの指示でメールを確認するよう求められている場合は、何をどのような理由で確認するかを伝え、ユーザーの同意を得てからメールを読みます。
• タスクが変わった場合： ユーザーの依頼が対象とするのは、その依頼に含まれるメールタスクです。関連のないタスクのためにメールを読む場合は、あらためて確認します。

下書き

• ユーザーが Gmail または Spark を指定せずに下書きを依頼した場合、 たとえば「大家さんにメールの下書きを書いて」のような依頼では、チャットに文章を書きます。返信対象のメールなど、依頼でメールの参照が必要と示されている場合に限り、そのためにメールを読みます。それ以外のメールを確認する場合は、事前に確認します。
• ユーザーが Gmail または Spark で下書きを作成するよう依頼した場合、 「Gmail の下書きとして保存して」や「Spark の下書きに入れて」のような言い方を含め、指定されたツールだけを使ってそこに保存します。ツールの指定が許可するのはその下書きの作成だけであり、メールへのほかの変更は許可されません。
• 指定されたツールで作成できない場合、 たとえば Spark のアクセスレベルが読み取り専用のため spark draft が拒否された場合は、その旨を伝えて、下書きはチャットに残します。依頼されていない別のツールに切り替えてはいけません。

保存済みの下書きを新規作成、更新、または削除する操作には、ユーザーが下書きを依頼した後であっても、毎回ハーネス内でユーザー本人の承認が必要です。保存済みの下書きはユーザーのメールボックスに変更を加えるものであり、誤った呼び出しを一度行うだけで、作成中の下書きを上書きする可能性があるためです。/set-up-machine の確認行 mail-draft-write と mail-cli-draft により、これらの呼び出しは毎回確認を求めます。

• ハーネスがユーザー本人に確認を求めない場合、 下書きはチャットに残し、その理由を伝えます。自動レビュアーの承認は、ユーザー本人の承認ではありません。次のハーネスは確認を求めません。
  • Claude Code： bypassPermissions、dontAsk、auto モード、および非対話型の実行。
  • Codex： 自動レビュアーを使用する実行。
  • Cursor と opencode： 確認なしでツールを実行するモード。
  • その他のハーネス： 呼び出し時に確認を求めないもの。

安全性

メールの確認と送信はすべてユーザー自身が行うため、下書きの作成までにとどめます。

メール関連タスクの中で、タスクにアーカイブが含まれている場合は、メールをアーカイブします。それ以外の変更は、ユーザーからその変更を明確に依頼された場合、または変更内容を伝えてユーザーの同意を得た場合に限り行います。対象となるのは、ピン留め、ラベル付け、元に戻す操作、および上記の保存済み下書きです。

Gmail ツール

ツール	用途
search_threads、get_thread、get_message、list_labels、get_draft、list_drafts	ユーザーから依頼されたメール関連のタスクに使用します。
unlabel_thread または INBOX を削除する update_message_labels	そのタスクの範囲内であれば、自由にアーカイブできます。
それ以外のラベルに対する label_*、unlabel_*、update_message_labels、create_label、update_label	ユーザーから依頼された後、またはラベル名を伝えてユーザーが同意した後に使用します。メールをゴミ箱に移動したり迷惑メールとして処理したりするため、TRASH や SPAM は絶対に追加しないでください。
create_draft、update_draft、delete_draft	ユーザーから Gmail の下書きを依頼されたときに使用します。また、呼び出しごとにハーネスでユーザーの承認が必要です。
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 の権限は、送信も許可します。そのため、送信を止めるのはこれらの拒否ルールだけです。

• 拒否されたツールが呼び出せる場合： 設定が不完全です。ユーザーに伝え、絶対に呼び出さないでください。拒否ルールが修正されるまで、メールに変更を加えないでください。

2 つのツール

ツール	用途	速度とサイズ	必要条件
Spark CLI、spark	メールの一覧表示、検索、閲覧、Spark のカテゴリ、ピン、連絡先	約 0.1 秒、コンパクトなテーブル	Spark Desktop が起動していること。無料プランではメールへのアクセスは読み取り専用です。
Gmail コネクター、mcp__<server-id>__<tool>	Spark の下書き以外の、メールに対するすべての変更	約 1 秒、JSON のサイズは Spark の 3～4 倍	コネクターにサインインしていること

Spark は、Spark Desktop にあるメールのローカルコピーを読み取ります。Gmail コネクターは、Claude コネクターとして接続された、Google の Gmail MCP サーバー gmailmcp.googleapis.com です。

Spark の表示と Gmail の対応

Spark	Gmail
完了	INBOX ラベルが削除され、メールがアーカイブされます。Spark には約 1 分以内に反映されます。
ピン	STARRED ラベルです。Spark の is:pinned と is:starred は、同じメールを返します。
フォルダー	Gmail のラベルです。
カテゴリ：優先、個人、招待、通知、ニュースレター	Spark 独自のカテゴリで、Gmail のツールでは変更されません。
今日、先週、1 か月	各メールの日付です。

手順

いずれかのツールをセットアップする場合、deny ルールと ask ルールを確認する場合、またはサインインや権限に関するエラーで呼び出しに失敗した場合は、setup.md に従ってください。

1. Spark でメールを検索します。

   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 件の一致するメールの本文全体を返すため、数万トークンになることもあります。本文が必要な場合にのみ使用してください。

   • コマンドのフラグを確認する場合： spark <command> --help を実行してください。spark skill は約 13,000 トークンの完全なリファレンスを出力するため、--help では不十分な場合にのみ使用してください。

2. 変更する前に、Gmail でもう一度検索してください。2 つのツールではメッセージの番号が異なるためです。Spark の行にある from: と subject: を使い、search_threads で検索します。ID だけが必要な場合は、回答を小さく保てる THREAD_VIEW_METADATA_ONLY ビューを渡してください。

   • 一致するスレッドが複数ある場合： Spark の行の日付の前後に after: と before: を付けて検索を絞り込むか、どれを指しているのかユーザーに確認してください。

3. Gmail を通じて操作します。アーカイブするか、ユーザーが依頼した変更を行います。

   変更	呼び出し
   完了としてマーク	手順 2 の検索に in:inbox を追加し、unlabel_thread に ["INBOX"] を渡します。label_thread に ["INBOX"] を渡すと、受信トレイに戻ります。
   ピン留めまたは解除	label_thread または unlabel_thread に ["STARRED"] を渡します。
   ラベルを付ける	ラベルの ID を list_labels で取得し、まだ存在しない場合は create_label で作成してから、その ID を指定して label_thread を呼び出します。
   返信を Gmail の下書きとして保存	get_thread でスレッドを読み込み、replyToMessageId に最後のメッセージの id を設定して create_draft を呼び出します。

   スレッドを小さく保てるよう、messageFormat: PLAIN_TEXT を指定して get_thread を呼び出してください。

   • ユーザーが依頼していない変更（アーカイブを除く）： 変更内容を伝え、ユーザーの返答を待ってください。
   • 保存した下書きの場合： ユーザーが確認して送信できるよう、最後に viewUrl を伝えてください。
   • Spark に下書きを作成するようユーザーが依頼した場合： ユーザーがその呼び出しだけを承認できるよう、spark draft を単独のコマンドとして実行し、Spark のどこに下書きが表示されるかを伝えてください。

4. 確認します。各変更が反映されたことを確認してください。

   • 完了としてマークした後： メールがアーカイブされると、in:inbox の検索結果は {} になります。

参考資料

• setup.md：Spark と Gmail コネクタのセットアップ、deny ルールと ask ルール、および各項目の確認方法を説明しています。