Guide

Gmail API 検索クエリの実例集

q パラメータ、ラベル、カテゴリ、日付、添付ファイル、rfc822msgid に対応する Gmail API 検索クエリの実例集。直接 API の構文を確認し、よくあるケースをサポートされる CLI フィルターに置き換える方法を解説します。

Written by Qasim Muhammad Staff SRE

Reviewed by Nick Barraclough

Verified — CLI 3.1.11 · last tested May 16, 2026

Gmail API の検索クエリ構文はどう動くのか？

Gmail API の検索クエリ構文は、users.messages.list の q クエリパラメータに Gmail の検索式を渡すことで動作します。Google のドキュメントによると、このパラメータは Gmail の検索ボックスと同じクエリ形式をサポートしており、1 回の HTTP リクエストで送信者、受信者、件名、未読状態、日付、添付ファイルの有無、メッセージ ID によるフィルタリングができます。

重要な制限は、messages.list が返すのはメッセージ ID であり、本文全体ではないことです。このメソッドはデフォルトで 100 件を返し、1 ページあたり最大 500 件まで受け付けるため、1,500 件ヒットする検索では、内容を取得する前に少なくとも 3 回の list 呼び出しが必要です。公式の users.messages.list リファレンスには、q が gmail.metadata スコープでは使用できないことも記載されています。

以下の最小限の Python 例は、直接 API の形を示しています。特定の送信者からの未読メールを検索し、最初のページを 50 件の ID に制限し、本文の読み取りは 2 番目のステップに残します。本文の読み取りはそれぞれが追加の API 呼び出しになるため、この分離が重要です。

response = service.users().messages().list(
    userId="me",
    q="from:billing@stripe.com is:unread",
    maxResults=50,
).execute()

message_ids = [message["id"] for message in response.get("messages", [])]

送信者・受信者・件名・未読状態で検索するには？

Gmail の検索クエリは複数のフィールド演算子を 1 つの文字列にまとめられるため、送信者、受信者、件名、未読のフィルターを同じ q の値に含められます。実用的なパターンは、ページネーションが始まる前にクエリを絞り込むことです。余分な結果はそれぞれ、後で messages.get の呼び出しを 1 回増やす可能性があるからです。

Google の例には from:、rfc822msgid:、is:unread といった演算子が含まれています。Gmail の UI は to:、subject:、完全一致フレーズ、否定もサポートします。API コードでは演算子は URL エンコードされた 1 つの文字列にすぎず、サーバー側が検索を実行して一致するメッセージ ID を返します。エージェントや cron ジョブの最初のパスには 25 件の上限が適しています。メールボックス全体の読み取りを強制せずに十分な候補が得られるからです。

この CLI コマンドは nylas email search の検証済みフラグを使っています。位置引数のクエリが invoice なのは、現在のコマンドがワイルドカード以外のクエリを件名テキストとして扱うためです。from: などのフィールド演算子は Gmail API の構文であり、CLI にそのまま渡せるわけではありません。このコマンドはスクリプトやエージェントツール向けに 25 件の JSON 結果を返します。

nylas email search "invoice" \
  --from "billing@stripe.com" \
  --unread \
  --limit 25 \
  --json

Gmail のラベルとカテゴリ検索はどう動くのか？

Gmail のラベルはフォルダーではなく、多くのメッセージに付けられるタグで、1 つのメッセージが複数のラベルを同時に持てます。Google のドキュメントには 2 つのラベルファミリーが定義されています：INBOX などの予約済み SYSTEM ラベルと、メールボックスの所有者や連携アプリが作成するカスタム USER ラベルです。

Gmail ラベルガイドには、INBOX、SPAM、TRASH、UNREAD、STARRED などの一般的なシステムラベルに加え、CATEGORY_PERSONAL、CATEGORY_SOCIAL、CATEGORY_PROMOTIONS、CATEGORY_UPDATES、CATEGORY_FORUMS という 5 つのカテゴリラベルが記載されています。検索クエリでは category:promotions のような人間向けの構文を使うことが多い一方、API のラベルフィルターは CATEGORY_PROMOTIONS のようなラベル ID を使います。

CLI は、他のプロバイダーで使われるのと同じフォルダースタイルのインターフェースを通じて Gmail のカテゴリラベルを公開します。この例では、プロモーションのメッセージを 25 件検索し、続いてソーシャルのメッセージに対して件名検索を実行します。どちらのコマンドも、nylas email search の検証済みフォルダーフィルターである --in を使います。

