ClaudeでGASのGmail自動ラベル分けを作る — 検証用ラベルで安全に試す

Gmailの受信メールを送信元や件名でラベル分けする処理は、GAS(Google Apps Script)のGmailAppだけで作れます。Claudeに書かせるなら、依頼文で決めておくことは3つです。どの検索クエリで拾うか、ラベルを付けたあとに受信トレイから外すか、最初はどのラベルに付けて試すか。この3つが曖昧だと、動くけれど仕分け済みのメールが二重に処理されるスクリプトが出てきます。

ここでは、ルールを表で渡してClaudeにコードを書かせ、検証用ラベルで試してから本番ラベルに切り替える流れを順に示します。claspでローカル開発する準備はClaude CodeでGAS開発を進める手順にあるので、この記事ではGmail側の書き方に絞ります。

仕分けに使うGmailAppの4つの部品

ラベル分けに必要なメソッドは多くありません。公式リファレンスでは、次の4つで足ります。

単位に注意してください。searchが返すのはメッセージではなくスレッドで、ラベルもスレッド単位で付きます。同じスレッドに別の送信元のメールが混ざると、そのスレッド全体が同じラベルになります。

どのメソッドも、初回の実行時にhttps://mail.google.com/スコープの承認を求められます。公式リファレンスの各メソッドの項に、必要なスコープとして載っているものです。メール全体への権限になるので、承認画面で自分のアカウントのスクリプトであることを確認してから進めます。

Claudeに渡すルール表と依頼文

コードを書かせる前に、仕分けルールを表にします。Claudeには「いい感じに分けて」ではなく、検索クエリそのものを渡すほうが手戻りが少なくなります。

宛先はダミーです。自分の受信箱で実際に届いているメールの送信元を見ながら、数件ずつ書き換えてください。検索クエリは「Gmailの検索欄に入れるのと同じ書き方」で書けるので、先にGmailの検索欄で試して、期待どおりのメールが出ることを確かめておくと、スクリプト側の原因切り分けが要らなくなります。

依頼文の例です。

GASでGmailの受信メールを自動でラベル分けしてください。
- ルールは次の表のとおり(label / query / archive の配列にする)
- 対象は受信トレイ内の直近1日(newer_than:1d)で、ラベル未付与のスレッドだけ
- DRY_RUN = true の間は、対象スレッドの件名と件数をLogger.logに出すだけで何も変更しない
- DRY_RUN = false のときは、ラベルが無ければ作り、100スレッド以下のバッチで付ける
- 1回の実行で処理するスレッドは最大200件で打ち切る
- ラベル名の先頭は auto- とし、既存のラベルは変更しない

ポイントは3つあります。ラベル未付与を条件にするのは、仕分け済みを再処理しないためです。実行の打ち切り件数は、後述の上限と6分制限に対する保険になります。DRY_RUNは、検証用ラベルより前の段階で「何件拾うか」だけを見るための切り替えです。

返ってくるコードの典型的な形

次のコードは、公式リファレンスのGmailApp.searchとGmailLabel.addToThreadsに沿って組んだ例です。Claudeの出力をそのまま再現したものではなく、上の依頼文を満たすコードがとる典型的な形として読んでください。

const DRY_RUN = true;        // false にすると実際にラベルを付ける
const MAX_THREADS = 200;     // 1回の実行で処理する上限
const RULES = [
  { label: 'auto-newsletter',
    query: 'from:(news@example.com OR info@example.org)', archive: true },
  { label: 'auto-invoice',
    query: 'subject:(請求書 OR 領収書)', archive: false },
];
 
function labelInbox() {
  let remaining = MAX_THREADS;
  for (const rule of RULES) {
    if (remaining <= 0) break;
    const q = `in:inbox newer_than:1d -label:${rule.label} ${rule.query}`;
    const threads = GmailApp.search(q, 0, remaining);
    remaining -= threads.length;
 
    if (DRY_RUN) {
      threads.forEach(t => Logger.log(`[dry] ${rule.label}: ${t.getFirstMessageSubject()}`));
      continue;
    }
    const label = GmailApp.getUserLabelByName(rule.label)
      || GmailApp.createLabel(rule.label);
    for (let i = 0; i < threads.length; i += 100) {
      label.addToThreads(threads.slice(i, i + 100));
    }
    if (rule.archive) threads.forEach(t => t.moveToArchive());
  }
}

-label:で自分のラベルを除いているので、2回目以降の実行は同じスレッドを拾いません。この除外を依頼文から落とすと、毎回同じメールを検索して読み書きの上限を食うコードになります。

