Limiti di frequenza e quota dell'API Gmail, spiegati

L'API Gmail è l'interfaccia ufficiale di Google, non scraping IMAP o SMTP

L'API Gmail è un'interfaccia REST che Google pubblica e documenta per le app di terze parti. È una tecnologia diversa da IMAP o SMTP, i protocolli di posta più vecchi usati dai client email generici.

Clean Email supporta solo Gmail (account personali @gmail.com e account Google Workspace) perché è costruito appositamente su questa API. Outlook, Yahoo Mail, iCloud Mail e altre caselle IMAP generiche non sono supportate per lo stesso motivo.

• L'accesso viene concesso tramite l'accesso Google OAuth 2.0 — Clean Email non vede né memorizza mai la tua password Google.
• Ogni azione (scansione, conteggio, eliminazione) passa attraverso un endpoint documentato dell'API Gmail, non una connessione a protocollo grezzo.
• Trattandosi della stessa API che Google espone a qualsiasi sviluppatore, Clean Email è soggetto agli stessi limiti di frequenza pubblicati di qualsiasi altra app che usa l'API Gmail.

Quali endpoint dell'API Gmail usa Clean Email

Una pulizia usa un piccolo insieme di endpoint, ciascuno documentato nella guida di riferimento dell'API Gmail di Google.

• messages.list — trova gli ID dei messaggi che corrispondono alla query di scansione di Clean Email, quella che esclude la posta protetta (ad esempio -is:starred -has:attachment -in:sent). Restituisce solo ID, non il contenuto dei messaggi.
• messages.get (formato metadata) — recupera solo intestazioni, etichette, dimensione e ID del thread di ogni messaggio. Clean Email non richiede mai il corpo del messaggio.
• messages.trash / batchModify — il percorso di eliminazione predefinito: sposta i messaggi corrispondenti nel Cestino di Gmail, dove restano recuperabili per 30 giorni.
• messages.batchDelete — usato solo per l'opzione facoltativa ed esplicita di eliminazione permanente, come documentato nella guida di Google sull'eliminazione in blocco. Questa azione è irreversibile.

Unità di quota dell'API Gmail e limiti al secondo

L'API Gmail non si limita a contare le richieste — addebita ogni chiamata in 'unità di quota', e le chiamate economiche costano meno di quelle costose. Il riferimento dell'API Gmail di Google è la fonte autorevole per i valori attuali; le cifre qui sotto sono quelle pubblicate.

• Google può rivedere questi costi per metodo nel tempo — considera sempre il riferimento dell'API Gmail come la fonte di verità attuale, non questa pagina.

Come l'elaborazione a blocchi di Clean Email resta entro la quota

Una casella di posta con decine di migliaia di email non può essere ripulita con un'unica chiamata API gigante senza rischiare di superare il limite di quota al secondo. Clean Email divide le grandi pulizie in blocchi più piccoli invece di inviare tutte le richieste in una volta.

Se Gmail risponde con un errore di limite di frequenza su una determinata chiamata, Clean Email ritenta quel blocco invece di interrompere l'intera pulizia. Ecco perché una casella di posta molto grande può impiegare più tempo per completarsi, in fasi visibili, invece di terminare all'istante — è un comportamento previsto, non un errore.

Domande frequenti

Qual è il limite di frequenza dell'API Gmail?

Il valore predefinito pubblicato da Google è 250 unità di quota per utente al secondo, misurato come media mobile, quindi brevi picchi oltre questo numero sono consentiti. Ogni progetto Google Cloud ha anche una propria quota giornaliera complessiva, visibile e modificabile in Google Cloud Console. Consulta il riferimento dell'API Gmail di Google per le cifre attuali.

Clean Email usa IMAP o SMTP per accedere al mio Gmail?

No. Clean Email si collega a Gmail esclusivamente tramite l'API Gmail ufficiale di Google usando l'accesso OAuth. Non effettua mai l'accesso a un server IMAP o SMTP e non esegue mai lo scraping diretto della tua casella di posta.

Quante unità di quota costa eliminare le email?

Le chiamate di lettura come messages.list e messages.get costano poche unità di quota ciascuna (5 unità per chiamata, secondo la tabella pubblicata da Google), mentre un'azione in massa come messages.batchDelete costa di più per chiamata (50 unità) perché può agire su molti messaggi contemporaneamente. Google può aggiornare queste cifre, quindi il suo riferimento dell'API Gmail è la fonte autorevole.

Perché una grande pulizia di Gmail richiede più tempo del previsto?

Le caselle di posta molto grandi vengono elaborate a blocchi invece che con un'unica richiesta gigante, così la pulizia resta entro i limiti di quota al secondo e per progetto di Gmail. Questo significa che una pulizia enorme si completa a fasi invece che all'istante, ma evita anche che fallisca del tutto o venga limitata.

Cosa succede se Gmail limita una richiesta durante una pulizia?

L'API Gmail restituisce un errore di limite di frequenza se chi effettua la chiamata supera la propria quota in un dato momento. L'elaborazione a blocchi di Clean Email è progettata per restare entro questi limiti e ritenta automaticamente il blocco interessato invece di interrompere l'esecuzione, così una limitazione temporanea non causa una pulizia fallita né perdita di dati.

Clean Email può ripulire Outlook, Yahoo Mail o iCloud Mail allo stesso modo?

No. Clean Email supporta solo Gmail — account personali @gmail.com e account Google Workspace — tramite l'API Gmail. Outlook, Yahoo Mail, iCloud Mail e altre caselle IMAP generiche non sono supportate.