L'API Gmail è soggetta a limiti di utilizzo che limitano la frequenza con cui puoi chiamare i metodi 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
L'API Gmail applica due tipi di quote:
Al minuto per progetto cloud: questo è il numero di unità di quota che il tuo progetto cloud Google Cloud può utilizzare in un minuto.
Al minuto per utente per progetto: questo è il numero di unità di quota che un singolo utente può utilizzare nel tuo progetto Cloud. Questo limite contribuisce a garantire una distribuzione equa dell'utilizzo tra i tuoi utenti.
La tabella seguente descrive 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 relativi ai limiti, consulta Risolvi gli errori.
Soglia di fatturazione giornaliera
Questo limite per giorno 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 non viene addebitato al tuo account Google Cloud. Google condividerà i dettagli completi sulla fatturazione nel corso del 2026 con un preavviso di almeno 90 giorni prima dell'entrata in vigore di eventuali modifiche.
Non puoi richiedere un aumento di questo limite di soglia giornaliero.
La tabella seguente descrive il limite:
| Tipo di limite di soglia | Limite |
|---|---|
| Al giorno per progetto | 80.000.000 di unità di quota |
Per saperne di più, consulta il modello standardizzato di Google Workspace per gli strumenti e le API degli agenti.
Utilizzo della quota per metodo
Il numero di unità di quota consumate da ogni richiesta varia a seconda del metodo chiamato e dei parametri di query. La tabella seguente descrive l'utilizzo delle unità di quota per metodo:
| Metodo | Unità di quota |
|---|---|
drafts.create |
10 |
drafts.delete |
10 |
drafts.get |
20 (60 quando format è full, raw o html) |
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 (60 quando format è full, raw o html) |
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 (120 quando format è full) |
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.
Risolvi gli errori di quota basati sul tempo
Per tutti gli errori basati sul tempo (massimo N richieste per X minuti), ti consigliamo di fare in modo che il codice rilevi l'eccezione e utilizzi un backoff esponenziale troncato per assicurarti che i 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 riprova le richieste utilizzando tempi di attesa che aumentano in modo esponenziale tra le richieste, fino a un tempo di backoff massimo. Se le richieste continuano a non andare 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 riprova le richieste in modo esponenziale, aumentando il tempo di attesa tra i nuovi tentativi fino a un tempo di backoff massimo. Ad esempio:
- Invia una richiesta all'API Gmail.
- Se la richiesta non va a buon fine, attendi 1 +
random_number_millisecondse riprova a inviare la richiesta. - Se la richiesta non va a buon fine, attendi 2 +
random_number_millisecondse riprova a inviare la richiesta. - Se la richiesta non riesce, attendi 4 +
random_number_millisecondse riprova a inviare la richiesta. - E via così fino all'
maximum_backoffintervallo di backoff massimo. - Continua ad attendere e riprovare fino al numero massimo di nuovi tentativi, ma non aumentare il periodo di attesa tra i nuovi tentativi.
dove:
- Il tempo di attesa è
min(((2^n)+random_number_milliseconds), maximum_backoff), connincrementato di 1 per ogni iterazione (richiesta). random_number_millisecondsè un numero casuale di millisecondi inferiore o uguale a 1000. In questo modo si evitano i casi in cui molti client vengono sincronizzati da una determinata situazione e tutti riprovano contemporaneamente, inviando richieste in ondate sincronizzate. Il valore dirandom_number_millisecondsviene ricalcolato dopo ogni richiesta di nuovo tentativo.maximum_backoffè in genere di 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 della rete.
Prezzi
L'utilizzo standard dell'API Gmail è disponibile senza costi aggiuntivi. Il superamento dei limiti delle richieste di quota comporterà addebiti sul tuo account di fatturazione Google Cloud nel corso del 2026. Per saperne di più, 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 effettuate da un service account vengono considerate come se utilizzassero un singolo account. La richiesta di aggiustamento di una quota non ne garantisce l'approvazione. Le richieste di aggiustamento della quota che aumenterebbero in modo significativo il valore della quota possono richiedere più tempo per essere approvate.
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:
- Informazioni sugli aggiustamenti delle quote
- Visualizza l'utilizzo e i limiti della quota
- Richiedi un limite di quota più alto
Quote del server MCP di Gmail
Il server MCP di Gmail utilizza una metrica di allocazione dei costi delle query. Le tabelle seguenti descrivono nel dettaglio il costo delle query per ogni metodo del server MCP di Gmail per sezione:
Quote MCP di Gmail
Il server applica due tipi di quote:
Per minuto per progetto: questo è il costo delle query per il tuo progetto Cloud per un minuto.
Al minuto per utente per progetto: questo è il costo delle query per il tuo progetto Cloud per un minuto che un utente specifico può utilizzare.
La tabella seguente descrive in dettaglio queste quote:
| Tipo di limite di utilizzo | Costo della query |
|---|---|
| Al minuto per progetto | 1.200.000 |
| Al minuto per utente per progetto | 6000 |
Quote del set di strumenti MCP di Gmail
La tabella seguente descrive in dettaglio il costo delle query per ogni set di strumenti gmailmcp.googleapis.com:
| Endpoint | Strumento | Costo delle query |
|---|---|---|
/mcp/v1 |
|
10 |
|
40 |
|
|
10 |
|
|
10 |
|
|
5 |
|
|
1 |
|
|
10 |
|
|
10 |
|
|
10 |
Per saperne di più, consulta il Riferimento API Gmail MCP.