> [!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.

The Mail Admin Quarantine API lets Google Workspace administrators programmatically
manage email messages that Gmail holds in an
[admin quarantine](https://support.google.com/a/answer/6104172). Messages land
in a quarantine when they match compliance, data loss prevention (DLP), or
security rules that you configure in the Google Admin console.

Use the API to build security and compliance automations, such as:

- Retrieving quarantined messages into a SIEM or SOAR platform for triage.
- Reviewing message headers, body snippets, and attachments before deciding how to handle a message.
- Releasing messages that are safe and denying messages that aren't, individually or in batches of up to 500 messages.

> [!NOTE]
> **Note:** During Developer Preview, the Admin Quarantine API is available as a REST API only. Client libraries and a Discovery document aren't available yet.

## Key resources

The Admin Quarantine API exposes the following resources under a customer:

| Resource | Resource name | Description |
|---|---|---|
| Customer | `customers/CUSTOMER_ID` | Your Google Workspace account. For details, see [Find your customer ID](https://developers.google.com/workspace/gmail/admin-quarantine/guides/setup.md.txt#customer-id). |
| [`customers.quarantinedMessages`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages.md.txt) | `customers/CUSTOMER_ID/quarantinedMessages/MESSAGE_OWNER:MESSAGE_ID` | An email message held in a quarantine. `MESSAGE_OWNER` is the email address of the mailbox owner and `MESSAGE_ID` is the immutable Gmail message ID. |
| [`customers.quarantines`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantines.md.txt) | `customers/CUSTOMER_ID/quarantines/QUARANTINE_ID` | A quarantine that you configured in the Admin console. |
| [`customers.operations`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.operations.md.txt) | `customers/CUSTOMER_ID/operations/OPERATION_ID` | A long-running operation that tracks a batch release or batch deny request. |

A [`QuarantinedMessage`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages.md.txt#QuarantinedMessage)
contains one of the following
[`State`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages.md.txt#State)
objects:

| State | Description |
|---|---|
| `PENDING_TRIAGE` | The message is held in a quarantine and awaits an administrator decision. |
| `RELEASED` | An administrator released the message and Gmail delivered it. |
| `DENIED` | An administrator denied the message and Gmail dropped it. |

## Methods

All requests target `https://mailadminquarantine.googleapis.com/v1`.

| Method | HTTP request | Description |
|---|---|---|
| [`customers.quarantinedMessages.list`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/list.md.txt) | `GET /customers/*/quarantinedMessages` | Lists quarantined messages from the last 30 days. |
| [`customers.quarantinedMessages.search`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/search.md.txt) | `POST /customers/*/quarantinedMessages:search` | Searches quarantined messages using a filter or a Gmail search query. |
| [`customers.quarantinedMessages.get`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/get.md.txt) | `GET /customers/*/quarantinedMessages/*` | Gets metadata, parsed content, or the raw RFC 2822 message. |
| [`customers.quarantinedMessages.release`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/release.md.txt) | `POST /customers/*/quarantinedMessages/*:release` | Releases a single message for delivery. |
| [`customers.quarantinedMessages.deny`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/deny.md.txt) | `POST /customers/*/quarantinedMessages/*:deny` | Denies a single message. |
| [`customers.quarantinedMessages.batchRelease`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/batchRelease.md.txt) | `POST /customers/*/quarantinedMessages:batchRelease` | Asynchronously releases up to 500 messages. |
| [`customers.quarantinedMessages.batchDeny`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/batchDeny.md.txt) | `POST /customers/*/quarantinedMessages:batchDeny` | Asynchronously denies up to 500 messages. |
| [`customers.operations.get`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.operations/get.md.txt) | `GET /customers/*/operations/*` | Gets the status and results of a batch operation. |
| [`customers.quarantines.list`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantines/list.md.txt) | `GET /customers/*/quarantines` | Lists the quarantines configured for the customer. |
| [`customers.quarantines.get`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantines/get.md.txt) | `GET /customers/*/quarantines/*` | Gets a quarantine's display name and description. |

## High-level implementation steps

1. [Set up the API](https://developers.google.com/workspace/gmail/admin-quarantine/guides/setup.md.txt): join the Developer Preview Program, enable the API in your Google Cloud project, find your customer ID, and grant the required administrator privilege.
2. [Authorize with domain-wide delegation](https://developers.google.com/workspace/gmail/admin-quarantine/guides/authorize.md.txt): create a service account, configure domain-wide delegation with the Admin Quarantine API scopes, and obtain an access token that impersonates an administrator.
3. Triage messages:
   1. [List and search quarantined messages](https://developers.google.com/workspace/gmail/admin-quarantine/guides/list-search.md.txt).
   2. [Get message details](https://developers.google.com/workspace/gmail/admin-quarantine/guides/get-message.md.txt).
   3. [Release or deny a message](https://developers.google.com/workspace/gmail/admin-quarantine/guides/release-deny.md.txt), or [release or deny messages in batches](https://developers.google.com/workspace/gmail/admin-quarantine/guides/batch.md.txt).
4. Stay within the [usage quotas](https://developers.google.com/workspace/gmail/admin-quarantine/guides/quotas.md.txt).

## Audit logging

Every API call that reads or changes quarantined messages is recorded in the
Admin console
[audit and investigation](https://support.google.com/a/answer/9725452) logs,
attributed to the administrator the request runs as.

## Next steps

- [Set up the Admin Quarantine API](https://developers.google.com/workspace/gmail/admin-quarantine/guides/setup.md.txt)
- [Set up and manage email quarantines](https://support.google.com/a/answer/6104172) in the Admin console Help Center