nylas email search "*" --in "CATEGORY_PROMOTIONS" --limit 25 --json

nylas email search "webinar" \
  --in "CATEGORY_SOCIAL" \
  --limit 25 \
  --json

MIME をデコードせずに添付ファイルを検索するには？

Gmail の添付ファイル検索は、MIME の解析ではなく検索インデックスから始めるべきです。has:attachment クエリは、コードがメッセージペイロードをダウンロードする前に結果セットを絞り込みます。これにより、ファイルを含むメッセージが 3 件しかないと知るためだけに、大きな受信トレイのすべてのメッセージをデコードする事態を避けられます。

添付ファイルのダウンロードは依然として 2 番目の API ステップです。Gmail の添付ファイルリソースでは、attachmentId は別の messages.attachments.get リクエストで使う値として説明されており、返されるデータは base64url エンコードです。つまり、Gmail を直接統合する場合は、検索、メッセージパートの走査、添付ファイル ID の取得、バイトのデコード、ファイルの書き込みを自前で行うことになります。

CLI は最初のパスを小さく保ち、メッセージと添付ファイル ID を選択するまでファイルのダウンロードを遅らせます。以下の 3 つのコマンドは、添付ファイル付きメッセージを検索し、選択した 1 件のメッセージの添付ファイルを一覧表示し、特定の添付ファイルをローカルパスにダウンロードします。

nylas email search "*" --has-attachment --from "billing@stripe.com" --limit 25 --json

nylas email attachments list <message-id> --json

nylas email attachments download <attachment-id> <message-id> --output ./invoice.pdf

日付範囲と古いメールを検索するには？

Gmail の日付検索は検索式の中で after:、before:、older:、newer: といった演算子を使う一方、CLI は日付の境界を明示的なフラグとして公開します。自動化ではどちらの方法でも固定の日付を使うべきです。そうすれば、同じジョブを 24 時間ごとに再実行しても再現性のある結果が得られます。

固定ウィンドウは、見えないメールボックススキャンを防ぎます。月次の請求書ジョブなら 2026 年 1 月だけを検索し、件名と送信者でランク付けした後に選択したメッセージを読めます。API コードではこの日付範囲は q 文字列の中に埋め込まれます。CLI では --after と --before により、日付の境界がレビュー担当者に見える形になり、ラッパーで強制しやすくなります。

このコマンドは、2026 年 1 月 1 日から 2 月 1 日までの間にある請求書件名のメッセージを検索します。返すのは最大でも 50 件の候補で、取得ステップを数千の本文へ膨らませることなく、人間向けレポートやエージェントのランク付けパスに十分な量です。

nylas email search "invoice" \
  --after 2026-01-01 \
  --before 2026-02-01 \
  --limit 50 \
  --json

rfc822msgid で 1 通のメッセージを見つけるには？

rfc822msgid: 演算子は、特定の 1 つのインターネットメッセージ ID を検索します。Webhook、バウンス、ログ行、サポートチケットが元の Message-ID ヘッダーを記録している場合に便利です。件名でスキャンする代わりに、通常は 1 つの会話に対応する、グローバルに意味のある識別子を検索対象にします。

Google は users.messages.list のドキュメント例に rfc822msgid: を含めています。この演算子はあいまいなテキスト検索を回避できるため、重複送信、Webhook のファンアウト、返信スレッドのデバッグに最も役立ちます。ラベルやスレッドビューをまたいでコピーが存在する場合、結果に複数のメッセージが含まれる可能性はあるため、低い上限を維持し、本文を読む前に ID を確認してください。

CLI は現在、rfc822msgid: 用の生の Gmail q パススルーを公開していません。この演算子そのものには直接 Gmail API を使い、送信者、件名、日付、フォルダー、添付ファイルのフィルターで検索を近似できる場合にだけ CLI フラグを使ってください。この例では API の結果セットを 5 件の ID に制限しています。

response = service.users().messages().list(
    userId="me",
    q="rfc822msgid:<20260516.12345@example.com>",
    maxResults=5,
).execute()

message_ids = [message["id"] for message in response.get("messages", [])]

Gmail の検索結果を安全にページングするには？

