Google Workspace CLI で Gmail の受信トレイを自動整理する

—
name: gmail-labeler
description: gws CLI を使って Gmail の受信メール(調査期間はユーザーに確認、デフォルト直近1ヶ月)を分析し、適切なラベル体系を設計したうえで「フィルタ」を作成して今後のメールも自動で振り分けられるようにする。
disable-model-invocation: true
—

# Gmail ラベル・フィルタ整理スキル

受信メールを `gws` CLI で分析し、ラベル体系を設計して **Gmail フィルタを作成する**スキル。
ポイントは「その場の一括ラベル付け」で終わらせず、フィルタによって**今後届くメールも自動で振り分けられる仕組み**を作ること。

目的は「メールを溜めがちな人が重要なメールを見落とさないようにする」こと。設計判断はすべてここから導く:

– **機械的な通知メールはフィルタで自動振り分けし、人が読むべきメールだけが残る**状態を目指す。
– **個別メールはフィルタの対象にしない。** 誤って自動処理されると見落としに直結する。判断に迷うものは対象外にする。
– **適用前に必ず設計案をユーザーに見せて承認を得る。** フィルタは今後のメール全部に効き続ける設定変更なので、一括ラベル付けより影響が大きい。

## 前提

`gws` CLI(Google Workspace CLI)が**インストール済みかつ認証済み**であること。

– **利用可否の確認**: まず `command -v gws`(または `gws –version`)で CLI が存在するか確認する。見つからない場合は、それ以上進めずユーザーにインストールを促して停止する。
– **認証の確認**: 続いて `gws gmail users labels list –params ‘{“userId”: “me”}’` を実行する。認証エラー(exit code 2)の場合はユーザーに認証設定を依頼して停止する。

## ワークフロー

### 1. 調査期間の確認

**直近の何ヶ月分を調査するかをユーザーに確認する。** 回答がなければデフォルトで**直近1ヶ月**とする。

以降のクエリ(手順3)の `newer_than` をこの期間に合わせる(例: 3ヶ月なら `newer_than:90d`、1ヶ月なら `newer_than:30d`)。期間が長いほど取得件数が増えるため、`–max` も適宜引き上げる。

### 2. 現状把握 — ラベルとフィルタの両方を読む

“`bash
gws gmail users labels list –params '{"userId": "me"}'
gws gmail users settings filters list –params '{"userId": "me"}'
“`

– ラベルは `type: “user”` のものが既存の分類体系。**名前と ID の対応を控える**(以降の API はすべて ID を要求する)。
– **既存フィルタはユーザーの運用ルールそのもの。** 新しく作るフィルタはこれに倣う。読み取るべき点:
– 条件の書き方(`from:` ベースか、`list:` ベースか、`query` か)
– アクションの流儀(ラベル付与のみか、`removeLabelIds: [“INBOX”]` で受信トレイをスキップするか、`UNREAD` も外すか)
– ラベルの粒度(サービス単位か、プロジェクト単位か)
– 既存フィルタが1つもない場合は、保守的なデフォルト(ラベル付与のみ、受信トレイには残す)から始め、受信トレイをスキップするか、既読にするかはユーザーに聞く。

### 3. 受信メールを分析

手順1で決めた調査期間で受信メールを取得する(以下は1ヶ月=30日の例)。

“`bash
gws gmail +triage –query 'in:inbox newer_than:30d' –max 200 –labels –format json
“`

`newer_than` は手順1で決めた期間に合わせる。結果が `–max` 件ちょうどなら取り切れていない可能性が高いので `–max` を増やす。

取得したら**送信元アドレスごとに集計**する。フィルタは送信元単位で作るのが基本なので、この集計が設計の土台になる。同一ドメインの複数アドレス(例: `*-noreply@google.com` 系)はまとめられないか検討する。

### 4. ラベル体系とフィルタの設計

送信元グループごとに、次の3つに仕分ける:

