【GAS入門#38】メールのやり取りを自動整理!GmailThread.addLabel()で「スープカレー部」ラベルを付与しよう

Gmailの受信トレイって、毎日の業務連絡や通知メールで一瞬にして埋もれてしまいませんか?

特に、札幌オフィスの有志メンバーで盛り上がっている「スープカレー部」のランチ打ち合わせメールや、大切なお客さまからの連絡が、メルマガや各種通知の中に埋もれてしまって探すのに一苦労…なんて経験がある方も多いはずです。

Gmailには、メールを綺麗に分類・整理するための「ラベル」機能があります。しかし、届いたメールを開いて、手動で1つずつマウス操作でラベルを付けていくのは地味に面倒ですし、うっかり付け忘れてしまうこともありますよね。

そこで今回登場するのが、GAS(Google Apps Script)を使ってメールのやり取り(スレッド)へ自動的にラベルをペタッと貼り付けてくれる超便利メソッド GmailThread.addLabel() です!

過去のGAS入門連載(第32回 GmailApp.search() や第33回 GmailThread.getMessages())で学んだGmailの検索・取得テクニックと組み合わせることで、「特定の内容を含むメールのやり取りを自動で見つけ出し、専用のラベルを貼って一瞬で整理する」という完璧な自動化仕組みが完成します。

今回は、この GmailThread.addLabel() の基本的な仕組みから、実際のコード例、実務で使える応用テクニック、そして初心者が必ず直面する「5大トラップ」まで、どこよりも分かりやすく丁寧に解説していきますね!

1. そもそも「スレッド(Thread)」と「ラベル(Label)」ってなに?

コードを書き始める前に、Gmail特有の概念である 「スレッド」 と 「ラベル」 の関係性を整理しておきましょう。ここを正しく理解しておくと、GASでメール操作をする際のエラーや混乱を劇的に減らすことができますよ!

「クリアファイル」と「付箋シール」でイメージしよう!

Gmailの仕組みは、オフィスで使う文房具に例えると非常にイメージしやすくなります。

  • メッセージ(GmailMessage) = 1通1通の手紙・メール本文
    • 送信者から届いた「単体のメール1通」のことです。
  • スレッド(GmailThread) = 関連するやり取りをまとめた「クリアファイル」★今回の主役!
    • 同じ件名で返信・やり取りを重ねた複数のメール(メッセージ)が、時系列で1つにまとまった「会話のかたまり」のことです。
  • ラベル(GmailLabel) = クリアファイルに貼る「見出し用のシール」
    • 「スープカレー部」「重要」「請求書」など、整理・分類するためにスレッド(クリアファイル)に貼り付ける識別タグのことです。

なぜ「メッセージ」ではなく「スレッド」にラベルを貼るの?

フォルダ分け形式の一般的なメールソフトとは異なり、Gmailではラベルは「メール1通単位」ではなく「スレッド(やり取り全体)単位」で管理される仕組み になっています。

そのため、GASの命令でも GmailMessage.addLabel() という命令は存在せず、必ず GmailThread(スレッドオブジェクト)に対して addLabel() を実行する というルールになっています。

「1通の手紙に直接シールを貼るのではなく、手紙がまとまったクリアファイルにシールを貼る」と覚えておくと納得がいきますよね!

2. 本日使う命令「GmailThread.addLabel()」の文法と仕組み

今回新しくマスターするメソッドの書き方と役割を確認しましょう。

thread.addLabel(label);

(読み方:スレッド・アド・ラベル)

「addLabel()」の役割

指定したスレッド(GmailThread オブジェクト)に対して、引数で渡したラベル(GmailLabel オブジェクト)を1つ付与(追加)する命令です。

ここが超重要!引数に渡すのは「文字」ではなく「ラベルオブジェクト」!

初心者が最もつまずきやすいのが、addLabel() のカッコの中に渡すデータの内容です。

  • ✕ 間違った書き方:thread.addLabel("スープカレー部"); (文字列を直接渡してしまう)
  • ◯ 正しい書き方:thread.addLabel(myLabel); (事前に取得した GmailLabel オブジェクトを渡す)

つまり、GASでラベルを貼るためには、以下の2段階のステップを踏む必要があります。

  1. ステップ1:GmailApp.getUserLabelByName("ラベル名") などを使って、目的の「ラベル(GmailLabel オブジェクト)」をプログラム内に持ってくる。
  2. ステップ2:取得したスレッドに対して thread.addLabel(myLabel) を実行して貼り付ける。

