Как просматривать и искать сообщения, помещенные в карантин

На этой странице рассказывается, как найти письма, помещенные в карантин администратора Google Workspace, с помощью Mail Admin Quarantine API.

В ресурсе customers.quarantinedMessages API предлагает два метода:

  • Метод list возвращает помещенные в карантин сообщения без фильтрации. Используйте его для просмотра всех писем в карантине.
  • Метод search сужает результаты с помощью структурированного фильтра, поискового запроса Gmail или обоих этих инструментов. Используйте его для рабочих процессов сортировки, например для получения только входящих сообщений, ожидающих проверки.

Оба метода возвращают сообщения за последние 30 дней и одинаковые основные метаданные для каждого сообщения. Чтобы получить заголовки, текст, прикрепленные файлы или необработанное сообщение, ознакомьтесь с разделом Как получить сведения о письме.

Требования

Как посмотреть список сообщений, помещенных в карантин

Чтобы получить список писем, помещенных в карантин, отправьте запрос GET к методу list ресурса customers.quarantinedMessages клиента:

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

Замените CUSTOMER_ID на свой идентификатор клиента.

Метод list принимает следующие параметры запроса:

Параметр Описание
pageSize Максимальное количество сообщений на странице (от 1 до 300). Всегда задавайте этот параметр явным образом.
pageToken Значение nextPageToken из предыдущего ответа. Используйте его, чтобы получить следующую страницу.

Чтобы выполнить поиск по сообщениям в карантине, отправьте запрос POST к пользовательскому методу :search ресурса customers.quarantinedMessages с телом 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 Название ресурса сообщения. Используйте его в последующих вызовах get, release и deny для ресурса customers.quarantinedMessages.
messageId Неизменяемый идентификатор сообщения Gmail.
messageOwner Адрес электронной почты почтового ящика, которому принадлежит письмо.
quarantines Названия ресурсов карантинов, в которых содержится сообщение. Вызовите метод get ресурса customers.quarantines, чтобы получить отображаемое название карантина.
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.')

Дальнейшие действия