Listar e pesquisar mensagens em quarentena

Nesta página, explicamos como encontrar as mensagens retidas nas quarentenas de admin do Google Workspace usando a API Mail Admin Quarantine.

A API oferece dois métodos no recurso customers.quarantinedMessages:

  • O método list retorna mensagens em quarentena sem filtragem. Use-o para navegar por tudo o que está em quarentena.
  • O método search restringe os resultados com um filtro estruturado, uma consulta de pesquisa do Gmail ou ambos. Use-o para fluxos de trabalho de triagem, como recuperar apenas mensagens recebidas que estão aguardando revisão.

Os dois métodos retornam mensagens dos últimos 30 dias e os mesmos metadados básicos para cada mensagem. Para recuperar cabeçalhos, corpo, anexos ou a mensagem bruta, consulte Ver detalhes da mensagem.

Pré-requisitos

  • Você concluiu as etapas em Configurar a API.
  • Um token de acesso que personifica um administrador com um privilégio de quarentena de administrador e inclui o escopo https://www.googleapis.com/auth/gmail.admin.quarantine ou https://www.googleapis.com/auth/gmail.admin.quarantine.readonly. Consulte Autorizar com delegação em todo o domínio.

Listar mensagens em quarentena

Para listar as mensagens em quarentena, envie uma solicitação GET ao método list no recurso customers.quarantinedMessages do seu cliente:

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

Substitua CUSTOMER_ID pelo seu ID de cliente.

O método list aceita os seguintes parâmetros de consulta:

Parâmetro Descrição
pageSize O número máximo de mensagens a serem retornadas por página, de 1 a 300. Sempre defina esse parâmetro explicitamente.
pageToken O valor nextPageToken de uma resposta anterior. Use-o para recuperar a próxima página.

Para pesquisar mensagens em quarentena, envie uma solicitação POST ao método personalizado :search no recurso customers.quarantinedMessages com um 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
}

O corpo da solicitação aceita os campos a seguir. Todos os campos são opcionais:

Campo Descrição
filter Um filtro estruturado na sintaxe AIP-160. Consulte Sintaxe do filtro.
query Uma consulta de pesquisa no Gmail, como has:attachment ou from:suspicious@example.com. A consulta usa os mesmos operadores da caixa de pesquisa do Gmail. Consulte Operadores de pesquisa que podem ser usados com o Gmail.
pageSize O número máximo de mensagens a serem retornadas por página, de 1 a 300. Sempre defina esse campo explicitamente.
pageToken O valor nextPageToken de uma resposta anterior.

Quando você define filter e query, a API retorna apenas as mensagens que correspondem a ambos.

Sintaxe do filtro

O campo filter é compatível com os campos a seguir. Combine-os com o operador AND. Outros operadores, como OR e NOT, não são compatíveis.

Campo Comparações aceitas Valores
status = PENDING_TRIAGE, RELEASED ou DENIED.
direction =, != INBOUND ou OUTBOUND.
quarantine_name (ou quarantineName) = O nome de exibição de uma quarentena, como mostrado no Google Admin Console, por exemplo, "Default".

Os exemplos a seguir mostram filtros válidos:

status = PENDING_TRIAGE

status = PENDING_TRIAGE AND direction = INBOUND

direction != OUTBOUND AND quarantine_name = "Default"

Um filtro inválido retorna um erro 400 INVALID_ARGUMENT.

Resposta

Os dois métodos retornam uma lista de recursos QuarantinedMessage com metadados básicos, além de um nextPageToken se houver mais resultados disponíveis:

{
  "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 Descrição
name O nome do recurso da mensagem. Use-o nas chamadas subsequentes de get, release e deny no recurso customers.quarantinedMessages.
messageId O ID imutável da mensagem do Gmail.
messageOwner O endereço de e-mail da caixa de correio que é proprietária da mensagem.
quarantines Os nomes de recursos das quarentenas que contêm a mensagem. Chame o método get do recurso customers.quarantines para receber o nome de exibição de uma quarentena.
receiveTime Quando o Gmail recebeu a mensagem.
direction INBOUND se um usuário recebeu a mensagem ou OUTBOUND se um usuário a enviou.
state PENDING_TRIAGE, RELEASED ou DENIED.
retentionExpireTime Quando a quarentena para de reter a mensagem.
triggeredRules As regras que fizeram a mensagem ser colocada em quarentena.
unreachable Contas em que o serviço não conseguiu recuperar mensagens em quarentena. Se estiver presente, tente fazer a solicitação novamente mais tarde.

Navegar pelos resultados

Para recuperar todas as mensagens correspondentes:

  1. Envie a primeira solicitação com um pageSize.
  2. Se a resposta contiver um nextPageToken, repita a solicitação com os mesmos parâmetros e defina pageToken como esse valor.
  3. Interrompa quando a resposta não tiver um nextPageToken.

O exemplo de Python a seguir mostra todas as mensagens recebidas que estão pendentes de triagem:

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óximas etapas