Liệt kê và tìm kiếm thư bị cách ly

Trang này giải thích cách tìm thư được lưu giữ trong khu vực cách ly của quản trị viên Google Workspace bằng Mail Admin Quarantine API.

API này cung cấp hai phương thức trên tài nguyên customers.quarantinedMessages:

  • Phương thức list trả về các thư bị cách ly mà không cần lọc. Hãy sử dụng nút này để xem từng trang trong danh sách thư bị cách ly.
  • Phương thức search thu hẹp kết quả bằng bộ lọc có cấu trúc, cụm từ tìm kiếm trong Gmail hoặc cả hai. Sử dụng tham số này cho quy trình phân loại, chẳng hạn như chỉ truy xuất những thư đến đang chờ xem xét.

Cả hai phương thức đều trả về tin nhắn trong 30 ngày qua và đều trả về cùng một siêu dữ liệu cơ bản cho mỗi tin nhắn. Để truy xuất tiêu đề, nội dung, tệp đính kèm hoặc thư thô, hãy xem phần Lấy thông tin chi tiết về thư.

Điều kiện tiên quyết

Liệt kê thư bị cách ly

Để liệt kê các thư bị cách ly, hãy gửi yêu cầu GET đến phương thức list trên tài nguyên customers.quarantinedMessages của khách hàng:

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

Thay thế CUSTOMER_ID bằng mã khách hàng của bạn.

Phương thức list chấp nhận các tham số truy vấn sau:

Tham số Mô tả
pageSize Số lượng tin nhắn tối đa được trả về trên mỗi trang, từ 1 đến 300. Luôn đặt tham số này một cách rõ ràng.
pageToken Giá trị nextPageToken từ phản hồi trước đó. Sử dụng mã này để truy xuất trang tiếp theo.

Để tìm kiếm thư bị cách ly, hãy gửi yêu cầu POST đến phương thức tuỳ chỉnh :search trên tài nguyên customers.quarantinedMessages có nội dung 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
}

Nội dung yêu cầu chấp nhận các trường sau. Tất cả các trường đều không bắt buộc:

Trường Mô tả
filter Bộ lọc có cấu trúc theo cú pháp AIP-160. Xem Cú pháp bộ lọc.
query Cụm từ tìm kiếm trong Gmail, chẳng hạn như has:attachment hoặc from:suspicious@example.com. Cụm từ tìm kiếm sử dụng các toán tử giống như hộp tìm kiếm của Gmail. Xem Toán tử tìm kiếm bạn có thể dùng trong Gmail.
pageSize Số lượng tin nhắn tối đa được trả về trên mỗi trang, từ 1 đến 300. Luôn đặt trường này một cách rõ ràng.
pageToken Giá trị nextPageToken từ phản hồi trước đó.

Khi bạn đặt cả filter và query, API chỉ trả về những thông báo khớp với cả hai.

Cú pháp bộ lọc

Trường filter hỗ trợ các trường sau. Kết hợp các từ khoá này bằng toán tử AND. Các toán tử khác, chẳng hạn như OR và NOT, không được hỗ trợ.

Trường Các phép so sánh được hỗ trợ Giá trị
status = PENDING_TRIAGE, RELEASED hoặc DENIED.
direction =, != INBOUND hoặc OUTBOUND.
quarantine_name (hoặc quarantineName) = Tên hiển thị của một khu vực cách ly như trong Bảng điều khiển dành cho quản trị viên của Google, ví dụ: "Default".

Các ví dụ sau đây cho thấy các bộ lọc hợp lệ:

status = PENDING_TRIAGE

status = PENDING_TRIAGE AND direction = INBOUND

direction != OUTBOUND AND quarantine_name = "Default"

Bộ lọc không hợp lệ sẽ trả về lỗi 400 INVALID_ARGUMENT.

Phản hồi

Cả hai phương thức đều trả về danh sách tài nguyên QuarantinedMessage có siêu dữ liệu cơ bản, cộng với nextPageToken nếu có thêm kết quả:

{
  "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..."
}
Trường Mô tả
name Tên tài nguyên của thông báo. Sử dụng mã này trong các lệnh gọi get, release và deny tiếp theo trên tài nguyên customers.quarantinedMessages.
messageId Mã nhận dạng thư Gmail không thể thay đổi.
messageOwner Địa chỉ email của hộp thư sở hữu thư.
quarantines Tên tài nguyên của các vùng cách ly chứa thư. Gọi phương thức get của tài nguyên customers.quarantines để lấy tên hiển thị của thư mục cách ly.
receiveTime Thời điểm Gmail nhận được thư.
direction INBOUND nếu người dùng nhận được tin nhắn hoặc OUTBOUND nếu người dùng gửi tin nhắn.
state PENDING_TRIAGE, RELEASED hoặc DENIED.
retentionExpireTime Thời điểm khu vực cách ly ngừng giữ lại thư.
triggeredRules Quy tắc khiến thư bị cách ly.
unreachable Những tài khoản mà dịch vụ không thể truy xuất thư bị cách ly. Nếu có, hãy thử lại yêu cầu sau.

Xem kết quả theo trang

Cách truy xuất tất cả thư phù hợp:

  1. Gửi yêu cầu đầu tiên bằng pageSize.
  2. Nếu phản hồi chứa nextPageToken, hãy lặp lại yêu cầu có cùng tham số và đặt pageToken thành giá trị đó.
  3. Dừng khi phản hồi không chứa nextPageToken.

Ví dụ về Python sau đây sẽ phân trang tất cả các thư đến đang chờ phân loại:

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.')

Các bước tiếp theo