Release or deny a message

After you review a quarantined message, use the Mail Admin Quarantine API to record your triage decision:

Release the message to deliver it to its recipients. For an inbound message, Gmail delivers it to the recipient's mailbox. For an outbound message, Gmail sends it.
Deny the message to reject it. Gmail drops the message and doesn't deliver it.

This page describes how to release or deny a single message. To act on many messages at once, see Release or deny messages in batches.

Prerequisites

You completed the steps in Set up the API.
An access token that impersonates an administrator with an admin quarantine privilege and includes the https://www.googleapis.com/auth/gmail.admin.quarantine scope. The read-only scope isn't sufficient. See Authorize with domain-wide delegation.
The resource name of a quarantined message in the PENDING_TRIAGE state, which you get from List and search quarantined messages.

Release a message

To release a message, send a POST request to the :release custom method of the customers.quarantinedMessages resource on the message's resource name with an empty JSON body:

POST https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/quarantinedMessages/MESSAGE_OWNER:MESSAGE_ID:release
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{}

The response contains the updated message in the message field, with the state set to RELEASED:

{
  "message": {
    "name": "customers/01abc23de/quarantinedMessages/user@example.com:18d3ef45a8b2c1d0",
    "messageId": "18d3ef45a8b2c1d0",
    "messageOwner": "user@example.com",
    "state": "RELEASED"
  }
}

Deny a message

To deny a message, send a POST request to the :deny custom method of the customers.quarantinedMessages resource on the message's resource name with an empty JSON body:

POST https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/quarantinedMessages/MESSAGE_OWNER:MESSAGE_ID:deny
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{}

The response contains the updated message in the message field, with the state set to DENIED:

{
  "message": {
    "name": "customers/01abc23de/quarantinedMessages/user@example.com:18d3ef45a8b2c1d0",
    "messageId": "18d3ef45a8b2c1d0",
    "messageOwner": "user@example.com",
    "state": "DENIED"
  }
}

Example: Triage pending messages

The following Python example searches for messages pending triage, inspects each message's subject, and releases or denies the message based on a sample rule. Replace the rule with your own triage logic.

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',
}

# 1. Search for messages pending triage.
search_url = f'{BASE_URL}/customers/{CUSTOMER_ID}/quarantinedMessages:search'
search_body = {'filter': 'status = PENDING_TRIAGE', 'pageSize': 10}
response = requests.post(search_url, headers=headers, json=search_body)
response.raise_for_status()

for message in response.json().get('quarantinedMessages', []):
  name = message['name']

  # 2. Get the parsed message content.
  details = requests.get(
      f'{BASE_URL}/{name}?view=MESSAGE_VIEW_DETAILS', headers=headers)
  details.raise_for_status()
  subject = details.json().get('content', {}).get('subject', '')

  # 3. Release or deny the message.
  action = 'deny' if 'malicious' in subject.lower() else 'release'
  result = requests.post(f'{BASE_URL}/{name}:{action}', headers=headers,
                         json={})
  result.raise_for_status()
  print(f"{name}: {result.json()['message']['state']}")

Error responses

HTTP status	Cause
`400 INVALID_ARGUMENT`	The resource name is malformed.
`403 PERMISSION_DENIED`	The impersonated administrator doesn't have access to the quarantine that holds the message, or the token lacks the `https://www.googleapis.com/auth/gmail.admin.quarantine` scope.
`404 NOT_FOUND`	No quarantined message exists with that resource name. The message might have expired from the quarantine.
`429 RESOURCE_EXHAUSTED`	Your Google Cloud project exceeded the write request quota. See Mail Admin Quarantine API usage quotas.

Next steps

Release or deny messages in batches