Mencantumkan dan menelusuri pesan yang dikarantina

Halaman ini menjelaskan cara menemukan pesan yang disimpan di karantina admin Google Workspace menggunakan Mail Admin Quarantine API.

API ini menawarkan dua metode pada resource customers.quarantinedMessages:

  • Metode list menampilkan pesan yang dikarantina tanpa pemfilteran apa pun. Gunakan untuk melihat halaman semua item di karantina Anda.
  • Metode search mempersempit hasil dengan filter terstruktur, kueri penelusuran Gmail, atau keduanya. Gunakan untuk alur kerja triase, seperti hanya mengambil pesan masuk yang menunggu peninjauan.

Kedua metode menampilkan pesan dari 30 hari terakhir, dan keduanya menampilkan metadata dasar yang sama untuk setiap pesan. Untuk mengambil header, isi, lampiran, atau pesan mentah, lihat Mendapatkan detail pesan.

Prasyarat

  • Anda telah menyelesaikan langkah-langkah di bagian Menyiapkan API.
  • Token akses yang meniru identitas administrator dengan hak istimewa karantina admin dan menyertakan cakupan https://www.googleapis.com/auth/gmail.admin.quarantine atau https://www.googleapis.com/auth/gmail.admin.quarantine.readonly. Lihat Memberikan otorisasi dengan delegasi tingkat domain.

Mencantumkan pesan yang dikarantina

Untuk mencantumkan pesan yang dikarantina, kirim permintaan GET ke metode list pada resource customers.quarantinedMessages pelanggan Anda:

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

Ganti CUSTOMER_ID dengan ID pelanggan Anda.

Metode list menerima parameter kueri berikut:

Parameter Deskripsi
pageSize Jumlah maksimum pesan yang akan ditampilkan per halaman, dari 1 hingga 300. Selalu tetapkan parameter ini secara eksplisit.
pageToken Nilai nextPageToken dari respons sebelumnya. Gunakan token ini untuk mengambil halaman berikutnya.

Untuk menelusuri pesan yang dikarantina, kirim permintaan POST ke metode kustom :search pada resource customers.quarantinedMessages dengan isi 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
}

Isi permintaan menerima kolom berikut. Semua kolom bersifat opsional:

Kolom Deskripsi
filter Filter terstruktur dalam sintaksis AIP-160. Lihat Sintaksis filter.
query Kueri penelusuran Gmail, seperti has:attachment atau from:suspicious@example.com. Kueri menggunakan operator yang sama dengan kotak penelusuran Gmail. Lihat Operator penelusuran yang dapat digunakan dengan Gmail.
pageSize Jumlah maksimum pesan yang akan ditampilkan per halaman, dari 1 hingga 300. Selalu tetapkan kolom ini secara eksplisit.
pageToken Nilai nextPageToken dari respons sebelumnya.

Jika Anda menetapkan filter dan query, API hanya akan menampilkan pesan yang cocok dengan keduanya.

Filter sintaksis

Kolom filter mendukung kolom berikut. Gabungkan dengan operator AND. Operator lain, seperti OR dan NOT, tidak didukung.

Kolom Perbandingan yang didukung Nilai
status = PENDING_TRIAGE, RELEASED, atau DENIED.
direction =, != INBOUND atau OUTBOUND.
quarantine_name (atau quarantineName) = Nama tampilan karantina seperti yang ditampilkan di konsol Google Admin, misalnya "Default".

Contoh berikut menunjukkan filter yang valid:

status = PENDING_TRIAGE

status = PENDING_TRIAGE AND direction = INBOUND

direction != OUTBOUND AND quarantine_name = "Default"

Filter yang tidak valid akan menampilkan error 400 INVALID_ARGUMENT.

Respons

Kedua metode ini menampilkan daftar resource QuarantinedMessage dengan metadata dasar, ditambah nextPageToken jika ada lebih banyak hasil yang tersedia:

{
  "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..."
}
Kolom Deskripsi
name Nama resource pesan. Gunakan dalam panggilan get, release, dan deny berikutnya pada resource customers.quarantinedMessages.
messageId ID pesan Gmail yang tidak dapat diubah.
messageOwner Alamat email kotak surat yang memiliki pesan.
quarantines Nama resource karantina yang menyimpan pesan. Panggil metode get dari resource customers.quarantines untuk mendapatkan nama tampilan karantina.
receiveTime Waktu Gmail menerima pesan.
direction INBOUND jika pengguna menerima pesan, atau OUTBOUND jika pengguna mengirimkannya.
state PENDING_TRIAGE, RELEASED, atau DENIED.
retentionExpireTime Saat karantina berhenti mempertahankan pesan.
triggeredRules Aturan yang menyebabkan pesan dikarantina.
unreachable Akun yang pesannya dikarantina tidak dapat diambil oleh layanan. Jika ada, coba lagi permintaan tersebut nanti.

Menelusuri hasil

Untuk mengambil semua pesan yang cocok:

  1. Kirim permintaan pertama dengan pageSize.
  2. Jika respons berisi nextPageToken, ulangi permintaan dengan parameter yang sama dan tetapkan pageToken ke nilai tersebut.
  3. Berhenti saat respons tidak berisi nextPageToken.

Contoh Python berikut menampilkan semua pesan masuk yang menunggu triase:

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

Langkah berikutnya