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:

Parametro Descrizione
pageSize Il numero massimo di messaggi da restituire per pagina, da 1 a 300. Imposta sempre questo parametro in modo esplicito.
pageToken Il valore nextPageToken di una risposta precedente. Utilizzalo per recuperare la pagina successiva.

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:

Campo Descrizione
filter Un filtro strutturato nella sintassi AIP-160. Consulta Sintassi filtro.
query Una query di ricerca di Gmail, ad esempio has:attachment o from:suspicious@example.com. La query utilizza gli stessi operatori della casella di ricerca di Gmail. Vedi Operatori di ricerca utilizzabili in Gmail.
pageSize Il numero massimo di messaggi da restituire per pagina, da 1 a 300. Imposta sempre questo campo in modo esplicito.
pageToken Il valore nextPageToken di una risposta precedente.

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.

Campo Confronti supportati Valori
status = PENDING_TRIAGE, RELEASED o DENIED.
direction =, != INBOUND o OUTBOUND.
quarantine_name (o quarantineName) = Il nome visualizzato di una quarantena, come mostrato nella Console di amministrazione Google, ad esempio "Default".

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..."
}
Campo Descrizione
name Il nome della risorsa del messaggio. Utilizzalo nelle chiamate get, release e deny successive sulla risorsa customers.quarantinedMessages.
messageId L'ID messaggio Gmail immutabile.
messageOwner L'indirizzo email della casella di posta proprietaria del messaggio.
quarantines I nomi delle risorse delle quarantene che contengono il messaggio. Chiama il metodo get della risorsa customers.quarantines per ottenere il nome visualizzato di una quarantena.
receiveTime Quando Gmail ha ricevuto il messaggio.
direction INBOUND se un utente ha ricevuto il messaggio o OUTBOUND se un utente lo ha inviato.
state PENDING_TRIAGE, RELEASED o DENIED.
retentionExpireTime Quando la quarantena smette di conservare il messaggio.
triggeredRules Le regole che hanno causato la messa in quarantena del messaggio.
unreachable Account per i quali il servizio non ha potuto recuperare i messaggi in quarantena. Se presente, riprova a inviare la richiesta in un secondo momento.

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