Guide

Gmail API：迷惑メールとゴミ箱を一覧表示

スクリプトはメールボックスのすべてのメッセージを一覧表示するはずなのに、探しているフィッシングのサンプルが一向に現れない。それはコードのバグではありません。Gmail API は、明示的に要求しない限り messages.list の結果から SPAM と TRASH を除外します。本ガイドでは、迷惑メールとゴミ箱を読み取る 3 つの公式な方法（includeSpamTrash パラメータ、labelIds フィルタ、in:spam 検索クエリ）に加え、フラグ 1 つで同じことができる CLI を解説します。

Written by Aaron de Mello Senior Engineering Manager

Verified — CLI 3.1.16 · Gmail · last tested June 6, 2026

本ガイドで使用するコマンドリファレンス： nylas email list と nylas email folders list。

Gmail API が迷惑メールやゴミ箱のメッセージを返さないのはなぜ？

Gmail API は、デフォルトで users.messages.list のレスポンスから SPAM と TRASH のシステムラベルを除外します。この動作を制御するのが includeSpamTrash クエリパラメータで、デフォルトは false です。 messages.list リファレンス によると、true に設定すると「SPAM と TRASH のメッセージを結果に含める」とされています。

このデフォルトは受信トレイ型のアプリには理にかなっていますが、3 つの現実的なワークロードを壊します：不正・フィッシング分析、メールボックス全体のバックアップ、そして誤検知メールの復旧スクリプトです。各 messages.list 呼び出しは 5 クォータユニットを消費し、デフォルトで 100 件のメッセージ ID（maxResults 指定で 500 件）を返すため、修正に必要なのはパラメータの変更だけで、追加のリクエストは不要です。

includeSpamTrash で迷惑メールとゴミ箱を含めるには？

messages.list に includeSpamTrash=true を設定すると、迷惑メールとゴミ箱のメッセージが他のすべてと一緒に返されます。結果をフィルタリングするのではなく結果セットを広げるため、メールボックス全体を漏れなく走査したいときに使います。maxResults=500 と組み合わせれば、1 リクエストでデフォルトの 5 倍のページサイズをカバーできます。

以下の Python の例は google-api-python-client を使い、最初の 500 件のうち SPAM または TRASH ラベルが付いたメッセージの数を数えます。後続の messages.get は 1 回あたり 20 クォータユニット、つまり list 呼び出し自体の 4 倍を消費する点に注意してください。

from googleapiclient.discovery import build

service = build("gmail", "v1", credentials=creds)

# Include spam and trash in a full-mailbox listing
results = service.users().messages().list(
    userId="me",
    includeSpamTrash=True,
    maxResults=500,
).execute()

ids = [m["id"] for m in results.get("messages", [])]
print(f"{len(ids)} messages, spam and trash included")

# Check which labels a specific message carries
msg = service.users().messages().get(
    userId="me", id=ids[0], format="minimal"
).execute()
print(msg["labelIds"])  # e.g. ['SPAM'] or ['TRASH']

このパラメータがないと、同じ呼び出しは SPAM または TRASH のラベルが付いたメッセージを黙って除外します。警告もなく、除外された件数も分からないため、このフラグを省いたバックアップスクリプトはメールボックスのサイズを過少に報告し、復旧可能なメールを見逃してしまいます。

labelIds で迷惑メールのみを一覧表示するには？

messages.list に labelIds=["SPAM"] を渡すと、includeSpamTrash なしで迷惑メールのみが返されます。 API リファレンス によると、このフィルタは「指定したすべてのラベル ID に一致するラベルを持つ」メッセージを返すため、ラベル ID を 1 つだけ指定すればそのフォルダがそのまま得られます。削除済みメールには同じ要領で ["TRASH"] を使います。

3 つ目の選択肢は q パラメータです。同じリファレンスによると「Gmail の検索ボックスと同じクエリ形式をサポート」しており、q="in:spam" は labelIds フィルタと同等になります。さらに from: や after: などの他の演算子と 1 つの文字列で組み合わせられます。

# Spam only, via labelIds
spam = service.users().messages().list(
    userId="me", labelIds=["SPAM"], maxResults=100
).execute()

# Trash only
trash = service.users().messages().list(
    userId="me", labelIds=["TRASH"], maxResults=100
).execute()

# Search-style: spam from one sender in the last week
recent = service.users().messages().list(
    userId="me", q="in:spam from:billing@suspicious.example newer_than:7d"
).execute()

目的で選びましょう：単一フォルダをそのまま読むなら labelIds、迷惑メールという範囲に送信者・日付・添付ファイルの条件を重ねるなら q です。どちらの方法も list 呼び出しあたりのコストは同じ 5 クォータユニットです。SPAM と TRASH は Gmail に 13 個ある組み込みシステムラベルのうちの 2 つで、 Gmail ラベルガイドに一覧があります。

Gmail はゴミ箱のメッセージをどのくらい保持する？

Gmail は削除されたメッセージをゴミ箱に最大 30 日間保持します。 Google の復元ドキュメントによると、「削除後 30 日まで：メッセージはゴミ箱で見つかります」、そして 30 日を過ぎると「メッセージは完全に削除されます」。TRASH ラベルに対して構築する復旧スクリプトは、この時計との競争になります。

この期限が自動化のスケジュールを左右します。ゴミ箱を JSON にエクスポートする週次の cron ジョブなら、Gmail がメッセージを消去する前に捕捉するチャンスが 4 回あります。月次のジョブではメッセージを完全に取りこぼすことがあります。迷惑メールのトリアージでも実践パターンは同じです：チームのインシデント対応の時間枠より短い間隔で SPAM ラベルを一覧し、証拠として必要になりうるものは永続化しておきましょう。

CLI から迷惑メールとゴミ箱を読み取るには？

nylas email list --folder SPAM コマンドは、Google Cloud プロジェクトも OAuth 同意画面も Python クライアントのセットアップもなしで、Gmail の迷惑メールを JSON として返します。CLI の --folder フラグは Gmail の任意のシステムラベル ID を受け付けるため、TRASH もまったく同じように動作し、--all-folders なら 1 回の実行ですべてのフォルダを走査できます。認証は nylas auth login 1 回で完了します。

# List spam messages
nylas email list --folder SPAM --limit 20

# List trash as JSON for scripting
nylas email list --folder TRASH --json --limit 50

# Sweep every folder, spam and trash included
nylas email list --all-folders --json --limit 200

# Extract sender addresses from spam for a blocklist review
nylas email list --folder SPAM --json --limit 50 | \
  jq -r '.[].from[0].email' | sort | uniq -c | sort -rn

これらのコマンドは CLI 3.1.16 で実際の Gmail アカウントに対して検証済みです。同じ --folder 構文は Outlook や IMAP アカウントでもそれぞれのフォルダ名で動作するため、Gmail 用に書いた迷惑メールレビュースクリプトは、Gmail API のラベルモデルに触れることなく他のプロバイダーへ移植できます。接続済みアカウントの正確なフォルダ ID を確認するには nylas email folders list を実行してください。

次のステップ