Before you call the Mail Admin Quarantine API, complete the steps on this page to enable the API, find the identifiers that every request needs, and grant the required administrator privileges in your Google Workspace account.
Prerequisites
- A Google Workspace account with the admin quarantine feature. To learn more, see Set up and manage email quarantines.
- A Google Cloud project. To create a project, see Create a project.
- Membership in the Google Workspace Developer Preview Program. Your Cloud project must be enrolled in the program before it can call the Admin Quarantine API.
- Access to the Google Admin console as a super administrator, to grant administrator privileges and authorize domain-wide delegation.
Enable the API
Enable mailadminquarantine.googleapis.com in the Cloud project that hosts your
integration.
Console
In the Google Cloud console, enable the Mail Admin Quarantine API.
gcloud
Run the following command, replacing PROJECT_ID with your Cloud project ID:
gcloud services enable mailadminquarantine.googleapis.com \
--project=PROJECT_ID
Find your customer ID
Every request to the Admin Quarantine API identifies your Google Workspace
account with the customers/CUSTOMER_ID resource name.
To find your customer ID:
- Sign in to the Admin console as an administrator.
- Go to Account > Account settings > Profile.
- Copy the Customer ID.
If the customer ID starts with a C, remove the C and use the remaining
alphanumeric value in the resource name, for example customers/01abc23de.
Don't use your domain name as the customer ID.
For more information, see Find your customer ID.
Grant the required administrator privileges
The Admin Quarantine API enforces the same administrator privilege checks as the admin quarantine in the Admin console. Every request runs on behalf of a Google Workspace administrator, and that administrator must hold one of the following Gmail privileges:
| Privilege | What it allows |
|---|---|
| Access Admin Quarantine | Access and manage messages in all quarantines, including the default quarantine. |
| Access restricted quarantines | Access and manage messages only in quarantines that are associated with groups the administrator belongs to. |
Super administrators have these privileges automatically. For other administrators, assign a role that includes the privilege:
- Sign in to the Admin console as a super administrator.
- Go to Account > Admin roles.
- Select an existing role or click Create new role.
- In the Privileges tab, go to Services > Gmail and select Access Admin Quarantine or Access restricted quarantines.
- Assign the role to the administrator account that your integration impersonates when it calls the API.
For details about delegated administrator roles, see Delegate administrator privileges in Gmail and Administrator privilege definitions.
If the impersonated administrator doesn't have the required privilege, the API
returns a 403 PERMISSION_DENIED error.