Nutzungsbeschränkungen

Für die Gmail API gelten Nutzungslimits, die die Häufigkeit einschränken, mit der Sie API-Methoden aufrufen können. Limits werden in Kontingenteinheiten definiert, einer abstrakten Maßeinheit, die die Gmail-Ressourcennutzung darstellt.

Gmail API-Kontingente

Die Gmail API erzwingt zwei Arten von Kontingenten:

  • Pro Minute und Projekt: Dies ist die Anzahl der Kontingenteinheiten, die Ihr Google Cloud-Projekt in einer Minute verwenden kann.

  • Pro Minute pro Nutzer pro Projekt: Dies ist die Anzahl der Kontingenteinheiten, die ein bestimmter Nutzer in Ihrem Cloud-Projekt verwenden kann. Dieses Limit trägt zu einer fairen Verteilung der Nutzung unter Ihren Nutzern bei.

In der folgenden Tabelle werden diese Limits im Detail beschrieben:

Typ des Nutzungslimits Limit
Pro Minute und Projekt 1.200.000 Kontingenteinheiten
Pro Minute, Nutzer und Projekt 6.000 Kontingenteinheiten

Informationen zum Umgang mit Limitfehlern finden Sie unter Fehler beheben.

Täglicher Schwellenwert für die Abrechnung

Dieses Limit pro Tag und Projekt definiert die maximale Anzahl von Kontingenteinheiten, die Ihr Google Cloud-Projekt innerhalb eines 24-Stunden-Zeitraums verwenden kann, bevor Gebühren anfallen.

Bei einer Nutzung unter diesem Schwellenwert fallen keine zusätzlichen Gebühren an und Ihr Google Cloud-Konto wird nicht belastet. Google wird im Laufe des Jahres 2026 alle Abrechnungsdetails bekannt geben, und zwar mindestens 90 Tage vor Inkrafttreten der Änderungen.

Sie können keine Erhöhung dieses täglichen Grenzwerts anfordern.

In der folgenden Tabelle wird das Limit näher erläutert:

Typ des Grenzwerts Limit
Pro Tag und Projekt 80.000.000 Kontingenteinheiten

Weitere Informationen finden Sie unter Standardisiertes Google Workspace-Modell für Agent-Tools und APIs.

Kontingentnutzung pro Methode

Die Anzahl der Kontingenteinheiten, die für jede Anfrage verbraucht werden, variiert je nach aufgerufener Methode und Suchparametern. In der folgenden Tabelle wird die Nutzung der Kontingenteinheiten pro Methode beschrieben:

Methode Kontingenteinheiten
drafts.create 10
drafts.delete 10
drafts.get 20 (60, wenn format full, raw oder html ist)
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, wenn format full, raw oder html ist)
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, wenn format full ist)
threads.list 10
threads.modify 10
threads.trash 20
threads.untrash 10
watch 100

Bei Verwendung der Gmail API gilt außerdem ein Limit von 500 Empfängern pro E‑Mail-Nachricht.

Zeitbasierte Kontingentfehler beheben

Bei allen zeitbasierten Fehlern (maximal N Anfragen pro X Minuten) empfehlen wir, dass Ihr Code die Ausnahme abfängt und einen gekürzten exponentiellen Backoff verwendet, damit Ihre Geräte keine übermäßige Last erzeugen.

Der exponentielle Backoff ist eine Standardstrategie zur Fehlerbehandlung für Netzwerkanwendungen. Ein exponentieller Backoff-Algorithmus wiederholt Anfragen mit exponentiell zunehmenden Wartezeiten zwischen den Anfragen bis zur maximalen Backoff-Zeit. Wenn Anfragen weiterhin fehlschlagen, ist es wichtig, dass die Verzögerungen zwischen den Anfragen im Laufe der Zeit zunehmen, bis die Anfrage erfolgreich ist.

Beispielalgorithmus

Ein exponentieller Backoff-Algorithmus wiederholt Anfragen exponentiell und verlängert dabei die Wartezeit zwischen zwei Wiederholungen bis zur maximalen Backoff-Zeit. Beispiel:

  1. Stellen Sie eine Anfrage an die Gmail API.
  2. Wenn die Anfrage fehlschlägt, wartet das System 1 + random_number_milliseconds und wiederholt dann die Anfrage.
  3. Wenn die Anfrage fehlschlägt, wartet das System 2 + random_number_milliseconds Sekunden und wiederholt dann die Anfrage.
  4. Wenn die Anfrage fehlschlägt, wartet das System 4 + random_number_milliseconds Sekunden und wiederholt dann die Anfrage.
  5. Und so weiter bis zur maximum_backoff-Zeit.
  6. Setzen Sie die Wartezeit fort und wiederholen Sie den Vorgang bis zu einer maximalen Anzahl an Wiederholungsversuchen. Erhöhen Sie jedoch nicht die Wartezeit zwischen den Wiederholungsversuchen.