この2ステップを意識しながら、実際にコードを書いて動かしてみましょう!

3. STEP1:準備!Gmailでラベルを作成&テストメールを用意しよう

まずは、GASから操作するためのテスト環境をGmail上で用意していきます。

手順1:Gmail上で「スープカレー部」ラベルを作成する

  1. ブラウザで Gmail を開きます。
  2. 画面左側のサイドバーメニューにある 「ラベル」 の横の 「+(新しいラベルを作成)」 アイコンをクリックします。
  3. ラベル名に スープカレー部 と入力し、「作成」ボタンを押します。
  4. 左側のラベル一覧に「スープカレー部」が追加されたことを確認してください。

手順2:テスト用のメール(スレッド)を用意する

ご自分のGmailアドレス宛に、テスト用のメールを1通送信してみましょう。

  • 宛先:ご自身のGmailアドレス
  • 件名:【スープカレー部】今週末の札幌おすすめ店めぐり打ち合わせ
  • 本文:今週末のランチですが、大通近くのスパイスカレーにするか、すすきのの名店にするか相談しましょう!

メールが送信され、受信トレイに届いたら準備完了です!

4. STEP2:【実践】「スープカレー部」のメールやり取りに自動でラベルを貼ってみよう!

準備ができたら、スプレッドシートや独立型のGASエディタを開いて、プログラムを作成・実行していきましょう!

今回は、第32回で学んだ GmailApp.search() を使って「スープカレー部」というキーワードが含まれるスレッドを検索し、見つかったスレッドに対して GmailThread.addLabel() で自動的にラベルを付与するコードを書いてみます。

1. コードを入力する

GASのエディタ画面を開き、元からある function myFunction() { ... } をすべて消去して、以下のコードをそのままコピー&ペーストしてください。

function addSoupCurryLabel() {
  // 1. Gmailから貼り付け対象の「スープカレー部」ラベルオブジェクトを取得する
  var labelName = "スープカレー部";
  var targetLabel = GmailApp.getUserLabelByName(labelName);
  
  // もしラベルが存在しない場合は処理を中断してログに警告を出す
  if (!targetLabel) {
    Logger.log("エラー:「" + labelName + "」というラベルがGmail内に存在しません。先に作成してください。");
    return;
  }
  
  // 2. GmailApp.search() で件名や本文に「スープカレー部」が含まれるスレッドを検索して取得する
  var searchQuery = "スープカレー部";
  var threads = GmailApp.search(searchQuery);
  
  Logger.log("検索にヒットしたスレッド数: " + threads.length + "件");
  
  // 3. 該当するスレッドを1つずつループ処理してラベルを付与する
  for (var i = 0; i < threads.length; i++) {
    var thread = threads[i];
    
    // 【本日の主役】スレッドにラベルを追加(付与)する!
    thread.addLabel(targetLabel);
    
    // 確認用にスレッドの最初の件名をログに出力(第1回 Logger.log の復習!)
    Logger.log("ラベルを付与しました ➡ 件名: " + thread.getFirstMessageSubject());
  }
}

2. コードの動作を1行ずつ丁寧に解説!

  • GmailApp.getUserLabelByName(labelName);
    • 指定した名前のラベルをGmailから検索し、GmailLabel オブジェクトとして取得します。
  • if (!targetLabel) { ... }
    • 万が一、指定した名前のラベルがGmail上に存在しない場合、プログラムが途中でエラー停止しないように安全装置(チェック処理)を入れておくプロのテクニックです。
  • GmailApp.search(searchQuery);
    • 第32回で学んだ検索機能です。検索窓に「スープカレー部」と打ち込んだ時と同じ結果(スレッドの配列)を取得します。
  • for (var i = 0; i < threads.length; i++)
    • 検索でヒットした複数のスレッドに対して、順番に1件ずつ同じ処理を繰り返すためのループ構文(for 文)です。
  • thread.addLabel(targetLabel);
    • 本日の主役です!取り出した1件のスレッドに対して、あらかじめ取得しておいた「スープカレー部」のラベルをペタッと追加します。

3. 保存と初回実行(承認プロセス)

  1. 画面上部の 「保存アイコン(フロッピーディスク)」 をクリックします。
  2. 実行する関数が addSoupCurryLabel になっていることを確認し、「実行」 ボタンをクリックします。

第2回記事でもお話しした通り、初めてGmail操作を行うプロジェクトでは、初回実行時のみGoogleの「承認が必要です」という認証ポップアップが表示されます。

