列出和搜索隔离的邮件

本页面介绍了如何使用 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 资源上的 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 值。使用此令牌可检索下一页。

如需搜索隔离的邮件，请向 customers.quarantinedMessages 资源上的 :search 自定义方法发送 POST 请求，并附带 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.')

后续步骤