Mail Admin Quarantine API overview

The Mail Admin Quarantine API lets Google Workspace administrators programmatically manage email messages that Gmail holds in an admin quarantine. 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.

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.
customers.quarantinedMessages 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 customers/CUSTOMER_ID/quarantines/QUARANTINE_ID A quarantine that you configured in the Admin console.
customers.operations customers/CUSTOMER_ID/operations/OPERATION_ID A long-running operation that tracks a batch release or batch deny request.

A QuarantinedMessage contains one of the following 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 GET /customers/*/quarantinedMessages Lists quarantined messages from the last 30 days.
customers.quarantinedMessages.search POST /customers/*/quarantinedMessages:search Searches quarantined messages using a filter or a Gmail search query.
customers.quarantinedMessages.get GET /customers/*/quarantinedMessages/* Gets metadata, parsed content, or the raw RFC 2822 message.
customers.quarantinedMessages.release POST /customers/*/quarantinedMessages/*:release Releases a single message for delivery.
customers.quarantinedMessages.deny POST /customers/*/quarantinedMessages/*:deny Denies a single message.
customers.quarantinedMessages.batchRelease POST /customers/*/quarantinedMessages:batchRelease Asynchronously releases up to 500 messages.
customers.quarantinedMessages.batchDeny POST /customers/*/quarantinedMessages:batchDeny Asynchronously denies up to 500 messages.
customers.operations.get GET /customers/*/operations/* Gets the status and results of a batch operation.
customers.quarantines.list GET /customers/*/quarantines Lists the quarantines configured for the customer.
customers.quarantines.get GET /customers/*/quarantines/* Gets a quarantine's display name and description.

High-level implementation steps

  1. Set up the API: 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: 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.
    2. Get message details.
    3. Release or deny a message, or release or deny messages in batches.
  4. Stay within the usage quotas.

Audit logging

Every API call that reads or changes quarantined messages is recorded in the Admin console audit and investigation logs, attributed to the administrator the request runs as.

Next steps