guida · gmail api

Come può un team di prodotto implementare la Gmail API in modo sicuro?

Implementa la Gmail API come accesso delegato a una specifica casella Gmail, non come una credenziale generica per la consegna di email. Scegli l'ambito OAuth più ristretto che supporta la funzionalità, proteggi lo stato di autorizzazione e i refresh token e mantieni ogni casella associata a un solo tenant. Costruisci i messaggi con una libreria matura per i messaggi Internet, registra l'ID del messaggio Gmail restituito e sincronizza le modifiche tramite Pub/Sub e i record della cronologia. Tratta l'impersonificazione tramite account di servizio come una decisione dell'amministratore di Workspace. Infine, mantieni distinti l'accettazione da parte dell'API, la consegna al server ricevente e l'arrivo in inbox.

Scegli il modello di casella prima di scrivere codice

La Gmail API opera sulla casella Gmail di un utente. È adatta quando un prodotto deve leggere quella casella, organizzarne etichette e thread, creare bozze, inviare come l'utente autorizzato o sincronizzare le modifiche della casella. Questa autorizzazione è sostanzialmente più ampia rispetto alla chiamata a un'API email applicativa da un dominio di prodotto verificato. Inizia definendo con precisione la funzione richiesta sulla casella e chi concede l'accesso. Un prodotto rivolto agli utenti usa normalmente il consenso OAuth per ogni account Google collegato. Un'automazione interna di Google Workspace potrebbe invece usare la delega a livello di dominio approvata dall'amministratore. Se l'unico requisito è inviare ricevute, link di verifica, avvisi o altri messaggi generati dal prodotto da un dominio controllato dall'azienda, evita del tutto l'accesso alla casella e valuta un'API per email transazionali. Questa decisione architetturale riduce gli accessi non necessari prima che qualsiasi controllo di sicurezza o schermata di consenso debba compensarli.

Autorizza l'ambito più ristretto possibile

Configura un client OAuth per il tipo di applicazione corretto, usa un URI di reindirizzamento registrato esatto e collega la risposta di autorizzazione alla sessione del browser che l'ha avviata con un valore state imprevedibile. Richiedi l'accesso nel contesto, quando l'utente attiva la funzionalità che ne ha bisogno. Per un'integrazione di solo invio, `https://www.googleapis.com/auth/gmail.send` è più ristretto degli ambiti che leggono o modificano la casella. Google classifica `gmail.send` come sensibile, mentre ambiti come `gmail.readonly`, `gmail.compose` e `gmail.modify` sono soggetti a restrizioni. Un'app pubblica che usa accessi sensibili o soggetti a restrizioni può richiedere la verifica OAuth, e l'archiviazione o la trasmissione lato server di dati di ambiti soggetti a restrizioni può comportare requisiti aggiuntivi di valutazione della sicurezza. Richiedi l'accesso offline solo quando è davvero necessario un lavoro in background. Cifra i refresh token, associa ogni token a un solo tenant interno e a un solo soggetto Google, non esporlo mai al codice del browser o ai log e fornisci un percorso di disconnessione testato che elimini le credenziali locali e fermi l'elaborazione in background.

Comprendi gli account di servizio e la delega a livello di dominio

Un account di servizio è un'identità applicativa, non una inbox Gmail pronta all'uso. Da solo non ottiene l'accesso ai messaggi dei dipendenti. Per i dati utente di Google Workspace, un super amministratore deve autorizzare esplicitamente l'ID client numerico dell'account di servizio e un elenco esatto di ambiti OAuth tramite la delega a livello di dominio. L'applicazione richiede poi credenziali delegate per un utente specifico, e ogni chiamata API agisce con i permessi di quell'utente entro gli ambiti autorizzati. Rendi esplicito il soggetto impersonato nei dati dei job e nei log di audit, così un worker in background non può cambiare casella in silenzio. Usa account di servizio separati per carichi di lavoro sostanzialmente diversi, evita le chiavi private scaricabili quando il runtime può usare credenziali gestite e rivedi periodicamente le autorizzazioni a livello di dominio. Gli account Gmail consumer non hanno un amministratore di Workspace che possa concedere questa delega a livello di organizzazione, quindi per quegli account usa il consenso OAuth dell'utente.

Invia messaggi senza perdere controllo e tracciabilità