安全な Gmail 検索のページネーションは、クエリを固定したまま現在の nextPageToken を保存し、ビジネス上の上限に達した時点ですぐに停止します。API は 1 ページあたり最大 500 件まで許可しますが、本番ジョブでは通常、200 件や 1,000 件といったより小さい合計上限を定義すべきです。

ページネーションは、直接 API コードが急速に膨らむ部分です。nextPageToken のループ、結果の上限、一時的な失敗へのリトライ動作、同じページを二度処理せずに再開する仕組みが必要になります。日次ジョブが最新 200 件のレシートしか必要としないのに 2,000 件の一致を取得すれば、出力は改善されないままクォータコストとレビュー時間だけが増えます。

この Python のループは検索クエリを一定に保ち、メッセージ ID が 200 件に達したら停止します。件名、スニペット、本文のために messages.get を呼び出す前の段階で、直接統合が抱え込む追加の状態管理を示しています。

query = "from:billing@stripe.com has:attachment after:2026/01/01"
page_token = None
message_ids = []

while len(message_ids) < 200:
    response = service.users().messages().list(
        userId="me",
        q=query,
        maxResults=min(100, 200 - len(message_ids)),
        pageToken=page_token,
    ).execute()

    message_ids.extend(message["id"] for message in response.get("messages", []))
    page_token = response.get("nextPageToken")

    if not page_token:
        break

Gmail の検索結果を読めるメッセージに変えるには？

messages.list は軽量なメッセージレコードを返すため、Gmail の検索結果は 2 番目の取得ステップを経て初めて読める形になります。件名、送信者、スニペット、本文を表示するには、選択した ID に対して messages.get を呼び出し、ヘッダーと base64url エンコードされたペイロードデータを解析する必要があります。

ここは多くの例が隠している部分です。50 件のメッセージ ID を返す検索は、ワークフローがすべての一致を読むなら 50 回のフォローアップ呼び出しになりえます。エージェントのワークフローでは、まず検索し、メタデータをランク付けし、選択した 1〜5 件だけを読んで止まる、というパターンの方が安全です。CLI は nylas email search と nylas email read という別々のコマンドで、この取得境界をそのまま再現しています。

以下のコマンドは、まず検索し、次に選んだ 1 通を読みます。この 2 ステップの形は意図的なものです。本文の取得に追加の呼び出しを費やす前に、スクリプトやモデルが ID とスニペットを確認できるようにします。

nylas email search "contract" --from legal@example.com --limit 10 --json

nylas email read <message-id> --json

CLI はプロバイダー間で検索をどう対応付けるのか？

CLI は開発者に 1 つの検索コマンドを提供しますが、6 つのプロバイダーファミリーはそれぞれ独自の検索エンジンとメールボックスモデルを持ち続けています。Gmail には q とラベルがあり、Microsoft のメールには Graph のフィルタリングとフォルダー API があり、IMAP サーバーは SEARCH とメールボックスフォルダーを公開します。有用な契約は、プロバイダー固有の挙動を裏に隠した 1 つのコマンド面です。

本ガイドにおけるプロバイダー側の挙動は、Google のドキュメントと検証済みの CLI ヘルプに基づく記述であり、すべてのバックエンドでの実機エンドツーエンドテストによるものではありません。category:promotions や rfc822msgid: のような Gmail 専用演算子は、ここでは直接 API の構文です。クロスプロバイダーのワークフローでは、--from、--to、--subject、--after、--before、--has-attachment といった CLI フラグを優先してください。

目的Gmail API の形CLI の形
送信者検索q="from:alice@example.com"nylas email search "*" --from alice@example.com
未読検索q="is:unread"nylas email search "*" --unread
添付ファイル検索q="has:attachment"nylas email search "*" --has-attachment
日付範囲q="invoice after:2026/01/01 before:2026/02/01"nylas email search "invoice" --after 2026-01-01 --before 2026-02-01

ラベル・フォルダー・カテゴリは検索品質にどう影響するのか？

Gmail の検索品質は、ラベル、フォルダー、カテゴリという正しいメールボックス概念を選べるかどうかに左右されます。Gmail のラベルは多対多のタグ、プロバイダーのフォルダーは通常 1 つの場所、Gmail のカテゴリは Google が割り当てるシステムラベルです。これら 3 つのメールボックス概念の混同は、検索が多すぎるメッセージを返したり、期待したメッセージを見落としたりするよくある原因です。