承認の手順(復習)

  1. 「権限を確認」をクリックする。
  2. ご自身のアカウントを選択する。
  3. 「このアプリは Google で検証されていません」と表示されたら、左下の 「詳細」 をクリックする。
  4. 「(無題のプロジェクト)に移動」 をクリックする。
  5. アクセス権限の画面で 「許可」 をクリックする。

4. 実行結果を確認してみよう!

承認が完了すると、自動的に処理が実行されます。エディタ下部の「実行ログ」に以下のように出力されていれば大成功です!

情報    検索にヒットしたスレッド数: 1件
情報    ラベルを付与しました ➡ 件名: 【スープカレー部】今週末の札幌おすすめ店めぐり打ち合わせ

実際にご自身の Gmail 画面を開いて、受信トレイを確認してみてください!

先ほど届いたテストメールの件名の横に、青やグレーの「スープカレー部」という綺麗でカラフルなラベルタグ が自動で付与されているはずです!

わざわざ手動でメールを開いてラベルを貼り付ける作業をしなくても、プログラムが一瞬でメールを整理してくれました。感動的ですよね!

5. 実務・日常で大活躍!GmailThread.addLabel() の応用パターン3選

GmailThread.addLabel() の基本操作がマスターできたら、実務や日々の業務で即使える3つの実践的な応用パターンに挑戦してみましょう!

応用①:ラベルが存在しない場合に GAS で自動作成してから貼るテクニック

「事前にGmail画面でラベルを手動作成しておくのが面倒…」という場合は、GASの GmailApp.createLabel() を使って、ラベルが存在しなければ自動生成するコードを組むのがスマートです。

function autoCreateAndAddLabel() {
  var labelName = "東京出張レポート";
  
  // 1. ラベルを取得してみる
  var myLabel = GmailApp.getUserLabelByName(labelName);
  
  // 2. もしラベルが存在しなければ、GASから新規作成する!
  if (!myLabel) {
    myLabel = GmailApp.createLabel(labelName);
    Logger.log("新しいラベル「" + labelName + "」を自動作成しました!");
  }
  
  // 3. 対象の未読スレッドを検索してラベルを付与
  var threads = GmailApp.search("subject:東京出張 is:unread");
  for (var i = 0; i < threads.length; i++) {
    threads[i].addLabel(myLabel);
  }
}

この処理を入れておけば、まだ一度も使っていない新しいプロジェクト名やエリア名でも、GASが勝手にGmail内にラベルを作成して整理してくれます!

応用②:特定のキーワードを含む「未読メール」だけにラベルを貼って既読化する

第36回で学んだ GmailMessage.markRead() や GmailThread.markRead() と組み合わせると、「特定の重要通知が届いたら、ラベルを貼って自動的に既読にする」という完全自動フィルタリングが実現できます。

function autoLabelAndMarkRead() {
  var myLabel = GmailApp.getUserLabelByName("スープカレー部");
  
  // 未読(is:unread)かつ「スープカレー」を含むスレッドを検索
  var threads = GmailApp.search("スープカレー is:unread");
  
  for (var i = 0; i < threads.length; i++) {
    var thread = threads[i];
    
    // ラベルを付与する
    thread.addLabel(myLabel);
    
    // スレッド全体を既読化する
    thread.markRead();
    
    Logger.log("自動ラベル付与&既読化完了: " + thread.getFirstMessageSubject());
  }
}

応用③:処理済みのスレッドにラベルを貼りつつ、受信トレイからアーカイブする

受信トレイを常にスッキリ空にしておく「Inbox Zero(インボックス・ゼロ)」を実践したい時におすすめの組み合わせです。

thread.moveToArchive() と組み合わせることで、ラベルを貼った上で受信トレイから退避(アーカイブ)させることができます。

function labelAndArchive() {
  var myLabel = GmailApp.getUserLabelByName("処理済み");
  if (!myLabel) myLabel = GmailApp.createLabel("処理済み");
  
  // 受信トレイにある特定の条件のスレッドを検索
  var threads = GmailApp.search("in:inbox subject:経費精算");
  
  for (var i = 0; i < threads.length; i++) {
    var thread = threads[i];
    
    // 1. ラベルを付与
    thread.addLabel(myLabel);
    
    // 2. 受信トレイからアーカイブ(非表示化)
    thread.moveToArchive();
  }
}

6. 初心者が絶対につまずく!5大トラップと完全対処法

