Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

検疫されたメールを一覧表示して検索する

このページでは、Mail Admin Quarantine API を使用して、Google Workspace 管理検疫に保持されているメッセージを検索する方法について説明します。

この API には、customers.quarantinedMessages リソースに 2 つのメソッドが用意されています。

list メソッドは、フィルタリングなしで検疫されたメッセージを返します。これを使用して、検疫内のすべての項目をページングします。
search メソッドは、構造化フィルタ、Gmail 検索クエリ、またはその両方を使用して結果を絞り込みます。審査待ちの受信メッセージのみを取得するなど、トリアージワークフローに使用します。

どちらのメソッドも過去 30 日間のメッセージを返し、各メッセージに対して同じ基本メタデータを返します。ヘッダー、本文、添付ファイル、未加工のメッセージを取得するには、メッセージの詳細を取得するをご覧ください。

前提条件

API を設定するの手順を完了している。
管理者検疫権限を持つ管理者の権限を借用し、https://www.googleapis.com/auth/gmail.admin.quarantine スコープまたは https://www.googleapis.com/auth/gmail.admin.quarantine.readonly スコープを含むアクセストークン。ドメイン全体の委任で承認するをご覧ください。

検疫済みメッセージを一覧表示する

隔離されたメッセージを一覧表示するには、お客様の customers.quarantinedMessages リソースの list メソッドに GET リクエストを送信します。

GET https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/quarantinedMessages?pageSize=50
Authorization: Bearer ACCESS_TOKEN

CUSTOMER_ID は、お客様 ID に置き換えます。

list メソッドは、次のクエリパラメータを受け入れます。

パラメータ	説明
`pageSize`	ページごとに返すメッセージの最大数（1 ～ 300）。このパラメータは常に明示的に設定してください。
`pageToken`	前のレスポンスの `nextPageToken` 値。次のページを取得するために使用します。

検疫されたメールを検索する

検疫されたメッセージを検索するには、JSON 本文を含む customers.quarantinedMessages リソースの :search カスタムメソッドに POST リクエストを送信します。

POST https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/quarantinedMessages:search
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "filter": "status = PENDING_TRIAGE AND direction = INBOUND",
  "query": "from:suspicious@example.com",
  "pageSize": 50
}

リクエスト本文では、次のフィールドを指定できます。すべての項目は省略可能です。

フィールド	説明
`filter`	AIP-160 構文の構造化フィルタ。フィルタ構文をご覧ください。
`query`	Gmail の検索クエリ（`has:attachment`、`from:suspicious@example.com` など）。クエリでは、Gmail 検索の検索ボックスと同じ演算子を使用します。Gmail で使用できる検索演算子をご覧ください。
`pageSize`	ページごとに返すメッセージの最大数（1 ～ 300）。このフィールドは常に明示的に設定してください。
`pageToken`	前のレスポンスの `nextPageToken` 値。

filter と query の両方を設定すると、API は両方に一致するメッセージのみを返します。

フィルタの構文

filter フィールドは、次のフィールドをサポートしています。AND 演算子を使用して結合します。OR や NOT などの他の演算子はサポートされていません。

フィールド	サポートされている比較	値
`status`	`=`	`PENDING_TRIAGE`、`RELEASED`、または `DENIED`。
`direction`	`=`、`!=`	`INBOUND` または `OUTBOUND`
`quarantine_name`（または `quarantineName`）	`=`	Google 管理コンソールに表示される検疫の表示名（例: `"Default"`）。

次の例は、有効なフィルタを示しています。

status = PENDING_TRIAGE

status = PENDING_TRIAGE AND direction = INBOUND

direction != OUTBOUND AND quarantine_name = "Default"

無効なフィルタは 400 INVALID_ARGUMENT エラーを返します。

レスポンス

どちらのメソッドも、基本的なメタデータを含む QuarantinedMessage リソースのリストを返します。さらに、より多くの結果が利用可能な場合は nextPageToken を返します。

{
  "quarantinedMessages": [
    {
      "name": "customers/01abc23de/quarantinedMessages/user@example.com:18d3ef45a8b2c1d0",
      "messageId": "18d3ef45a8b2c1d0",
      "messageOwner": "user@example.com",
      "quarantines": [
        "customers/01abc23de/quarantines/0"
      ],
      "receiveTime": "2026-09-22T10:15:30Z",
      "direction": "INBOUND",
      "state": "PENDING_TRIAGE",
      "retentionExpireTime": "2026-10-22T10:15:30Z",
      "triggeredRules": [
        {
          "policyId": "123",
          "ruleId": "456",
          "displayName": "Inbound phishing protection"
        }
      ]
    }
  ],
  "nextPageToken": "CAESBAgBEA..."
}

フィールド	説明
`name`	メッセージのリソース名。`customers.quarantinedMessages` リソースに対する後続の `get`、`release`、`deny` 呼び出しで使用します。
`messageId`	不変の Gmail メッセージ ID。
`messageOwner`	メッセージを所有するメールボックスのメールアドレス。
`quarantines`	メールを保留している検疫のリソース名。`customers.quarantines` リソースの `get` メソッドを呼び出して、検疫の表示名を取得します。
`receiveTime`	Gmail がメールを受信した日時。
`direction`	ユーザーがメッセージを受信した場合は `INBOUND`、ユーザーがメッセージを送信した場合は `OUTBOUND`。
`state`	`PENDING_TRIAGE`、`RELEASED`、または `DENIED`。
`retentionExpireTime`	検疫でメールの保持が停止されたとき。
`triggeredRules`	メールが検疫に送信される原因となったルール。
`unreachable`	サービスが検疫されたメールを取得できなかったアカウント。存在する場合は、しばらくしてからリクエストを再試行してください。

結果をページ分割する

一致するすべてのメッセージを取得するには:

pageSize を使用して最初のリクエストを送信します。
レスポンスに nextPageToken が含まれている場合は、同じパラメータでリクエストを繰り返し、pageToken をその値に設定します。
レスポンスに nextPageToken が含まれていない場合は停止します。

次の Python の例では、トリアージ待ちのすべての受信メッセージをページングします。

import requests

BASE_URL = 'https://mailadminquarantine.googleapis.com/v1'
CUSTOMER_ID = '01abc23de'  # Your customer ID without the leading 'C'.
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json',
}

search_url = f'{BASE_URL}/customers/{CUSTOMER_ID}/quarantinedMessages:search'
body = {
    'filter': 'status = PENDING_TRIAGE AND direction = INBOUND',
    'pageSize': 100,
}
messages = []
while True:
  response = requests.post(search_url, headers=headers, json=body)
  response.raise_for_status()
  result = response.json()
  messages.extend(result.get('quarantinedMessages', []))
  page_token = result.get('nextPageToken')
  if not page_token:
    break
  body['pageToken'] = page_token

print(f'Found {len(messages)} messages pending triage.')