1. **既存ラベルに紐づくフィルタを作る** — 既存ラベルに合致する送信元なのにフィルタが無い(=手動でラベル付けされていた、または放置されていた)もの
2. **新規ラベル+フィルタを作る** — 既存ラベルに合わないが、繰り返し届いていて(目安: 1ヶ月に3通以上)今後も届き続ける機械的な通知。ラベル名は既存の命名規則(言語、大文字小文字、粒度)に合わせる
3. **フィルタを作らない** — 人間からの個別メール、単発の通知、判断に迷うもの。これらは受信トレイに残り続けることでユーザーの目に触れる。それがこのスキルの見落とし防止の仕組みであり、「全部にフィルタを作る」ことが目的ではない

フィルタ条件の作り方:

– 基本は `from:` 条件(`criteria.from`)。1送信元=1フィルタが管理しやすい
– 同一ドメインの複数送信元をまとめる場合は `criteria.query` に `from:(a@x.com OR b@x.com)` 形式
– メーリングリスト由来は `criteria.query` に `list:(リストID)` 形式(既存フィルタがこの形式を使っていれば倣う)
– **件名ベースの条件は誤爆しやすいので、送信元で判別できない場合の最終手段**にする

アクションの設計:

– ラベル付与(`addLabelIds`)は必須
– 受信トレイをスキップするか(`removeLabelIds: [“INBOX”]`)は**ユーザーの好みが分かれるため、必ず本人に確認する**。「ラベルと受信トレイで二重に確認したくないので、ラベルを付けたメールは全部スキップしたい」人もいれば、「重要な通知(請求アラート、期限付き対応依頼)だけは受信トレイに残したい」人もいる。どちらが正しいというものではない
– 既存フィルタの流儀がどちらかに揃っていれば、それをデフォルト案として設計に反映する
– 設計案の提示時に「全フィルタでスキップ / 重要そうな通知のみ受信トレイに残す / 全部残す」のどれにするかを聞く
– デフォルトで既読にするか(`removeLabelIds` に `UNREAD` を追加)も**好みが分かれるため、設計案の提示時に確認する**。「機械的な通知を未読件数に含めたくない(既読にする)」人もいれば、「未読バッジで新着に気付きたい(未読のまま)」人もいる
– 既存フィルタに `UNREAD` を外す流儀があれば、それをデフォルト案として設計に反映する
– ユーザーがすでに方針を表明している場合(会話の中で指定済み、など)は従い、該当する確認は省略してよい

### 5. 設計案の提示と承認

適用前に、設計案を一覧でユーザーに提示する。**フィルタごとに「条件 / ラベル / 受信トレイに残すか / 既読にするか / 調査期間中の該当件数」**が一目で分かる形式にする(以下の表は直近1ヶ月の例):

“`
## フィルタ設計案

| # | 条件 | ラベル | 受信トレイ | 既読 | 直近1ヶ月 |
|—|——|——–|———–|——|———-|
| 1 | from:no_reply@example-kintai.jp | 🆕 kintai | スキップ | 既読にする | 6通 |
| 2 | from:CloudPlatform-noreply@google.com | 🆕 Google Cloud | 残す(請求アラート含むため) | 未読のまま | 9通 |
| 3 | from:forms-receipts-noreply@google.com | 🆕 GoogleForms | スキップ | 既読にする | 6通 |

### フィルタを作らないもの(受信トレイに残る)
– john.doe@example.com — 進行中のサポート案件(人からの返信)
– taro.yamada@example.co.jp — 単発の重要連絡
…理由を一言ずつ添える

### 既存メールへの遡及適用
フィルタは今後のメールにしか効きません。過去メールにも同じラベルを一括適用するか、その範囲を確認する。

### 確認事項
1. この内容で作成してよいですか? 番号指定で一部のみ、条件・ラベル名の変更も指定できます。
2. 受信トレイの扱いはどうしますか? — 全フィルタでスキップ(ラベル側でだけ確認する運用)/ 上記の案どおり重要そうな通知のみ残す / 全部残す
3. 振り分けたメールをデフォルトで既読にしますか? — 全フィルタで既読にする(未読件数に含めない)/ 未読のまま振り分ける / フィルタごとに指定
4. 過去メールへの遡及適用はどうしますか? — 過去のすべてのメールに適用 / 今回の調査範囲(直近1ヶ月)の該当 XX 通のみに適用 / 適用しない
“`