Gmail accetta un messaggio email Internet completo nel campo `raw`, codificato in base64url, tramite `users.messages.send`; un prodotto può anche creare una bozza e inviarla in seguito. Usa una libreria per i messaggi mantenuta per generare From, To, Cc, Bcc, Subject, Date, Message-ID, testo, HTML e struttura degli allegati invece di comporre a mano le righe di intestazione. Valida destinatari e contenuti prima della codifica, rifiuta l'header injection e imposta limiti di dimensione espliciti. Rendi idempotente l'azione del prodotto prima di chiamare Gmail: salva una chiave stabile dell'evento applicativo, il soggetto della casella previsto e uno stato del tentativo di invio. Dopo una risposta positiva, salva con quell'evento l'ID del messaggio e l'ID del thread restituiti da Gmail. Se il client va in timeout dopo aver trasmesso la richiesta, riconcilia lo stato della casella prima di ritentare, perché il messaggio potrebbe essere già stato accettato. Un nuovo tentativo alla cieca può produrre un'email duplicata anche quando la risposta originale è andata persa. Usa la creazione di bozze con revisione umana quando contenuti o destinatari richiedono un'approvazione.

Sincronizza le modifiche della casella con i record della cronologia

Per un'integrazione con la casella lato server, un watch di Gmail pubblica segnali di modifica tramite Google Cloud Pub/Sub. La notifica è un invito a sincronizzare, non un payload email completo. Salva l'history ID corrente e la scadenza restituiti dalla risposta del watch, conferma rapidamente le notifiche e chiama `users.history.list` a partire dall'ultimo history ID salvato con successo per scoprire le modifiche a messaggi ed etichette. Recupera solo i messaggi necessari alla funzionalità, poi fai avanzare il checkpoint dopo che le scritture locali sono riuscite. Le notifiche possono arrivare in ritardo o duplicate, quindi rendi idempotente l'elaborazione di messaggi e cronologia. Gmail richiede di rinnovare il watch di una casella almeno ogni sette giorni e raccomanda un rinnovo giornaliero; pianifica il rinnovo con largo anticipo rispetto alla scadenza e imposta avvisi in caso di errori. Se un history ID salvato è fuori dall'intervallo disponibile in Gmail, l'API restituisce HTTP 404. Trattalo come un percorso di ripristino definito: esegui una sincronizzazione completa controllata, stabilisci un nuovo checkpoint e riprendi l'elaborazione incrementale invece di ritentare all'infinito l'history ID non valido.

Segui un flusso di implementazione e verifica per fasi

Primo, documenta se la funzionalità invia, legge, modifica o monitora la posta, e associa ogni operazione al suo ambito OAuth minimo. Secondo, crea progetti Google Cloud o client OAuth separati per sviluppo e produzione, con URI di reindirizzamento esatti e responsabili delle credenziali nominativi. Terzo, implementa l'autorizzazione con validazione dello state, accesso offline solo quando serve, archiviazione cifrata dei token, revoca dei token e controlli di accesso a livello di tenant. Quarto, testa con caselle controllate: collega, aggiorna un access token scaduto, revoca il consenso, ricollega, invia una volta, simula un timeout ambiguo e conferma la prevenzione dei duplicati. Quinto, se ricevi modifiche, configura i permessi Pub/Sub, avvia un watch, elabora la cronologia in modo incrementale, forza un ripristino da checkpoint obsoleto e verifica il rinnovo del watch. Sesto, aggiungi code di lavoro per utente, backoff esponenziale limitato, classificazione strutturata degli errori e log di audit che per impostazione predefinita omettano corpi dei messaggi e token. Prima del lancio, completa le verifiche di Google e le revisioni di sicurezza richieste, pubblica informative accurate sull'uso dei dati e prova la rotazione delle credenziali e la cancellazione dei dati utente.

Pianifica quote, nuovi tentativi ed errori parziali

Gmail misura l'uso dell'API in unità di quota, non solo nel conteggio delle richieste. La pagina delle quote di Google indica 1.200.000 unità al minuto per progetto e 6.000 unità al minuto per utente e progetto. Indica `messages.send`, `drafts.send` e `watch` a 100 unità ciascuno, e un limite di 500 destinatari per messaggio. I limiti separati di invio per utente di Gmail si applicano comunque a client API, web e SMTP. Considera la console Cloud e la documentazione corrente come input di configurazione a runtime anziché codificare in modo rigido i limiti pubblicati nella logica di business. Serializza o accoda equamente il lavoro per casella, limita la concorrenza e ritenta solo le risposte transitorie con backoff esponenziale con jitter e una scadenza finita. Non ritentare errori di autorizzazione, policy, destinatario non valido o messaggio non valido come se fossero problemi di capacità. Un batch multipart riduce l'overhead di connessione, ma ogni chiamata interna consuma comunque quota e può fallire in modo indipendente.

Tieni distinti accettazione, consegna e arrivo in inbox

