Elenca e cerca i messaggi in quarantena

Questa pagina spiega come trovare i messaggi conservati nelle quarantene amministrative di Google Workspace utilizzando l'API Mail Admin Quarantine.

L'API offre due metodi per la risorsa customers.quarantinedMessages:

• Il metodo list restituisce i messaggi in quarantena senza alcun filtro. Utilizzala per scorrere tutti gli elementi in quarantena.
• Il metodo search restringe i risultati con un filtro strutturato, una query di ricerca di Gmail o entrambi. Utilizzalo per i workflow di triage, ad esempio per recuperare solo i messaggi in entrata in attesa di revisione.

Entrambi i metodi restituiscono i messaggi degli ultimi 30 giorni e gli stessi metadati di base per ogni messaggio. Per recuperare le intestazioni, il corpo, gli allegati o il messaggio non elaborato, consulta Recupera i dettagli dei messaggi.

Prerequisiti

• Hai completato i passaggi descritti in Configura l'API.
• Un token di accesso che impersona un amministratore con un privilegio di quarantena amministrativa e include l'ambito https://www.googleapis.com/auth/gmail.admin.quarantine o https://www.googleapis.com/auth/gmail.admin.quarantine.readonly. Vedi Autorizza con la delega a livello di dominio.

Elenca i messaggi in quarantena

Per elencare i messaggi in quarantena, invia una richiesta GET al metodo list sulla risorsa customers.quarantinedMessages del tuo cliente:

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

Sostituisci CUSTOMER_ID con il tuo ID cliente.

Il metodo list accetta i seguenti parametri di query:

Cerca i messaggi in quarantena

Per cercare i messaggi in quarantena, invia una richiesta POST al metodo personalizzato :search sulla risorsa customers.quarantinedMessages con un corpo 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
}

Il corpo della richiesta accetta i seguenti campi. Tutti i campi sono facoltativi:

Quando imposti sia filter sia query, l'API restituisce solo i messaggi che corrispondono a entrambi.

Sintassi filtro

Il campo filter supporta i seguenti campi. Combinali con l'operatore AND. Altri operatori, come OR e NOT, non sono supportati.

I seguenti esempi mostrano filtri validi:

status = PENDING_TRIAGE

status = PENDING_TRIAGE AND direction = INBOUND

direction != OUTBOUND AND quarantine_name = "Default"

Un filtro non valido restituisce un errore 400 INVALID_ARGUMENT.

Risposta

Entrambi i metodi restituiscono un elenco di risorse QuarantinedMessage con metadati di base, oltre a un nextPageToken se sono disponibili altri risultati:

{
  "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..."
}

Scorri i risultati

Per recuperare tutti i messaggi corrispondenti:

1. Invia la prima richiesta con un pageSize.
2. Se la risposta contiene un nextPageToken, ripeti la richiesta con gli stessi parametri e imposta pageToken su quel valore.
3. Interrompi quando la risposta non contiene un nextPageToken.

Il seguente esempio di Python mostra tutte le pagine dei messaggi in entrata in attesa di triage:

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

Passaggi successivi

• Visualizza i dettagli del messaggio
• Sbloccare o rifiutare un messaggio