Karantinaya alınan iletileri listeleme ve arama

Bu sayfada, Mail Admin Quarantine API'yi kullanarak Google Workspace yönetici karantinalarınızda tutulan iletileri nasıl bulacağınız açıklanmaktadır.

API, customers.quarantinedMessages kaynağında iki yöntem sunar:

  • list yöntemi, karantinaya alınan iletileri herhangi bir filtreleme olmadan döndürür. Karantinalarınızdaki her şeye göz atmak için bu seçeneği kullanın.
  • search yöntemi, sonuçları yapılandırılmış bir filtre, Gmail arama sorgusu veya her ikisiyle daraltır. Bu özelliği, yalnızca inceleme bekleyen gelen iletileri alma gibi triyaj iş akışları için kullanın.

Her iki yöntem de son 30 güne ait mesajları ve her mesaj için aynı temel meta verileri döndürür. Üstbilgileri, gövdeyi, ekleri veya ham iletiyi almak için İleti ayrıntılarını alma başlıklı makaleyi inceleyin.

Ön koşullar

  • API'yi ayarlama başlıklı makaledeki adımları tamamlamış olmanız gerekir.
  • Yönetici karantinası ayrıcalığına sahip bir yöneticiyi taklit eden ve https://www.googleapis.com/auth/gmail.admin.quarantine veya https://www.googleapis.com/auth/gmail.admin.quarantine.readonly kapsamını içeren bir erişim jetonu. Alan genelinde yetkiyle yetkilendirme başlıklı makaleyi inceleyin.

Karantinaya alınan iletileri listeleme

Karantinaya alınan iletileri listelemek için müşterinizin customers.quarantinedMessages kaynağındaki list yöntemine bir GET isteği gönderin:

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

CUSTOMER_ID yerine müşteri kimliğinizi yazın.

list yöntemi aşağıdaki sorgu parametrelerini kabul eder:

Parametre Açıklama
pageSize Sayfa başına döndürülecek maksimum mesaj sayısı (1 ile 300 arasında). Bu parametreyi her zaman açıkça ayarlayın.
pageToken Önceki bir yanıttan alınan nextPageToken değeri. Sonraki sayfayı almak için bunu kullanın.

Karantinaya alınmış iletileri aramak için JSON gövdesiyle customers.quarantinedMessages kaynağındaki :search özel yöntemine bir POST isteği gönderin:

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
}

İstek içeriği aşağıdaki alanları kabul eder. Tüm alanlar isteğe bağlıdır:

Alan Açıklama
filter AIP-160 söz diziminde yapılandırılmış bir filtre. Filtre söz dizimi bölümüne bakın.
query has:attachment veya from:suspicious@example.com gibi bir Gmail arama sorgusu. Sorgu, Gmail arama kutusuyla aynı operatörleri kullanır. Gmail'de kullanabileceğiniz arama operatörleri başlıklı makaleyi inceleyin.
pageSize Sayfa başına döndürülecek maksimum mesaj sayısı (1 ile 300 arasında). Bu alanı her zaman açıkça ayarlayın.
pageToken Önceki bir yanıttan alınan nextPageToken değeri.

Hem filter hem de query değerini ayarladığınızda API yalnızca her ikisiyle de eşleşen mesajları döndürür.

Filtre söz dizimi

filter alanı aşağıdaki alanları destekler. Bunları AND operatörüyle birleştirin. OR ve NOT gibi diğer operatörler desteklenmez.

Alan Desteklenen karşılaştırmalar Değerler
status = PENDING_TRIAGE, RELEASED veya DENIED.
direction =, != INBOUND veya OUTBOUND.
quarantine_name (veya quarantineName) = Karantinanın Google Yönetici Konsolu'nda gösterilen görünen adı (ör. "Default").

Aşağıdaki örneklerde geçerli filtreler gösterilmektedir:

status = PENDING_TRIAGE

status = PENDING_TRIAGE AND direction = INBOUND

direction != OUTBOUND AND quarantine_name = "Default"

Geçersiz bir filtre, 400 INVALID_ARGUMENT hatası döndürür.

Yanıt

Her iki yöntem de temel meta verilerle birlikte QuarantinedMessage kaynaklarının listesini ve daha fazla sonuç varsa nextPageToken değerini döndürür:

{
  "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..."
}
Alan Açıklama
name Mesajın kaynak adı. customers.quarantinedMessages kaynağındaki sonraki get, release ve deny çağrılarında kullanın.
messageId Sabit Gmail ileti kimliği.
messageOwner İletinin sahibi olan posta kutusunun e-posta adresi.
quarantines İletiyi tutan karantinaların kaynak adları. Karantinanın görünen adını almak için customers.quarantines kaynağının get yöntemini çağırın.
receiveTime Gmail'in iletiyi aldığı zaman.
direction Kullanıcı iletiyi aldıysa INBOUND, gönderdiyse OUTBOUND.
state PENDING_TRIAGE, RELEASED veya DENIED.
retentionExpireTime Karantina, iletiyi saklamayı bıraktığında.
triggeredRules İletinin karantinaya alınmasına neden olan kurallar.
unreachable Hizmetin karantinaya alınmış iletileri alamadığı hesaplar. Varsa isteği daha sonra tekrar deneyin.

Sonuçlar arasında gezinme

Eşleşen tüm mesajları almak için:

  1. pageSize ile ilk isteği gönderin.
  2. Yanıt bir nextPageToken içeriyorsa isteği aynı parametrelerle tekrarlayın ve pageToken değerini bu değere ayarlayın.
  3. Yanıt nextPageToken içermediğinde durdurun.

Aşağıdaki Python örneği, önceliklendirme bekleyen tüm gelen mesajları sayfalar:

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

Sonraki adımlar