ユーザーがメッセージ内の語句を覚えている場合は、全文検索を使います。ワークフローがすでにメッセージを分類済みなら、ラベルを使います。対象がプロモーションやソーシャルといった Gmail のタブなら、カテゴリを使います。Outlook、Exchange、Yahoo、iCloud、IMAP にもうまく対応するプロバイダー中立のコマンドが欲しいなら、フォルダーを使います。

デバッグしやすいのは、たいてい 2 ステップのパターンです：まず利用可能なフォルダーやラベルを一覧し、次に選んだ場所の中で検索します。これによりフォルダー名がログに残り、クロスプロバイダーのワークフローが CLI のフォルダー抽象を使うべき場面で、Gmail 専用ラベルをハードコードしてしまうことを避けられます。

ジョブを本番投入する前に Gmail 検索クエリをテストするには？

Gmail の検索クエリは、cron、CI、エージェントツールに組み込む前に 4 つのチェックからなるループでテストします：小さい上限で実行し、ID を確認し、選択した 1 通を読み、正確なクエリ文字列を保存します。これにより、何百もの本文を読み込んでしまう前に、広すぎる検索を捕捉できます。

最初の実行では、本番の上限ではなく --limit 5 か --limit 10 を使うべきです。最新の 5 件の一致が期待した種類のメールであることを確認し、送信者、日付、フォルダー、添付ファイルのフィルターが正しく動作してから上限を広げてください。月次ジョブなら、既知の一致があるウィンドウと空のウィンドウという、少なくとも 2 つの日付ウィンドウでテストします。

このスモークテストは出力を小さく、レビューしやすく保ちます。1 つ目のコマンドは検索のスコープが適切であることを証明し、2 つ目のコマンドは候補を 1 通読みます。選んだメッセージが間違っていたら、ページネーションや送信ロジックを追加する前にクエリを修正してください。

nylas email search "invoice" --from billing@example.com --limit 5 --json

nylas email read <message-id> --json

AI エージェントは Gmail 検索をどう安全に使うべきか？

AI エージェントは Gmail 検索を、メールボックス全体を読む許可ではなく、範囲を限定した取得ステップとして使うべきです。安全なエージェントループは、狭く検索し、候補数を制限し、メタデータを確認し、選択したメッセージだけを読み、送信や破壊的な操作の前に承認を求めます。

その差は測定可能です。25 件を検索して 3 通の本文を読むエージェントは、先に 250 通の本文を読むエージェントよりも、プロンプト、コスト、プライバシーのフットプリントがはるかに小さくなります。検索クエリは監査の成果物にもなります：エージェントが from:customer@example.com や has:attachment で検索したのか、それとも contract のような広い語で検索したのかを、レビュー担当者が確認できます。

このシェルのパターンは、エージェントツールの良い出発点です。25 件の候補 ID を集め、ランク付けステップに 1 件を選ばせ、その後で初めて本文を読みます。コマンド名は監査ログやコマンド許可リストにきれいに対応します。

nylas email search "contract" --from customer@example.com --limit 25 --json \
  | jq -r '.[].id' \
  | head -5

nylas email read <selected-message-id> --json

CLI ではなく Gmail API を使うべきなのはいつ？

アプリケーションが Gmail 専用のコントロールプレーンを必要とする場合は、Gmail API を直接使ってください：rfc822msgid: などの生の q 演算子、Gmail の管理、独自の Google Cloud の所有、ドメイン全体の委任、Pub/Sub の watch 更新、Google の OAuth フローをすでに組み込んだ UI などです。ターミナルワークフロー、エージェントツール、cron ジョブ、あるいは可動部品の少ないマルチプロバイダースクリプトが欲しい場合は、CLI を使ってください。

この判断は、Gmail API が優れているかどうかの問題ではありません。配管を誰が所有すべきかの問題です。直接 API コードは、OAuth のセットアップ、クエリの構築、ページネーション、メッセージの読み取り、base64url のデコード、リトライ動作、プロバイダーロックインを抱えます。CLI のパスが抱えるのはコマンドの選択と出力の処理だけで、プロバイダー統合は Nylas が裏側で処理します。

ほとんどの開発者向け自動化では、まず CLI のパスから始め、Gmail 専用の機能を具体的に挙げられる場合にだけ直接 Gmail API の呼び出しに移行してください。このルールにより、単発のスクリプト、AI エージェントツール、CI ジョブが長寿命の OAuth クライアントになってしまうことを防げます。

次に作るべきものは？