> [!WARNING] > **Developer Preview:** Available as part of the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview.md.txt), which grants early access to certain features. This page explains how to find the messages that are held in your Google Workspace admin quarantines using the Mail Admin Quarantine API. The API offers two methods on the [`customers.quarantinedMessages`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages.md.txt) resource: - The [`list`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/list.md.txt) method returns quarantined messages without any filtering. Use it to page through everything in your quarantines. - The [`search`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/search.md.txt) method narrows the results with a structured filter, a Gmail search query, or both. Use it for triage workflows, such as retrieving only inbound messages that are pending review. Both methods return messages from the last 30 days, and both return the same basic metadata for each message. To retrieve headers, body, attachments, or the raw message, see [Get message details](https://developers.google.com/workspace/gmail/admin-quarantine/guides/get-message.md.txt). ## Prerequisites - You completed the steps in [Set up the API](https://developers.google.com/workspace/gmail/admin-quarantine/guides/setup.md.txt). - An access token that impersonates an administrator with an admin quarantine privilege and includes the `https://www.googleapis.com/auth/gmail.admin.quarantine` or `https://www.googleapis.com/auth/gmail.admin.quarantine.readonly` scope. See [Authorize with domain-wide delegation](https://developers.google.com/workspace/gmail/admin-quarantine/guides/authorize.md.txt). ## List quarantined messages To list quarantined messages, send a `GET` request to the [`list`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/list.md.txt) method on the [`customers.quarantinedMessages`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages.md.txt) resource of your customer: GET https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/quarantinedMessages?pageSize=50 Authorization: Bearer ACCESS_TOKEN Replace CUSTOMER_ID with your [customer ID](https://developers.google.com/workspace/gmail/admin-quarantine/guides/setup.md.txt#customer-id). The `list` method accepts the following query parameters: | Parameter | Description | |---|---| | `pageSize` | The maximum number of messages to return per page, from 1 to 300. Always set this parameter explicitly. | | `pageToken` | The `nextPageToken` value from a previous response. Use it to retrieve the next page. | ## Search quarantined messages To search quarantined messages, send a `POST` request to the [`:search`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/search.md.txt) custom method on the `customers.quarantinedMessages` resource with a JSON body: 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 } The request body accepts the following fields. All fields are optional: | Field | Description | |---|---| | `filter` | A structured filter in [AIP-160](https://google.aip.dev/160) syntax. See [Filter syntax](https://developers.google.com/workspace/gmail/admin-quarantine/guides/list-search.md.txt#filter). | | `query` | A Gmail search query, such as `has:attachment` or `from:suspicious@example.com`. The query uses the same operators as the Gmail search box. See [Search operators you can use with Gmail](https://support.google.com/mail/answer/7190). | | `pageSize` | The maximum number of messages to return per page, from 1 to 300. Always set this field explicitly. | | `pageToken` | The `nextPageToken` value from a previous response. | When you set both `filter` and `query`, the API returns only messages that match both. ### Filter syntax The `filter` field supports the following fields. Combine them with the `AND` operator. Other operators, such as `OR` and `NOT`, aren't supported. | Field | Supported comparisons | Values | |---|---|---| | `status` | `=` | `PENDING_TRIAGE`, `RELEASED`, or `DENIED`. | | `direction` | `=`, `!=` | `INBOUND` or `OUTBOUND`. | | `quarantine_name` (or `quarantineName`) | `=` | The display name of a quarantine as shown in the Google Admin console, for example `"Default"`. | The following examples show valid filters: status = PENDING_TRIAGE status = PENDING_TRIAGE AND direction = INBOUND direction != OUTBOUND AND quarantine_name = "Default" An invalid filter returns a `400 INVALID_ARGUMENT` error. ## Response Both methods return a list of [`QuarantinedMessage`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages.md.txt#QuarantinedMessage) resources with basic metadata, plus a `nextPageToken` if more results are available: ```json { "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..." } ``` | Field | Description | |---|---| | `name` | The resource name of the message. Use it in subsequent [`get`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/get.md.txt), [`release`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/release.md.txt), and [`deny`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/deny.md.txt) calls on the `customers.quarantinedMessages` resource. | | `messageId` | The immutable Gmail message ID. | | `messageOwner` | The email address of the mailbox that owns the message. | | `quarantines` | The resource names of the quarantines that hold the message. Call the [`get`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantines/get.md.txt) method of the [`customers.quarantines`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantines.md.txt) resource to get a quarantine's display name. | | `receiveTime` | When Gmail received the message. | | `direction` | `INBOUND` if a user received the message, or `OUTBOUND` if a user sent it. | | `state` | `PENDING_TRIAGE`, `RELEASED`, or `DENIED`. | | `retentionExpireTime` | When the quarantine stops retaining the message. | | `triggeredRules` | The rules that caused the message to be quarantined. | | `unreachable` | Accounts for which the service couldn't retrieve quarantined messages. If present, retry the request later. | ## Page through results To retrieve all matching messages: 1. Send the first request with a `pageSize`. 2. If the response contains a `nextPageToken`, repeat the request with the same parameters and set `pageToken` to that value. 3. Stop when the response doesn't contain a `nextPageToken`. The following Python example pages through all inbound messages that are pending triage: ```python 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.') ``` > [!NOTE] > **Note:** List and search requests share a quota of 60 requests per minute per Google Cloud project. Use the largest `pageSize` that suits your workflow to reduce the number of requests. For details, see [Mail Admin Quarantine API usage quotas](https://developers.google.com/workspace/gmail/admin-quarantine/guides/quotas.md.txt). ## Next steps - [Get message details](https://developers.google.com/workspace/gmail/admin-quarantine/guides/get-message.md.txt) - [Release or deny a message](https://developers.google.com/workspace/gmail/admin-quarantine/guides/release-deny.md.txt)