GmailThread.addLabel() を扱う際、プログラミング初心者やGAS学習者が非常によく直面する「5つの落とし穴」と解決策をまとめました。

ここで予習しておけば、エラーが出ても焦らず一瞬で解決できますよ!

トラップ1:GmailApp.addLabel() と書いてエラーになる

// ✕ NG:GmailApp(親玉)に対して直接呼び出してしまう
GmailApp.addLabel(myLabel); 

// ◯ OK:取得した個別の「thread(スレッド)」に対して呼び出す
thread.addLabel(myLabel);

エラーメッセージの例

TypeError: GmailApp.addLabel is not a function

原因と解決策

addLabel() は GmailApp 全体の命令ではなく、1つひとつの GmailThread(スレッドオブジェクト)が持っている専用のメソッド です。必ず検索や一括取得で取り出した thread 変数に対して .addLabel() を実行しましょう!

トラップ2:ラベル名(文字列)を直接 addLabel("スープカレー部") に渡してしまう

// ✕ NG:文字列を直接引数に入れてしまう
thread.addLabel("スープカレー部"); 

// ◯ OK:GmailLabel オブジェクトを渡す
var myLabel = GmailApp.getUserLabelByName("スープカレー部");
thread.addLabel(myLabel);

エラーメッセージの例

Exception: Invalid argument: label

原因と解決策

前半でお伝えした通り、addLabel() は文字列のテキストではなく、Gmailから取得した GmailLabel(ラベルオブジェクト) しか受け付けない仕様になっています。必ず事前に getUserLabelByName() や createLabel() でオブジェクトを取得して渡しましょう。

トラップ3:存在しないラベルを取得しようとして null エラーになる

var myLabel = GmailApp.getUserLabelByName("存在しないラベル名");
thread.addLabel(myLabel); 

エラーメッセージの例

TypeError: Cannot read properties of null または Exception: Invalid argument: label

原因と解決策

Gmail上にまだ存在しないラベル名を指定して getUserLabelByName() を実行すると、変数 myLabel には null(空っぽ)が入ります。その null を addLabel() に渡すためエラーになってしまうのです。

コード内で if (!myLabel) { myLabel = GmailApp.createLabel("ラベル名"); } のように、存在しない場合に自動作成する処理を挟むのが最も安全な解決策 です。

トラップ4:GmailMessage に対して addLabel() を実行しようとしてしまう

var messages = thread.getMessages();
var message = messages[0];

// ✕ NG:メッセージ(単体メール)に対してラベルを貼ろうとする
message.addLabel(myLabel); 

エラーメッセージの例

TypeError: message.addLabel is not a function

原因と解決策

Gmailの構造上、ラベルはメッセージ単位ではなくスレッド単位で付与するもの です。そのため GmailMessage には addLabel() メソッドが用意されていません。

メッセージを取得して解析した場合でも、最終的にラベルを貼る際は thread.addLabel(myLabel) または message.getThread().addLabel(myLabel) のようにスレッドに戻して実行しましょう!

トラップ5:大量のスレッドに対してループで処理して「6分の壁(タイムアウト)」に引っかかる

受信トレイに何千件も蓄積されたスレッドに対して GmailApp.search() で一括検索し、for 文の中で thread.addLabel() を何百回も連続実行すると、GASの実行時間上限(無料アカウントは6分)を超えてエラー停止することがあります。

解決策

検索クエリを調整して、一度に処理する件数を制限するのが鉄則です。

// search の第2引数(開始位置)と第3引数(取得件数)で一度に最大20件までに絞る
var threads = GmailApp.search("スープカレー部", 0, 20);

こうすることで処理が爆速になり、タイムアウトエラーを完全に回避できます!

7. 今回のまとめと次回予告

今回は、Gmailのメールのやり取り(スレッド)に自動でラベルを付与して綺麗に整理整頓できる GmailThread.addLabel() について解説しました。

今日の重要ポイントおさらい

  • GmailThread.addLabel() は、メールのやり取り(スレッド)にラベルを付与する命令
  • 引数には「文字列(”スープカレー部”)」ではなく、事前取得した GmailLabel オブジェクトを渡す
  • ラベルは「メッセージ(1通)」ではなく「スレッド(やり取り全体)」単位で付与される
  • getUserLabelByName() や createLabel() と組み合わせることで自動作成から整理まで一貫して行える

これを使えば、毎日のように届く膨大なメールの分類作業から完全に解放されますよね!