Panoramica dell'API Mail Admin Quarantine

L'API Mail Admin Quarantine consente agli amministratori di Google Workspace di gestire in modo programmatico le email che Gmail conserva in una quarantena amministrativa. I messaggi vengono messi in quarantena quando corrispondono alle regole di conformità, di prevenzione della perdita di dati (DLP) o di sicurezza che configuri nella Console di amministrazione Google.

Utilizza l'API per creare automazioni di sicurezza e conformità, ad esempio:

  • Recupero dei messaggi in quarantena in una piattaforma SIEM o SOAR per il triage.
  • Esaminare le intestazioni dei messaggi, gli snippet del corpo e gli allegati prima di decidere come gestire un messaggio.
  • Sbloccare i messaggi sicuri e rifiutare quelli che non lo sono, singolarmente o in gruppi di massimo 500 messaggi.

Risorse principali

L'API Admin Quarantine espone le seguenti risorse per un cliente:

Risorsa Nome della risorsa Descrizione
Cliente customers/CUSTOMER_ID Il tuo account Google Workspace. Per maggiori dettagli, vedi Trova il tuo ID cliente.
customers.quarantinedMessages customers/CUSTOMER_ID/quarantinedMessages/MESSAGE_OWNER:MESSAGE_ID Un'email trattenuta in quarantena. MESSAGE_OWNER è l'indirizzo email del proprietario della casella di posta e MESSAGE_ID è l'ID messaggio Gmail immutabile.
customers.quarantines customers/CUSTOMER_ID/quarantines/QUARANTINE_ID Una quarantena che hai configurato nella Console di amministrazione.
customers.operations customers/CUSTOMER_ID/operations/OPERATION_ID Un'operazione a lunga esecuzione che monitora una richiesta di rilascio o rifiuto in batch.

Un QuarantinedMessage contiene uno dei seguenti oggetti State:

Stato Descrizione
PENDING_TRIAGE Il messaggio viene trattenuto in quarantena in attesa di una decisione dell'amministratore.
RELEASED Un amministratore ha sbloccato il messaggio e Gmail lo ha recapitato.
DENIED Un amministratore ha rifiutato il messaggio e Gmail lo ha ignorato.

Metodi

Tutte le richieste hanno come target https://mailadminquarantine.googleapis.com/v1.

Metodo Richiesta HTTP Descrizione
customers.quarantinedMessages.list GET /customers/*/quarantinedMessages Elenca i messaggi in quarantena degli ultimi 30 giorni.
customers.quarantinedMessages.search POST /customers/*/quarantinedMessages:search Cerca i messaggi in quarantena utilizzando un filtro o una query di ricerca di Gmail.
customers.quarantinedMessages.get GET /customers/*/quarantinedMessages/* Recupera i metadati, i contenuti analizzati o il messaggio RFC 2822 non elaborato.
customers.quarantinedMessages.release POST /customers/*/quarantinedMessages/*:release Sblocca un singolo messaggio per il recapito.
customers.quarantinedMessages.deny POST /customers/*/quarantinedMessages/*:deny Rifiuta un singolo messaggio.
customers.quarantinedMessages.batchRelease POST /customers/*/quarantinedMessages:batchRelease Rilascia in modo asincrono fino a 500 messaggi.
customers.quarantinedMessages.batchDeny POST /customers/*/quarantinedMessages:batchDeny Rifiuta in modo asincrono fino a 500 messaggi.
customers.operations.get GET /customers/*/operations/* Recupera lo stato e i risultati di un'operazione batch.
customers.quarantines.list GET /customers/*/quarantines Elenca le quarantene configurate per il cliente.
customers.quarantines.get GET /customers/*/quarantines/* Recupera il nome visualizzato e la descrizione di una quarantena.

Procedura di implementazione di alto livello

  1. Configura l'API: partecipa al programma Anteprima per gli sviluppatori, attiva l'API nel tuo progetto Google Cloud, trova il tuo ID cliente e concedi il privilegio amministrativo richiesto.
  2. Autorizza con la delega a livello di dominio: crea un service account, configura la delega a livello di dominio con gli ambiti dell'API Admin Quarantine e ottieni un token di accesso che impersona un amministratore.
  3. Classifica i messaggi:
    1. Elencare e cercare i messaggi in quarantena.
    2. Visualizza i dettagli del messaggio.
    3. Sblocca o rifiuta un messaggio o sblocca o rifiuta i messaggi in batch.
  4. Rispettare le quote di utilizzo.

Audit logging

Ogni chiamata API che legge o modifica i messaggi in quarantena viene registrata nei log di controllo e indagine della Console di amministrazione e attribuita all'amministratore con cui viene eseguita la richiesta.

Passaggi successivi