Enumera y busca mensajes en cuarentena

En esta página, se explica cómo encontrar los mensajes que se retienen en tus cuarentenas de administrador de Google Workspace con la API de Mail Admin Quarantine.

La API ofrece dos métodos en el recurso customers.quarantinedMessages:

  • El método list devuelve los mensajes en cuarentena sin ningún filtrado. Úsala para recorrer todo el contenido de tus cuarentenas.
  • El método search limita los resultados con un filtro estructurado, una consulta de búsqueda de Gmail o ambos. Úsala para los flujos de trabajo de clasificación, como recuperar solo los mensajes entrantes que están pendientes de revisión.

Ambos métodos devuelven mensajes de los últimos 30 días y los mismos metadatos básicos para cada mensaje. Para recuperar encabezados, cuerpo, archivos adjuntos o el mensaje sin procesar, consulta Obtén detalles del mensaje.

Requisitos previos

  • Completaste los pasos que se indican en Configura la API.
  • Un token de acceso que suplanta la identidad de un administrador con un privilegio de cuarentena de administrador y que incluye el permiso https://www.googleapis.com/auth/gmail.admin.quarantine o https://www.googleapis.com/auth/gmail.admin.quarantine.readonly. Consulta Autoriza con la delegación de todo el dominio.

Enumera los mensajes en cuarentena

Para enumerar los mensajes en cuarentena, envía una solicitud GET al método list en el recurso customers.quarantinedMessages de tu cliente:

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

Reemplaza CUSTOMER_ID por tu ID de cliente.

El método list acepta los siguientes parámetros de consulta:

Parámetro Descripción
pageSize Es la cantidad máxima de mensajes que se devolverán por página, de 1 a 300. Establece siempre este parámetro de forma explícita.
pageToken El valor nextPageToken de una respuesta anterior. Úsalo para recuperar la página siguiente.

Para buscar mensajes en cuarentena, envía una solicitud POST al método personalizado :search en el recurso customers.quarantinedMessages con un cuerpo 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
}

El cuerpo de la solicitud acepta los siguientes campos. Los siguientes campos son opcionales:

Campo Descripción
filter Un filtro estructurado en la sintaxis de AIP-160. Consulta Sintaxis de filtro.
query Es una búsqueda de Gmail, como has:attachment o from:suspicious@example.com. La consulta usa los mismos operadores que el cuadro de búsqueda de Gmail. Consulta Operadores de búsqueda que puedes usar con Gmail.
pageSize Es la cantidad máxima de mensajes que se devolverán por página, de 1 a 300. Establece siempre este campo de forma explícita.
pageToken El valor nextPageToken de una respuesta anterior.

Cuando configuras filter y query, la API solo devuelve los mensajes que coinciden con ambos.

Sintaxis de filtro

El campo filter admite los siguientes campos. Combínalos con el operador AND. No se admiten otros operadores, como OR y NOT.

Campo Comparaciones admitidas Valores
status = PENDING_TRIAGE, RELEASED o DENIED.
direction =, != INBOUND o OUTBOUND.
quarantine_name (o quarantineName) = Es el nombre visible de una cuarentena como se muestra en la Consola del administrador de Google, por ejemplo, "Default".

En los siguientes ejemplos, se muestran filtros válidos:

status = PENDING_TRIAGE

status = PENDING_TRIAGE AND direction = INBOUND

direction != OUTBOUND AND quarantine_name = "Default"

Un filtro no válido devuelve un error 400 INVALID_ARGUMENT.

Respuesta

Ambos métodos devuelven una lista de recursos QuarantinedMessage con metadatos básicos, además de un nextPageToken si hay más resultados 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..."
}
Campo Descripción
name Es el nombre del recurso del mensaje. Úsala en las llamadas posteriores a get, release y deny en el recurso customers.quarantinedMessages.
messageId Es el ID inmutable del mensaje de Gmail.
messageOwner Es la dirección de correo electrónico del buzón al que pertenece el mensaje.
quarantines Son los nombres de los recursos de las cuarentenas que contienen el mensaje. Llama al método get del recurso customers.quarantines para obtener el nombre visible de una cuarentena.
receiveTime Cuándo Gmail recibió el mensaje
direction INBOUND si un usuario recibió el mensaje o OUTBOUND si un usuario lo envió.
state PENDING_TRIAGE, RELEASED o DENIED.
retentionExpireTime Cuando la cuarentena deja de retener el mensaje.
triggeredRules Son las reglas que provocaron que el mensaje se pusiera en cuarentena.
unreachable Son las cuentas para las que el servicio no pudo recuperar los mensajes en cuarentena. Si está presente, vuelve a intentar la solicitud más tarde.

Desplázate por los resultados

Para recuperar todos los mensajes que coincidan, haz lo siguiente:

  1. Envía la primera solicitud con un pageSize.
  2. Si la respuesta contiene un nextPageToken, repite la solicitud con los mismos parámetros y establece pageToken en ese valor.
  3. Detente cuando la respuesta no contenga un nextPageToken.

En el siguiente ejemplo de Python, se muestran todas las páginas de mensajes entrantes que están pendientes de clasificación:

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

Próximos pasos