Dabei gilt:

  • Die Wartezeit beträgt min(((2^n)+random_number_milliseconds), maximum_backoff), wobei n bei jeder Ausführung (Anfrage) um 1 erhöht wird.
  • random_number_milliseconds steht für eine zufällige Anzahl von Millisekunden,deren Wert kleiner oder gleich 1.000 ist. So wird vermieden, dass viele Clients durch eine bestimmte Situation synchronisiert werden und alle gleichzeitig Wiederholungsversuche starten und Anfragen in synchronisierten Wellen senden. Der Wert von random_number_milliseconds wird nach jeder Anfragewiederholung neu berechnet.
  • maximum_backoff ist normalerweise 32 oder 64 Sekunden lang. Der geeignete Wert hängt vom jeweiligen Anwendungsfall ab.

Der Client kann den Vorgang wiederholen, nachdem er die maximum_backoff-Zeit erreicht hat. Die Backoff-Zeit muss dabei nicht mehr verlängert werden. Wenn ein Client beispielsweise eine maximum_backoff-Zeit von 64 Sekunden verwendet, kann er den Vorgang nach Erreichen dieses Werts alle 64 Sekunden noch einmal versuchen. Sie sollten jedoch dafür sorgen, dass er dies nicht unbegrenzt tut.

Die Wartezeit zwischen den Wiederholungen und der Anzahl der Wiederholungen hängt von Ihrem Anwendungsfall und den Netzwerkbedingungen ab.

Preise

Die Standardnutzung der Gmail API ist kostenlos. Wenn Sie die Kontingentlimits für Anfragen überschreiten, fallen voraussichtlich später im Jahr 2026 Gebühren für Ihr Google Cloud-Rechnungskonto an. Weitere Informationen finden Sie unter Standardisiertes Google Workspace-Modell für Agent-Tools und APIs.

Kontingenterhöhung anfordern

Abhängig von der Ressourcennutzung Ihres Projekts möchten Sie möglicherweise eine Kontingentanpassung anfordern. API-Aufrufe über ein Dienstkonto werden so behandelt, als würden sie über ein einzelnes Konto erfolgen. Wenn Sie ein angepasstes Kontingent beantragen, bedeutet dies nicht, dass Ihr Antrag auch genehmigt wird. Anfragen zur Kontingentanpassung, die den Kontingentwert erheblich erhöhen würden, können länger dauern, bis sie genehmigt werden.

Es gelten nicht für alle Projekte dieselben Kontingente. Wenn Sie Google Cloud mit der Zeit stärker nutzen, müssen Ihre Kontingentwerte möglicherweise erhöht werden. Falls Sie eine deutlich stärkere Auslastung erwarten, können Sie auf der Seite Kontingente und Systemlimits der Google Cloud Console eine Anpassung Ihres Kontingents anfordern.

Weitere Informationen finden Sie in folgenden Dokumenten:

Kontingente für den Gmail-MCP-Server

Der Gmail-MCP-Server verwendet einen Messwert für die Abfragekostenzuordnung. In den folgenden Tabellen sind die Abfragekosten für die einzelnen Gmail-MCP-Servermethoden nach Abschnitt aufgeführt:

Gmail-MCP-Kontingente

Der Server erzwingt zwei Arten von Kontingenten:

  • Pro Minute und Projekt: Dies sind die Abfragekosten für Ihr Cloud-Projekt für eine Minute.

  • Pro Minute, Nutzer und Projekt: Dies sind die Abfragekosten für Ihr Cloud-Projekt für eine Minute, die ein bestimmter Nutzer verwenden kann.

In der folgenden Tabelle werden diese Kontingente aufgeführt:

Typ des Nutzungslimits Abfragekosten
Pro Minute und Projekt 1.200.000
Pro Minute, Nutzer und Projekt 6.000

Kontingente für Gmail-MCP-Tools

In der folgenden Tabelle sind die Abfragekosten für die einzelnen gmailmcp.googleapis.com-Toolsets aufgeführt:

Endpunkt Tool Abfragekosten

/mcp/v1

create_draft

10

get_thread

40

label_message

10

label_thread

10

list_drafts

5

list_labels

1

search_threads

10

unlabel_message

10

unlabel_thread

10

Weitere Informationen finden Sie in der Referenz zur Gmail MCP API.