Lister et rechercher des messages mis en quarantaine

Cette page explique comment trouver les messages conservés dans vos quarantaines d'administration Google Workspace à l'aide de l'API Mail Admin Quarantine.

L'API propose deux méthodes sur la ressource customers.quarantinedMessages :

  • La méthode list renvoie les messages mis en quarantaine sans aucun filtrage. Utilisez-le pour parcourir tous les éléments de vos quarantaines.
  • La méthode search affine les résultats à l'aide d'un filtre structuré, d'une requête de recherche Gmail ou des deux. Utilisez-le pour les workflows de tri, par exemple pour ne récupérer que les messages entrants en attente d'examen.

Les deux méthodes renvoient les messages des 30 derniers jours, ainsi que les mêmes métadonnées de base pour chaque message. Pour récupérer les en-têtes, le corps, les pièces jointes ou le message brut, consultez Obtenir les détails d'un message.

Prérequis

  • Vous avez suivi les étapes de la section Configurer l'API.
  • Un jeton d'accès qui emprunte l'identité d'un administrateur disposant d'un droit de mise en quarantaine d'administrateur et inclut le champ d'application https://www.googleapis.com/auth/gmail.admin.quarantine ou https://www.googleapis.com/auth/gmail.admin.quarantine.readonly. Consultez Autoriser avec la délégation au niveau du domaine.

Lister les messages mis en quarantaine

Pour lister les messages mis en quarantaine, envoyez une requête GET à la méthode list sur la ressource customers.quarantinedMessages de votre client :

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

Remplacez CUSTOMER_ID par votre numéro client.

La méthode list accepte les paramètres de requête suivants :

Paramètre Description
pageSize Nombre maximal de messages à renvoyer par page, de 1 à 300. Définissez toujours ce paramètre explicitement.
pageToken Valeur nextPageToken d'une réponse précédente. Utilisez-le pour récupérer la page suivante.

Pour rechercher des messages mis en quarantaine, envoyez une requête POST à la méthode personnalisée :search sur la ressource customers.quarantinedMessages avec un corps 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
}

Le corps de la requête accepte les champs suivants. Tous les champs sont facultatifs :

Champ Description
filter Filtre structuré dans la syntaxe AIP-160. Consultez Syntaxe des filtres.
query Requête de recherche Gmail, par exemple has:attachment ou from:suspicious@example.com. La requête utilise les mêmes opérateurs que le champ de recherche Gmail. Consultez Opérateurs de recherche compatibles avec Gmail.
pageSize Nombre maximal de messages à renvoyer par page, de 1 à 300. Définissez toujours ce champ explicitement.
pageToken Valeur nextPageToken d'une réponse précédente.

Lorsque vous définissez à la fois filter et query, l'API ne renvoie que les messages qui correspondent aux deux.

Syntaxe de filtre

Le champ filter accepte les champs suivants. Combinez-les avec l'opérateur AND. Les autres opérateurs, tels que OR et NOT, ne sont pas compatibles.

Champ Comparaisons acceptées Valeurs
status = PENDING_TRIAGE, RELEASED ou DENIED.
direction =, != INBOUND ou OUTBOUND.
quarantine_name (ou quarantineName) = Nom à afficher d'une quarantaine, tel qu'il apparaît dans la console d'administration Google, par exemple "Default".

Les exemples suivants montrent des filtres valides :

status = PENDING_TRIAGE

status = PENDING_TRIAGE AND direction = INBOUND

direction != OUTBOUND AND quarantine_name = "Default"

Un filtre non valide renvoie une erreur 400 INVALID_ARGUMENT.

Réponse

Les deux méthodes renvoient une liste de ressources QuarantinedMessage avec des métadonnées de base, ainsi qu'un nextPageToken si d'autres résultats sont disponibles :

{
  "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..."
}
Champ Description
name Nom de ressource du message. Utilisez-le dans les appels get, release et deny suivants sur la ressource customers.quarantinedMessages.
messageId ID de message Gmail immuable.
messageOwner Adresse e-mail de la boîte aux lettres propriétaire du message.
quarantines Noms de ressources des quarantaines qui contiennent le message. Appelez la méthode get de la ressource customers.quarantines pour obtenir le nom à afficher d'une quarantaine.
receiveTime Date et heure de réception du message par Gmail.
direction INBOUND si un utilisateur a reçu le message ou OUTBOUND s'il l'a envoyé.
state PENDING_TRIAGE, RELEASED ou DENIED.
retentionExpireTime Lorsque la quarantaine cesse de conserver le message.
triggeredRules Règles ayant causé la mise en quarantaine du message.
unreachable Comptes pour lesquels le service n'a pas pu récupérer les messages mis en quarantaine. Si elle est présente, réessayez la requête ultérieurement.

Parcourir les résultats

Pour récupérer tous les messages correspondants :

  1. Envoyez la première requête avec un pageSize.
  2. Si la réponse contient un nextPageToken, répétez la requête avec les mêmes paramètres et définissez pageToken sur cette valeur.
  3. Arrêtez-vous lorsque la réponse ne contient pas de nextPageToken.

L'exemple Python suivant parcourt tous les messages entrants en attente de tri :

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

Étapes suivantes