Limiti di utilizzo

L'API Gmail è soggetta a limiti di utilizzo che limitano la frequenza con cui è possibile chiamare i metodi dell'API. I limiti sono definiti in termini di unità di quota, un'unità di misura astratta che rappresenta l'utilizzo delle risorse di Gmail.

Quote dell'API Gmail

Vengono applicati due tipi di quote:

  • Al minuto per progetto:è il numero di unità di quota che il tuo progetto Google Cloud può utilizzare in un minuto.

  • Al minuto per utente per progetto:è il numero di unità di quota che un utente specifico può utilizzare nel tuo progetto Cloud. Questo limite ha lo scopo di aiutarti a garantire una distribuzione equa dell'utilizzo tra i tuoi utenti.

La tabella seguente descrive in dettaglio questi limiti:

Tipo di limite di utilizzo Limite
Al minuto per progetto 1.200.000 unità di quota
Al minuto per utente per progetto 6000 unità di quota

Per informazioni sulla gestione degli errori di limite, consulta Risolvere gli errori.

Soglia di fatturazione giornaliera

Questo limite giornaliero per progetto definisce il numero massimo di unità di quota che il tuo progetto Google Cloud può utilizzare in un periodo di 24 ore prima che vengano applicati addebiti.

L'utilizzo al di sotto di questa soglia non comporta costi aggiuntivi e il tuo account Google Cloud non viene fatturato. I dettagli di fatturazione completi verranno condivisi più avanti nel 2026 con un preavviso di almeno 90 giorni prima che le modifiche diventino effettive.

Non puoi richiedere un aumento di questo limite di soglia giornaliero.

La tabella seguente descrive in dettaglio il limite:

Tipo di limite di soglia Limite
Al giorno per progetto 80.000.000 unità di quota

Per ulteriori informazioni, consulta Modello standardizzato di Google Workspace per strumenti degli agenti e API.

Utilizzo delle quote per metodo

Il numero di unità di quota consumate per richiesta varia a seconda del metodo chiamato. La tabella seguente illustra l'utilizzo delle unità di quota per metodo:

Metodo Unità di quota
drafts.create 10
drafts.delete 10
drafts.get 20
drafts.list 5
drafts.send 100
drafts.update 15
getProfile 1
history.list 2
labels.create 5
labels.delete 5
labels.get 1
labels.list 1
labels.update 5
messages.attachments.get 20
messages.batchDelete 50
messages.batchModify 50
messages.delete 10
messages.get 20
messages.import 25
messages.insert 25
messages.list 5
messages.modify 5
messages.send 100
messages.trash 20
messages.untrash 5
settings.delegates.create 100
settings.delegates.delete 5
settings.delegates.get 1
settings.delegates.list 1
settings.filters.create 5
settings.filters.delete 5
settings.filters.get 1
settings.filters.list 1
settings.forwardingAddresses.create 100
settings.forwardingAddresses.delete 5
settings.forwardingAddresses.get 1
settings.forwardingAddresses.list 1
settings.getAutoForwarding 1
settings.getImap 1
settings.getPop 1
settings.getVacation 1
settings.sendAs.create 100
settings.sendAs.delete 5
settings.sendAs.get 1
settings.sendAs.list 1
settings.sendAs.update 100
settings.sendAs.verify 100
settings.updateAutoForwarding 5
settings.updateImap 5
settings.updatePop 100
settings.updateVacation 5
stop 50
threads.delete 20
threads.get 40
threads.list 10
threads.modify 10
threads.trash 20
threads.untrash 10
watch 100

Quando utilizzi l'API Gmail, esiste anche un limite di 500 destinatari per messaggio email.

Risolvere gli errori di quota basati sul tempo

Per tutti gli errori basati sul tempo (massimo N richieste ogni X minuti), ti consigliamo di fare in modo che il codice rilevi l'eccezione e utilizzi un backoff esponenziale troncato per assicurarti che i tuoi dispositivi non generino un carico eccessivo.

Il backoff esponenziale è una strategia standard di gestione degli errori per le applicazioni di rete. Un algoritmo di backoff esponenziale ripete i tentativi di richiesta utilizzando tempi di attesa in aumento esponenziale tra le richieste, fino a un tempo di backoff massimo. Se le richieste non vanno ancora a buon fine, è importante che i ritardi tra le richieste aumentino nel tempo fino a quando la richiesta non va a buon fine.

Algoritmo di esempio

Un algoritmo di backoff esponenziale ripete i tentativi di richiesta in modo esponenziale, aumentando il tempo di attesa tra i tentativi fino a un tempo di backoff massimo. Ad esempio:

  1. Invia una richiesta all'API Gmail.
  2. Se la richiesta non va a buon fine, attendi 1 + random_number_milliseconds e riprova la richiesta.
  3. Se la richiesta non va a buon fine, attendi 2 + random_number_milliseconds e riprova la richiesta.
  4. Se la richiesta non va a buon fine, attendi 4 + random_number_milliseconds e riprova la richiesta.
  5. E così via, fino a un tempo maximum_backoff.
  6. Continua ad attendere e a riprovare fino a un numero massimo di tentativi, ma non aumentare il periodo di attesa tra i tentativi.

dove:

  • Il tempo di attesa è min(((2^n)+random_number_milliseconds), maximum_backoff), con n incrementato di 1 per ogni iterazione (richiesta).
  • random_number_milliseconds è un numero casuale di millisecondi minore o uguale a 1000. In questo modo, si evitano casi in cui molti client vengono sincronizzati da una determinata situazione e tutti riprovano contemporaneamente, inviando richieste in onde sincronizzate. Il valore di random_number_milliseconds viene ricalcolato dopo ogni tentativo di richiesta.
  • maximum_backoff è in genere 32 o 64 secondi. Il valore appropriato dipende dal caso d'uso.

Il client può continuare a riprovare dopo aver raggiunto il tempo maximum_backoff. I nuovi tentativi dopo questo punto non devono continuare ad aumentare il tempo di backoff. Ad esempio, se un client utilizza un valore maximum_backoff di 64 secondi, dopo aver raggiunto questo valore, il client può riprovare ogni 64 secondi. A un certo punto, è necessario impedire ai client di effettuare ulteriori tentativi indefinitamente.

Il tempo di attesa tra i tentativi e il numero di tentativi dipendono dal caso d'uso e dalle condizioni di rete.

Prezzi

Tutto l'utilizzo standard dell'API Gmail è disponibile senza costi aggiuntivi. Il superamento dei limiti delle richieste di quota è previsto per l'addebito sul tuo account di fatturazione Google Cloud più avanti nel 2026. Per ulteriori informazioni, consulta Modello standardizzato di Google Workspace per strumenti e API degli agenti.

Richiedi un aumento della quota

A seconda dell'utilizzo delle risorse del progetto, potresti voler richiedere un aggiustamento della quota. Le chiamate API di un account di servizio sono considerate come se utilizzassero un singolo account. La richiesta di una quota aggiustata non ne garantisce l'approvazione. L'approvazione delle richieste di aggiustamento della quota che aumenterebbero in modo significativo il valore della quota può richiedere più tempo.

Non tutti i progetti hanno le stesse quote. Man mano che utilizzi sempre più Google Cloud nel tempo, i valori delle quote potrebbero dover aumentare. Se prevedi un aumento imminente e consistente dell'utilizzo, puoi richiedere un aggiustamento della quota in modo proattivo nella pagina Quote e limiti di sistema della console Google Cloud.

Per saperne di più, consulta le seguenti risorse: