毎日届く大量のGmailの中から、必要なメールを手作業で探して確認するのは大変ですよね。「未読の重要メールを見落としてしまった」「特定のお問い合わせメールを毎朝手動で集計している」といったお悩みを抱えている方も多いのではないでしょうか。
GAS(Google Apps Script)を使えば、Gmailの強力な検索機能をプログラムから呼び出し、目的のメールを一瞬で自動抽出することができます!
第33回となる今回は、Gmail連携の要となる超重要メソッド GmailApp.search() を徹底解説します。
Gmailの検索窓で普段使っている検索演算子(クエリ)の活用方法から、初心者が100%つまずく「スレッド」と「メッセージ」の違い、さらには取得したメール一覧をGoogleスプレッドシートへ自動書き出しする実践コードまで、どこよりも分かりやすく噛み砕いてお届けします!
1. そもそも GmailApp.search() とは?
GmailApp.search() は、Google Apps ScriptからGmail内部を検索し、条件に一致するメールのまとまり(スレッド)を取得するための命令(メソッド)です。
普段、WebやアプリのGmail画面上部にある「検索窓」に is:unread(未読)や from:info@example.com と打ち込んで検索しますよね。GmailApp.search() を使うと、あの検索窓と全く同じ指定をプログラムから実行できます。
コードの基本構文
// 条件に合うメールのスレッド(会話のまとまり)を検索して取得する
var threads = GmailApp.search("検索クエリ");
2. 超重要!「スレッド(Thread)」と「メール(Message)」の違い
GmailApp.search() を使いこなす上で、絶対に避けて通れないのが「スレッド」と「メッセージ」の概念の違いです。
Gmailでは、同じ件名で返信・やり取りされた一連のメールが、1つの「会話のまとまり」としてグループ化されます。これをGmail用語で スレッド(Thread) と呼びます。
「フォルダーと手紙」でイメージしよう!
- スレッド(GmailThread) = 1つのテーマに関するメールをまとめた 「バインダー(クリアフォルダー)」
- メッセージ(GmailMessage) = バインダーの中に入っている 「1枚1枚の手紙(個別メール)」
【スレッド:札幌オフィス出張日程の件】(バインダー)
├── メッセージ1:佐藤さんからの初回メール「日程候補について」
├── メッセージ2:自分からの返信「承諾しました」
└── メッセージ3:佐藤さんからの確定メール「詳細案内」
GmailApp.search() を実行して返ってくる結果は、個別メール(Message)の集まりではなく、「スレッド(Thread)の配列」 です。
そのため、検索結果から具体的な本文や差出人を取り出すには、まずスレッドを掴み、その中から個別メッセージを取り出すという手順を踏みます。
3. 実務でそのまま使える!Gmail検索クエリ(検索演算子)一覧
GmailApp.search() のカッコ内には、Gmailの検索窓で使える条件指定文字列(検索クエリ)をそのまま記述します。実務や自動化でよく使われるクエリをまとめました。
| 検索クエリ | 意味・動作 | 具体例 |
is:unread | 未読のメールのみ検索 | GmailApp.search("is:unread") |
is:read | 既読のメールのみ検索 | GmailApp.search("is:read") |
subject:〇〇 | 件名に「〇〇」を含むメール | GmailApp.search("subject:札幌オフィス") |
from:〇〇 | 指定した差出人からのメール | GmailApp.search("from:city.sapporo.jp") |
to:〇〇 | 指定した宛先へのメール | GmailApp.search("to:me") |
has:attachment | 添付ファイルがついているメール | GmailApp.search("has:attachment") |
label:〇〇 | 指定したラベルが付与されているメール | GmailApp.search("label:スープカレー部") |
after:YYYY/MM/DD | 指定した日付以降のメール | GmailApp.search("after:2026/09/01") |
before:YYYY/MM/DD | 指定した日付以前のメール | GmailApp.search("before:2026/09/30") |
組み合わせも自由自在!
スペースを空けて並べると AND検索(かつ) になります。
"is:unread subject:札幌市"➡ 未読で、かつ件名に「札幌市」が含まれるメール"from:secoma.co.jp has:attachment"➡ セイコーマートからのメールで、添付ファイルがあるもの
4. STEP1:準備!検索テスト用のメールを用意しよう
まずは、GASで正しく検索できるかテストするためのメールを用意します。
手順
- ご自身のGmailを開きます。
- 自分宛て(自分自身のメールアドレス宛て)に、テスト用メールを1通送信してください。
- 件名:
【重要】札幌市からのお知らせ:秋の防災訓練について - 本文:
札幌オフィスメンバーの皆様、秋の防災訓練の日程をお知らせします。
- 件名:
- 送信後、受信トレイに届いたそのメールを 「未読」の状態 に戻しておきます(メール一覧で未読マークをつけるか、右クリックで未読に設定)。
5. STEP2:【実践】GmailApp.search()で未読メールを検索してみよう!
それでは、GASから未読の「札幌市からのお知らせ」メールを自動検索してみましょう!
1. GASのエディタ画面を開く
任意のGoogleスプレッドシートを開き、上部メニューの 「拡張機能」 > 「Apps Script」 をクリックしてエディタを開きます。
2. コードを入力する
エディタ内のコードをすべて消去し、以下のスクリプトを貼り付けます。
function searchSapporoEmails() {
// 1. 検索クエリを設定(未読 かつ 件名に「札幌市」を含む)
var query = "is:unread subject:札幌市";
// 2. Gmailから条件に合うスレッドを一括取得
var threads = GmailApp.search(query);
// 3. 該当したスレッドの件数をログに表示(第1回の Logger.log を活用!)
Logger.log("検索にヒットしたスレッド数: " + threads.length + "件");
}
3. 初回実行とアクセスの承認
- 上部の 「保存(フロッピーアイコン)」 を押し、「実行」 ボタンをクリックします。
- 初回実行時のみ、「承認が必要です」というポップアップが表示されます。
- 「権限を確認」 > 自分のGoogleアカウントを選択 > 「詳細」 > 「無題のプロジェクト(安全ではないページ)に移動」 > 「許可」 を順にクリックしてアクセスを許可してください。
4. 実行結果を確認する
エディタ下部の「実行ログ」に以下のように表示されれば大成功です!
情報 検索にヒットしたスレッド数: 1件
GASがGmailの受信トレイの中身を自動スキャンし、目的のメール(スレッド)をしっかり見つけてくれました!
6. STEP3:検索結果(スレッド)から件名を取り出して一覧表示する
スレッドの件数が取れたら、次は「見つかったスレッドの件名(タイトル)」をログに出力してみましょう。
スレッドオブジェクトが持つ .getFirstUserMessageSubject() というメソッドを使うと、そのスレッドの件名を簡単に取得できます。
function printSapporoEmailSubjects() {
// 未読の「札幌市」メールを検索
var threads = GmailApp.search("is:unread subject:札幌市");
// 1件もヒットしなかった場合の安全対策
if (threads.length === 0) {
Logger.log("条件に合うメールは見つかりませんでした。");
return;
}
// 検索されたすべてのスレッドを順番に処理(繰り返し処理)
for (var i = 0; i < threads.length; i++) {
var thread = threads[i]; // i番目のスレッドを取り出す
var subject = thread.getFirstUserMessageSubject(); // 件名を取得
Logger.log("[" + (i + 1) + "件目] 件名: " + subject);
}
}
実行ログの例
情報 [1件目] 件名: 【重要】札幌市からのお知らせ:秋の防災訓練について
7. 初心者が絶対につまずく!4大トラップと完全対処法
GmailApp.search() を使う際、プログラミング初心者の方が特によく遭遇するエラーやトラブルを4つ厳選しました。
トラップ1:配列に対して直接スレッド用メソッドを呼んでしまう
GmailApp.search() の戻り値は「スレッドの配列(リスト)」です。
// ✕ NGな書き方(threads は配列なので直接メソッドは呼べない)
var threads = GmailApp.search("is:unread");
var subject = threads.getFirstUserMessageSubject(); // TypeError発生!
// ◯ OKな書き方(インデックス [0] で要素を指定して呼び出す)
var threads = GmailApp.search("is:unread");
if (threads.length > 0) {
var subject = threads[0].getFirstUserMessageSubject();
}
トラップ2:検索上限(デフォルト件数)の制限を知らない
GmailApp.search("クエリ") を単体で実行した場合、取得できるスレッド数は最大50件までに制限されています。
もし50件を超える大量のメールを検索・処理したい場合は、第2引数(開始位置)と第3引数(取得件数) を渡すオーバーロード構文を使用します。
// 0番目(最新)から最大100件取得したい場合
var threads = GmailApp.search("is:unread", 0, 100);
トラップ3:クエリ内の「全角スペース」による検索漏れ
検索クエリを組み立てる際、条件と条件の間のスペースに 全角スペース を混ぜてしまうと、Gmailが正しく検索キーワードを認識できず、検索結果が0件になってしまうことがあります。
クエリ内の区切りスペースは 必ず半角スペース で記述しましょう。
トラップ4:処理対象のメールを毎回全て処理してしまう
GmailApp.search("subject:請求書") などの条件だけで検索をかけると、処理済みの過去のメールまで毎回検索結果に含まれてしまいます。
実務で自動化スクリプトを作成する際は、以下のような工夫をして「未処理のメールだけ」を検索対象にするのが鉄則です。
- 検索条件に
is:unreadを含め、処理後に既読化(markRead())する - 処理済みのスレッドに 専用ラベル(例:「GAS処理済み」)を自動付与し、検索クエリで
-label:処理済みを指定して除外する
8. ちょっと応用!検索結果をスプレッドシートへ自動書き出し
最後に、本連載の過去記事で学んだ知識を組み合わせて、「Gmailで自動検索したメール一覧を、スプレッドシートの末尾に全自動で追記記録する」 実践ツールを作成してみましょう!
第7回で学んだ Sheet.appendRow() を活用します。
実践コード
function exportSapporoEmailsToSheet() {
// 1. アクティブなシートを取得(第2回・第3回参照)
var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
// 2. 検索クエリでメールを抽出
var threads = GmailApp.search("is:unread subject:札幌市");
if (threads.length === 0) {
Logger.log("書き出す未読メールはありませんでした。");
return;
}
// 3. 取得したスレッドをループログ&シート書き出し
for (var i = 0; i < threads.length; i++) {
var thread = threads[i];
var subject = thread.getFirstUserMessageSubject(); // 件名
var lastMessageDate = thread.getLastMessageDate(); // 最終受信日時
var permalink = thread.getPermalink(); // メールへの直リンクURL
// 1行分のデータ配列を作成(第7回参照)
var rowData = [
lastMessageDate,
subject,
permalink,
"未処理"
];
// スプレッドシートの一番下に自動追記!(第7回参照)
sheet.appendRow(rowData);
}
Logger.log(threads.length + "件のメール情報をスプレッドシートに追記しました!");
}
このスクリプトをトリガー設定(定時自動実行)しておけば、毎朝仕事を開始した時点で「自分宛ての重要メール一覧シート」が自動完成しているような便利システムが完成します!
9. 今回のまとめ&次回予告
今回は、Gmailから目的のメールを自在に検索抽出する GmailApp.search() について解説しました。
今日の重要ポイントおさらい
GmailApp.search("クエリ")でGmailの検索窓と同じ条件でメール検索ができる- 戻り値は「スレッド(会話のまとまり)の配列」である
is:unreadやsubject:などの検索演算子を半角スペースで組み合わせて絞り込む- 取得件数の上限はデフォルトで50件。引数で調整可能
次回(第34回)は、今回取得したスレッド(バインダー)の中から具体的な 1通1通のメール本文や送信者情報を取得する GmailThread.getMessages() を解説します!
メール本文に含まれるお問い合わせ内容や出張手配の確認など、テキスト情報を自由自在にプログラムへ読み込んで活用できるようになりますよ。ぜひお楽しみに!