検証用ラベルで本番前に試す

いきなり本番ラベルに付けると、クエリが広すぎたとき受信トレイから大量のメールが消えます。次の順で段階を踏むと、戻せない操作を避けられます。

アーカイブを最後の段階まで残すのは、ラベルが付いただけなら受信トレイに残っていて、誤判定に気づきやすいからです。

1日の上限と6分制限を数える

GASには実行回数や処理量の上限があります。公式の割り当て表(Quotas)で、この処理に関わるのは次の項目です。

割り当ては「ユーザーごとで、最初のリクエストから24時間後にリセット」と説明されています。超えるとスクリプトが例外を投げて止まります。表の値は予告なく変わりうると明記されているので、実運用の前に最新の表を開いてください。

1スレッドへのラベル付けが読み書きの何回分に数えられるかは、公式の表に書かれていません。そのため、設計では次のように見積もると安全側に寄せられます。

• 1回の実行はMAX_THREADSで頭打ちにしておく。検索で読む分と、ラベル付けとアーカイブで書く分の両方が数えられる前提で、1日の実行回数を掛けても2万に届かない値にする
• 時間主導トリガーは最短で1分おきにできますが、トリガーの合計実行時間が日に90分(個人アカウント)なので、1回10秒かかる処理を1分おきに回すと1時間に約10分を消費するため、約9時間で枠を使い切ります
• 初回に過去のメールを全部仕分けたいときは、newer_than:1dを外した一度きりの実行に分け、6分に収まらなければ6分制限を分割実行に直す手順の方法で続きから再開させます

メールの送信はこの処理に含まれませんが、仕分けに加えて通知メールを送る改造をするときは、送信の宛先数が個人アカウントで1日100通までという別の枠に当たります。

定期実行は時間主導トリガーで足りる

仕分けをユーザーの操作なしに回すには、時間主導トリガーを1本作ります。公式のトリガーの説明では、時間主導トリガーはcronのようなもので、最短1分おき、最長で月1回の間隔にできます。1時間おきなら次の1行です。

function installTrigger() {
  ScriptApp.newTrigger('labelInbox').timeBased().everyHours(1).create();
}

installTriggerは一度だけ実行します。毎回実行すると同じトリガーが増えるので、依頼文には「作成前に同名の関数を呼ぶ既存トリガーを削除する」と一行足すと安全です。インストール型トリガーは作成したアカウントの権限で動きます。実行したあとは、エディタの「トリガー」画面を開き、同じ関数のトリガーが1本だけ登録されているかを確かめてください。

この構成では、Claudeは仕分けの実行時には関わりません。Claudeが担うのはコードを書く段階だけで、毎時の実行コストはGoogle側の割り当ての中に収まります。メールを読んで内容で判断させたい場合は、ClaudeのGmailコネクタのように会話の中で都度扱う方法が合います。差出人や件名で決まる規則的な仕分けは、GASのほうが向いています。

GASプロジェクトに置くCLAUDE.mdの書き方

同じ指示を毎回の依頼文に書くのが面倒になったら、プロジェクトのCLAUDE.mdに移します。公式のメモリのページは、指示を「検証できる具体さ」で書くこと、1ファイルは200行以内を目安にすることを勧めています。GAS向けなら次のような内容です。

# Gmail仕分けGAS
 
- ラベル付けは必ず DRY_RUN 定数で切り替えられるようにする。初期値は true
- GmailApp.search は max を必ず指定する(未指定の全件取得を書かない)
- 追加するラベル名は auto- で始め、既存ラベルの削除・改名はしない
- 変更後は clasp push まで実行し、DRY_RUN=true の実行ログ確認は人が行う
- moveToTrash / sendEmail / reply は使わない

CLAUDE.mdは「強制される設定」ではなく文脈として読まれるため、守られなかったときの確認が要ります。メモリのページは、/contextで読み込まれているかを見ることと、必ず実行したい処理はhooksにすることを案内しています。例えば「ファイルを編集するたびに型チェックを走らせる」といった処理は、PostToolUse hookに回すほうが確実です。

よくあるつまずき

仕分けの条件を変えたくなったら、Claudeへの依頼は「RULESの表に1行足して」だけで済みます。検索クエリを自分でGmailに入れて確かめ、DRY_RUNと検証用ラベルを通してから本番に混ぜる、この順を崩さないことが、受信箱を壊さない一番の近道です。issueにラベルを付ける同種の自動化なら、claude-code-actionでissueにラベルを自動で付ける手順も、条件を先に決める点で共通しています。