ユーザーの返答に応じて修正する。**承認を得るまで何も作成しない。**

### 6. 適用

承認後、次の順で実行する。

**(a) 新規ラベルの作成**(レスポンスの `id` を控える):

“`bash
gws gmail users labels create –params '{"userId": "me"}' \
–json '{"name": "kintai", "labelListVisibility": "labelShow", "messageListVisibility": "show"}'
“`

**(b) フィルタの作成**(`addLabelIds` はラベル**ID**。名前ではない):

“`bash
# 受信トレイに残す場合
gws gmail users settings filters create –params '{"userId": "me"}' \
–json '{"criteria": {"from": "no_reply@example-kintai.jp"}, "action": {"addLabelIds": ["Label_xxx"]}}'

# 受信トレイをスキップする場合
gws gmail users settings filters create –params '{"userId": "me"}' \
–json '{"criteria": {"from": "no_reply@example-kintai.jp"}, "action": {"addLabelIds": ["Label_xxx"], "removeLabelIds": ["INBOX"]}}'

# さらに既読にする場合(removeLabelIds に UNREAD を追加)
gws gmail users settings filters create –params '{"userId": "me"}' \
–json '{"criteria": {"from": "no_reply@example-kintai.jp"}, "action": {"addLabelIds": ["Label_xxx"], "removeLabelIds": ["INBOX", "UNREAD"]}}'
“`

**(c) 既存メールへの遡及適用**(手順5の確認で「適用する」を選んだ場合のみ)。フィルタは過去のメールに効かないため、フィルタと同じ条件で検索してラベルを一括付与する。**手順5で選ばれた範囲に応じて検索クエリを変える**:

– **過去のすべてのメールに適用**: クエリに `newer_than` を付けない
– **今回の調査範囲のみに適用**: `newer_than` を手順1の調査期間に合わせる(例: 1ヶ月なら `newer_than:30d`)
– **適用しない**: この手順をスキップする

“`bash
# 対象 ID を取得(「調査範囲のみ」なら newer_than を付ける。「すべて」なら付けない)
gws gmail users messages list –params '{"userId": "me", "q": "from:no_reply@example-kintai.jp newer_than:30d", "maxResults": 500}'
# 一括適用(1リクエスト最大1000件)
gws gmail users messages batchModify –params '{"userId": "me"}' \
–json '{"ids": ["19eb…", "19ea…"], "addLabelIds": ["Label_xxx"]}'
“`

遡及適用では `removeLabelIds: [“INBOX”]` は付けない(過去メールを勝手にアーカイブしない)。ユーザーが明示的に頼んだ場合のみ例外。

`users.messages.list` の `maxResults` は**最大 500**(上限。デフォルトは 100)。該当メールが 500 件を超える場合は 1 回で取り切れないため、レスポンスの `nextPageToken` を `pageToken` に渡して繰り返し取得する。一方、batchModify は1リクエスト最大1000件なので、取得した ID は 1000 件ずつに分割して適用する。

batchModify と filters create は成功時に exit code 0。filters create は作成されたフィルタの `id` を返す。

### 7. 結果の報告

最後に以下を報告する:

– 作成したフィルタの一覧(条件 → ラベル、受信トレイ扱い)と、作成した新規ラベル
– 遡及適用した件数(実施した場合)
– **フィルタを作らず受信トレイに残したメールの一覧と理由** — ここにユーザーが自分で読むべきメールが残っている。これが見落とし防止の要
– フィルタ作成に失敗したものがあれば、その内容と原因

## 失敗時の振る舞い

– フィルタ作成で API エラー(exit code 1)が出たら、そのフィルタだけスキップして続行し、最後にまとめて報告する。よくある原因: `addLabelIds` にラベル名(ID ではなく)を渡している、criteria が空
– 途中で失敗しても作成済みのフィルタはそのまま有効。再実行する場合は `filters list` で重複を確認してから作る(同一条件のフィルタが二重にできるのを防ぐ)