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:
GmailApp.getUserLabelByName("ラベル名")などを使って、目的の「ラベル(GmailLabelオブジェクト)」をプログラム内に持ってくる。 - ステップ2:取得したスレッドに対して
thread.addLabel(myLabel)を実行して貼り付ける。
この2ステップを意識しながら、実際にコードを書いて動かしてみましょう!
3. STEP1:準備!Gmailでラベルを作成&テストメールを用意しよう
まずは、GASから操作するためのテスト環境をGmail上で用意していきます。
手順1:Gmail上で「スープカレー部」ラベルを作成する
- ブラウザで Gmail を開きます。
- 画面左側のサイドバーメニューにある 「ラベル」 の横の 「+(新しいラベルを作成)」 アイコンをクリックします。
- ラベル名に
スープカレー部と入力し、「作成」ボタンを押します。 - 左側のラベル一覧に「スープカレー部」が追加されたことを確認してください。
手順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オブジェクトとして取得します。
- 指定した名前のラベルをGmailから検索し、
if (!targetLabel) { ... }- 万が一、指定した名前のラベルがGmail上に存在しない場合、プログラムが途中でエラー停止しないように安全装置(チェック処理)を入れておくプロのテクニックです。
GmailApp.search(searchQuery);- 第32回で学んだ検索機能です。検索窓に「スープカレー部」と打ち込んだ時と同じ結果(スレッドの配列)を取得します。
for (var i = 0; i < threads.length; i++)- 検索でヒットした複数のスレッドに対して、順番に1件ずつ同じ処理を繰り返すためのループ構文(
for文)です。
- 検索でヒットした複数のスレッドに対して、順番に1件ずつ同じ処理を繰り返すためのループ構文(
thread.addLabel(targetLabel);- 本日の主役です!取り出した1件のスレッドに対して、あらかじめ取得しておいた「スープカレー部」のラベルをペタッと追加します。
3. 保存と初回実行(承認プロセス)
- 画面上部の 「保存アイコン(フロッピーディスク)」 をクリックします。
- 実行する関数が
addSoupCurryLabelになっていることを確認し、「実行」 ボタンをクリックします。
第2回記事でもお話しした通り、初めてGmail操作を行うプロジェクトでは、初回実行時のみGoogleの「承認が必要です」という認証ポップアップが表示されます。
承認の手順(復習)
- 「権限を確認」をクリックする。
- ご自身のアカウントを選択する。
- 「このアプリは Google で検証されていません」と表示されたら、左下の 「詳細」 をクリックする。
- 「(無題のプロジェクト)に移動」 をクリックする。
- アクセス権限の画面で 「許可」 をクリックする。
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()と組み合わせることで自動作成から整理まで一貫して行える
これを使えば、毎日のように届く膨大なメールの分類作業から完全に解放されますよね!
