Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Nachrichten in Quarantäne auflisten und suchen

Auf dieser Seite wird erläutert, wie Sie mit der Mail Admin Quarantine API die Nachrichten finden, die in Ihren Google Workspace-Admin-Quarantänen gespeichert sind.

Die API bietet zwei Methoden für die Ressource customers.quarantinedMessages:

Die Methode list gibt unter Quarantäne gestellte Nachrichten ohne Filterung zurück. Damit können Sie durch alle Elemente in Ihren Quarantänen blättern.
Mit der Methode search werden die Ergebnisse mit einem strukturierten Filter, einer Gmail-Suchanfrage oder beidem eingegrenzt. Verwenden Sie ihn für Triage-Workflows, z. B. um nur eingehende Nachrichten abzurufen, die noch überprüft werden müssen.

Beide Methoden geben Nachrichten der letzten 30 Tage zurück und beide geben für jede Nachricht dieselben grundlegenden Metadaten zurück. Informationen zum Abrufen von Headern, Text, Anhängen oder der Rohdaten der Nachricht finden Sie unter Nachrichtendetails abrufen.

Vorbereitung

Sie haben die Schritte unter API einrichten ausgeführt.
Ein Zugriffstoken, das einen Administrator mit einer Administratorberechtigung für die Quarantäne imitiert und den Bereich https://www.googleapis.com/auth/gmail.admin.quarantine oder https://www.googleapis.com/auth/gmail.admin.quarantine.readonly enthält. Weitere Informationen finden Sie unter Mit domainweiter Delegierung autorisieren.

Nachrichten in Quarantäne auflisten

Wenn Sie Nachrichten in Quarantäne auflisten möchten, senden Sie eine GET-Anfrage an die Methode list für die Ressource customers.quarantinedMessages Ihres Kunden:

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

Ersetzen Sie CUSTOMER_ID durch Ihre Kundennummer.

Die Methode list akzeptiert die folgenden Abfrageparameter:

Parameter	Beschreibung
`pageSize`	Die maximale Anzahl von Nachrichten, die pro Seite zurückgegeben werden sollen, von 1 bis 300. Legen Sie diesen Parameter immer explizit fest.
`pageToken`	Der Wert `nextPageToken` aus einer vorherigen Antwort. Verwenden Sie es, um die nächste Seite abzurufen.

Nachrichten in Quarantäne suchen

Wenn Sie nach Nachrichten in Quarantäne suchen möchten, senden Sie eine POST-Anfrage an die benutzerdefinierte Methode :search für die Ressource customers.quarantinedMessages mit einem JSON-Text:

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
}

Der Anfragetext akzeptiert die folgenden Felder. Alle Felder sind optional:

Feld	Beschreibung
`filter`	Ein strukturierter Filter in der AIP-160-Syntax. Siehe Filtersyntax.
`query`	Eine Gmail-Suchanfrage, z. B. `has:attachment` oder `from:suspicious@example.com`. Die Abfrage verwendet dieselben Operatoren wie die Suche in Gmail. Weitere Informationen finden Sie unter Suchoperatoren in Gmail.
`pageSize`	Die maximale Anzahl von Nachrichten, die pro Seite zurückgegeben werden sollen, von 1 bis 300. Legen Sie dieses Feld immer explizit fest.
`pageToken`	Der Wert `nextPageToken` aus einer vorherigen Antwort.

Wenn Sie sowohl filter als auch query festlegen, gibt die API nur Nachrichten zurück, die mit beiden übereinstimmen.

Filtersyntax

Das Feld filter unterstützt die folgenden Felder. Kombinieren Sie sie mit dem Operator AND. Andere Operatoren wie OR und NOT werden nicht unterstützt.

Feld	Unterstützte Vergleiche	Werte
`status`	`=`	`PENDING_TRIAGE`, `RELEASED` oder `DENIED`.
`direction`	`=`, `!=`	`INBOUND` oder `OUTBOUND`.
`quarantine_name` oder `quarantineName`	`=`	Der Anzeigename einer Quarantäne, wie er in der Admin-Konsole angezeigt wird, z. B. `"Default"`.

Die folgenden Beispiele zeigen gültige Filter:

status = PENDING_TRIAGE

status = PENDING_TRIAGE AND direction = INBOUND

direction != OUTBOUND AND quarantine_name = "Default"

Ein ungültiger Filter gibt den Fehler 400 INVALID_ARGUMENT zurück.

Antwort

Beide Methoden geben eine Liste von QuarantinedMessage-Ressourcen mit grundlegenden Metadaten sowie ein nextPageToken zurück, wenn weitere Ergebnisse verfügbar sind:

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

Feld	Beschreibung
`name`	Der Ressourcenname der Nachricht. Verwenden Sie sie in nachfolgenden `get`-, `release`- und `deny`-Aufrufen für die Ressource `customers.quarantinedMessages`.
`messageId`	Die unveränderliche Gmail-Nachrichten-ID.
`messageOwner`	Die E‑Mail-Adresse des Postfachs, zu dem die Nachricht gehört.
`quarantines`	Die Ressourcennamen der Quarantänen, in denen die Nachricht gespeichert ist. Rufen Sie die Methode `get` der Ressource `customers.quarantines` auf, um den Anzeigenamen einer Quarantäne abzurufen.
`receiveTime`	Wann die Nachricht in Gmail eingegangen ist.
`direction`	`INBOUND`, wenn ein Nutzer die Nachricht empfangen hat, oder `OUTBOUND`, wenn ein Nutzer sie gesendet hat.
`state`	`PENDING_TRIAGE`, `RELEASED` oder `DENIED`.
`retentionExpireTime`	Wenn die Nachricht nicht mehr in der Quarantäne aufbewahrt wird.
`triggeredRules`	Die Regeln, wegen der die Nachricht unter Quarantäne gestellt wurde.
`unreachable`	Konten, für die der Dienst keine in Quarantäne verschobenen Nachrichten abrufen konnte. Wenn vorhanden, wiederholen Sie die Anfrage später.

In Ergebnissen suchen

So rufen Sie alle übereinstimmenden Nachrichten ab:

Senden Sie die erste Anfrage mit einem pageSize.
Wenn die Antwort ein nextPageToken enthält, wiederholen Sie die Anfrage mit denselben Parametern und setzen Sie pageToken auf diesen Wert.
Beenden Sie den Vorgang, wenn die Antwort kein nextPageToken enthält.

Im folgenden Python-Beispiel werden alle eingehenden Nachrichten durchlaufen, die auf eine Triage warten:

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