Una chiamata `messages.send` riuscita significa che Gmail ha accettato la richiesta API autorizzata e ha restituito una risorsa Message di Gmail. Non dimostra che il server di posta di ogni destinatario abbia accettato il messaggio e non può stabilire come un sistema ricevente lo abbia classificato. La consegna al server del destinatario significa che il sistema di destinazione si è assunto la responsabilità SMTP. L'arrivo in inbox è un esito di filtraggio successivo, come inbox principale, promozioni, quarantena o spam. La API della casella Gmail non sostituisce quindi un flusso di eventi del provider quando un prodotto ha bisogno di telemetria su consegne, bounce o segnalazioni di spam (complaint) per la posta transazionale. Conserva l'ID del messaggio Gmail per la riconciliazione, ma descrivi lo stato visibile all'utente con precisione, come inviato o accettato da Gmail, a meno che prove separate non confermino la consegna. Autenticazione, destinatari attesi, qualità dei contenuti, comportamento di invio e policy di destinazione influenzano tutti la gestione a valle. Una risposta API non può determinare né promettere la cartella finale nella casella del destinatario.

Quando un'API per email transazionali serve a un compito diverso

Usa Gmail API quando il prodotto richiede l'accesso autorizzato alla casella Gmail di una persona o organizzazione, inclusi thread, etichette, bozze o sincronizzazione della casella. Un'API email transazionale si adatta a un'architettura diversa: messaggi attivati dall'applicazione inviati da domini controllati dall'organizzazione, senza autorità delegata per leggere la casella Gmail di un utente. Un prodotto può usare entrambi i tipi di sistemi quando i confini sono espliciti, ad esempio Gmail OAuth per leggere la casella connessa di un agente di assistenza e un provider transazionale verificato separatamente per inviare ricevute di prodotto. Mantieni separate credenziali, consenso, archivi dei messaggi, policy di nuovi tentativi e record di audit, così l'autorità sulla casella non può estendersi all'invio in tutta l'applicazione e una credenziale transazionale non può leggere la Gmail di un utente.

Domande frequenti

Un account di servizio può accedere a qualsiasi casella Gmail?

No. Un account di servizio non ottiene automaticamente l'accesso ai dati utente di Gmail. Un super amministratore di Google Workspace deve concedere la delega a livello di dominio al suo ID client numerico e agli ambiti approvati; solo allora l'applicazione può impersonare esplicitamente un utente di quell'organizzazione. Per gli account Gmail consumer, usa invece il consenso OAuth dell'utente.

Quale ambito OAuth dovrebbe richiedere un'integrazione Gmail di solo invio?

Inizia valutando `https://www.googleapis.com/auth/gmail.send`, che consente di inviare per conto dell'utente senza concedere l'accesso generale in lettura alla casella. Prima di richiedere un ambito più ampio, conferma che nessun requisito del prodotto abbia davvero bisogno di bozze, lettura dei messaggi, etichette o modifiche, e tieni conto delle regole di verifica di Google per gli ambiti sensibili.

Un invio riuscito con la Gmail API significa che il messaggio è stato consegnato?

No. Conferma che Gmail ha accettato l'operazione API autorizzata e ha restituito un record del messaggio. L'accettazione da parte del server ricevente e l'arrivo in inbox sono stati successivi e distinti. Non etichettare il messaggio come consegnato e non promettere l'arrivo in inbox, a meno che un altro segnale affidabile non supporti questa conclusione.

Le notifiche push di Gmail contengono l'intero nuovo messaggio?

No. Una notifica Pub/Sub segnala che lo stato della casella è cambiato e include le informazioni per proseguire la sincronizzazione. L'applicazione dovrebbe interrogare la cronologia di Gmail a partire dall'history ID salvato, recuperare i dati dei messaggi necessari, elaborarli in modo idempotente e poi far avanzare il checkpoint.

Ogni quanto va rinnovato il watch di una casella Gmail?

Google richiede di chiamare `watch` almeno una volta ogni sette giorni e raccomanda un rinnovo giornaliero. Salva la scadenza restituita, rinnova in anticipo, monitora gli errori e mantieni un job di sincronizzazione di riserva, così un rinnovo mancato non crea silenziosamente un buco nei dati senza limiti.

Quando un team dovrebbe usare un'API per email transazionali invece della Gmail API?

Usa un'API per email transazionali quando si tratta di email generate dall'applicazione da domini controllati dall'organizzazione e nessuna funzionalità ha bisogno di accedere alla casella Gmail di una persona. Usa la Gmail API quando il prodotto ha specificamente bisogno di un accesso delegato a messaggi, thread, etichette, bozze, impostazioni della casella o dell'autorizzazione send-as.

Fonti

Continua ad approfondire

Guida all'implementazione di un'API email per i team di prodottoProgetta un'integrazione sicura con un'API email: domini verificati, invii in coda, identificatori stabili, nuovi tentativi controllati, eventi di consegna, soppressioni e isolamento dei tenant.