列出及搜尋遭隔離的郵件

本頁面說明如何使用 Mail Admin Quarantine API，找出 Google Workspace 管理員隔離區中保留的郵件。

API 在 customers.quarantinedMessages 資源上提供兩種方法：

  • list 方法會傳回隔離郵件，不進行任何篩選。可用來翻閱隔離區中的所有內容。
  • search 方法會使用結構化篩選器、Gmail 搜尋查詢或兩者，縮小結果範圍。可用於分類工作流程，例如只擷取待審查的傳入郵件。

這兩種方法都會傳回過去 30 天內的訊息，且每則訊息都會傳回相同的基本中繼資料。如要擷取標頭、內文、附件或原始郵件，請參閱「取得郵件詳細資料」。

必要條件

  • 您已完成「設定 API」中的步驟。
  • 存取權杖，可模擬具備管理員隔離權限的管理員，並包含 https://www.googleapis.com/auth/gmail.admin.quarantine 或 https://www.googleapis.com/auth/gmail.admin.quarantine.readonly 範圍。請參閱「使用全網域委派功能進行授權」。

列出遭到隔離的郵件

如要列出隔離郵件，請對客戶的 customers.quarantinedMessages 資源，傳送 GET 要求至 list 方法：

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 值。使用這個權杖即可擷取下一頁。

如要搜尋隔離郵件，請將 POST 要求傳送至 customers.quarantinedMessages 資源的 :search 自訂方法，並附上 JSON 主體：

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 服務無法擷取隔離郵件的帳戶。如果出現，請稍後再重試要求。

逐頁瀏覽結果

如要擷取所有相符的訊息，請按照下列步驟操作：

  1. 使用 pageSize 傳送第一個要求。
  2. 如果回應包含 nextPageToken，請使用相同參數重複要求，並將 pageToken 設為該值。
  3. 如果回應不含 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.')

後續步驟