LinkedIn
Instagram
WhatsApp
Telegramm
Google Mail
Ausblick
Google Kalender
Slack-Gemeinschaft beitretenGmail API-Limits im Jahr 2026: Kontingente, Ratenbegrenzungen, und wie man mit ihnen umgeht
Gmail API Kontingentreferenz: minütliche, pro Benutzer und tägliche Limits pro Methode, Kosten pro Einheit, 429-Fehlerbehandlung und ein produktionsreifes Exponential-Backoff-Muster für authentifizierte Benutzer.
async function withBackoff(fn, maxRetries = 5) { let delay = 1000; for (let i = 0; i < maxRetries; i++) { try { return await fn(); } catch (err) { if (err.code !== 429) throw err; const jitter = Math.random() * 500; await sleep(delay + jitter); delay *= 2; } }}Gültigkeitsbereich der authentifizierten Benutzersitzung
Unipile unterhält kein paralleles Archiv der Gmail-Postfachdaten. Der gesamte E-Mail-Zugriff erfolgt Geltungsbereich der Sitzung des authentifizierten Benutzers wer explizit die OAuth-Zustimmung erteilt hat. Es werden keine Daten unabhängig davon gespeichert, was zur Bearbeitung dieser spezifischen Anfrage erforderlich ist.
Unabhängiger technischer Vermittler
Unipile fungiert als unabhängiger technischer Vermittler, Anrufe an die Gmail API im Namen jedes einzelnen authentifizierten Nutzers tätigen. Unipile ist kein Google-Partner oder angeschlossenes Unternehmen. Es werden keine Anmeldeinformationen zwischen Nutzern geteilt. Jeder OAuth-Token gehört ausschließlich dem Nutzer, der ihn erteilt hat.
Cadence ist die Entscheidung des Kunden
Unipile leitet die Ratenbegrenzungen und Quotenbeschränkungen der Gmail API weiter, wie von Google definiert. Die Häufigkeit und das Volumen der getätigten API-Aufrufe im Namen von jeder Nutzer ist ein Kundenentscheidung. Unipile gleicht Quotenfehler aus und wendet eine Backoff-Logik an, aber die aufrufende Kadenz bleibt unter der Kontrolle des Entwicklers.
Gmail API-Limits im Überblick
Bevor Sie auch nur eine Zeile Wiederholungslogik schreiben, benötigen Sie ein klares Bild aller drei Kontingentachsen, die Google durchsetzt. Die folgende Tabelle ist die Referenz, die Sie als Lesezeichen speichern werden: Durchsatz pro Projekt, Limits pro Benutzer und die tägliche Obergrenze, die um Mitternacht Pacific Time zurückgesetzt wird.
| Grenze | Wert | Dimension | Notizen |
|---|---|---|---|
| Gmail API Ratenbegrenzung (Kontingenteinheiten) | 1.200.000 / min | Pro GCP-Projekt | Freigegeben für alle Benutzer im Projekt |
| Gmail API pro Benutzer-Ratenbegrenzung | 6.000 / min | Pro Benutzer-Postfach | Häufigste Ursache für 429 in der Produktion |
| Tägliches Kontingent | 80.000.000 / Tag | Pro GCP-Projekt | Zurücksetzung um Mitternacht Pazifischer Zeit |
| Gmail-Sendebeschränkung (kostenloses Gmail) | 500 E-Mails / Tag | Absenderadresse | 2.000 / Tag für Google Workspace |
| Gleichzeitige Anfragen pro Postfach | 50 | Pro Postfach | Verstecktes Limit - löst 429 unabhängig vom Kontingent aus |
| Stapelverarbeitungsanfragen pro Aufruf | 100 Anfragen | Pro Stapelaufruf | Bündeln zum Reduzieren des Verbrauchs von Quota-Einheiten |
| Maximale Nachrichtengröße (Anhänge) | 25 MB | Pro Nachricht | Mit Headern und codiertem Body |
Google Developers Dokumentation, Gmail API - Nutzungslimits (zuletzt geprüft Mai 2026). Limits können sich ändern; überprüfen Sie immer die Quoten-Seite Ihrer GCP-Konsole auf die aktuellen Werte für Ihr Projekt.
Die drei Quoten-Dimensionen
Gmail API-Nutzungslimits arbeiten gleichzeitig über drei unabhängige Achsen. Eine Anfrage kann gesperrt werden, auch wenn zwei der drei in Ordnung sind. Das Verständnis der Trennung zwischen projektbezogenen, benutzerspezifischen und täglichen Limits ist der erste Schritt, um resilienten Code für jeden authentifizierten Benutzer zu schreiben.
Pro Projekt (GCP)
1.200.000 Einheiten/minDies ist die Deckensumme über alle Nutzer innerhalb eines GCP-Projekts hinweg. Wenn 500 authentifizierte Nutzer gleichzeitig Gmail API-Aufrufe tätigen, wird der gesamte Kontingentverbrauch gegen diesen einen Topf gezählt. Das Erreichen dieses Limits löst ein RateLimitUeberschritten 429. Das Tagesäquivalent beträgt 80 Millionen Einheiten, zurückgesetzt um Mitternacht Pazifikzeit.
Pro Benutzer (pro Postfach)
6.000 Einheiten/MinuteDiese Obergrenze gilt unabhängig für jeder authentifizierte Benutzer. Selbst wenn Ihr Projekt über freien Kontingentspielraum verfügt, wird ein einzelner Benutzer, der seine eigene Mailbox mit schnellem Abfragen überlastet, ein auslösen BenutzerRatenlimitÜberschritten 429. Bei Multi-Tenant-Apps ist dies das Limit, das am häufigsten ausgelöst wird: Es gilt pro Benutzer und wird nicht geteilt.
Tägliches Kontingent
80.000.000 Einheiten/TagDas Tageslimit gilt ebenfalls pro Projekt. Im Gegensatz zu den Minutengrenzen, die sich nach 60 Sekunden automatisch wieder erholen, wird das Erreichen des Tageskontingent bedeutet keinen weiteren API-Zugriff bis Mitternacht Pazifikzeit. Der Fehler lautet TageslimitÜberschritten. Sie können eine Quotenanforderung über die GCP-Konsole stellen – das behandeln wir im Abschnitt zu Mandantenfähigkeit.
Das ist wichtig: Die Gmail API-Ratenbegrenzungen werden in "Kontingenteinheiten" und nicht in rohen Anforderungsanzahlen gemessen. A Nachrichten senden Anruf kostet 100 Einheiten, während ein Nachrichtenliste kostet nur 5. Das bedeutet, Ihr Budget für praktische Anfragen variiert erheblich, je nachdem, welche Methoden Sie aufrufen. Siehe die Tabelle der Einheitskosten im nächsten Abschnitt. Beachten Sie außerdem, dass OAuth-Berechtigungsprüfung Fehler aus dem Zustimmungsfluss sind vollständig von diesen Laufzeit-Kontingentfehlern getrennt.
Kontingenteinheit Kosten pro Methode
Nicht alle Gmail API-Aufrufe sind gleich. Google zählt die Nutzung des Kontingents in abstrakten "Einheiten", und jede Methode hat unterschiedliche Kosten. Wenn Sie diese Kosten kennen, können Sie Ihre tatsächliche Anfragekapazität berechnen und optimieren, welche Endpunkte Sie aufrufen. Das pro Benutzer geltende Ratenlimit der Gmail API von 6.000 Einheiten/Minute verhält sich je nach Aufrufmischung sehr unterschiedlich.
| Methode | Stückkosten | Anfragen / Minute (pro Benutzer) | Optimierungstipp |
|---|---|---|---|
| Nachrichten senden | 100 | 60 Sendeungen/Minute maximal | Höchste Kosten – Entwurf verwenden + nur bei Bedarf senden |
| Nachrichten.einfügen | 25 | 240/min max | Einfügen in den Posteingang - niedriger als senden |
| threads.get | 10 | 600/min max | Bevorzuge threads.get gegenüber mehreren messages.get |
| Nachrichten.abrufen | 5 | 1.200/minsetMax | Füge fields= partial response hinzu, um die Kosten bei 5 zu halten |
| Nachrichtenliste | 5 | 1.200/minsetMax | Verwenden Sie history.list für Synchronisierungsmuster |
| threads.liste | 5 | 1.200/minsetMax | Paginieren Sie mit maxResults, um Aufrufe zu reduzieren |
| Benutzerverlauf Liste | 2 | 3.000 U/min max | Am besten für inkrementelle Synchronisierung - kostengünstigste Abfrage |
| labels.list | 1 | 6.000/min max | Zwischenspeichern des Ergebnisses – Labels ändern sich selten |
| Nachrichten.ändern | 5 | 1.200/minsetMax | Verwenden Sie batchModify für Massenaktualisierungen von Labels |
| nachrichten.anhänge.holen | 5 | 1.200/minsetMax | Anhänge nur abrufen, wenn sie explizit benötigt werden |
Profi-Tipp: Sie können die Felder= Abfrageparameter für partielle Antworten bei jeder Methode. Das Anfordern nur der Felder, die Ihre Anwendung benötigt, reduziert nicht die Rohkosten pro Einheit, aber es reduziert die Größe der Antwortnutzlast und die Latenz dramatisch – ein lohnender Kompromiss, wenn Sie sich den Gmail API-Kontingentlimits nähern. Testen Sie Ihre Abfragen interaktiv mit dem Gmail OAuth Playground bevor Sie in die Produktion gehen.
Das versteckte Limit von 50 parallelen Anfragen pro Mailbox
Es gibt eine Grenze, die die meisten Gmail-API-Tutorials nie erwähnen, aber sie ist die Ursache für mysteriöse 429-Fehler in Multi-Threaded- oder asynchronen Anwendungen: Gmail erzwingt ein Maximum von 50 gleichzeitige Inflight-Anfragen pro Mailbox. Dieses Limit ist vollständig unabhängig von Ihrem Kontingenteinheitenbudget. Sie können sich bei 500 Kontingenteinheiten von 6.000 verfügbaren befinden und trotzdem eine 429 erhalten, wenn Sie 51 Anfragen gleichzeitig gegen das Postfach desselben authentifizierten Benutzers offen haben.
Warum das Entwickler überrascht
Asynchrone Frameworks wie Node.js Promise.all() oder Python asyncio.gather() mache es trivial einfach, über 100 gleichzeitige Anfragen auszulösen. Wenn du eine Mailbox-Synchronisation verarbeitest und 200 Nachrichten gleichzeitig abrufst im Namen eines einzelnen authentifizierten Benutzers, Gmail sieht 200 offene TCP-Verbindungen für ein Postfach und drosselt sie sofort. Das Quoten-Dashboard in GCP zeigt noch genügend Einheiten an – die 50-Gleichzeitigkeitsgrenze wird nicht als Quotenmetrik angezeigt.
Wenn es auslöst
Das 50-gleichzeitige Anfragen-Limit tritt bei Massen-Postfachsynchronisierungsoperationen auf: beim Abrufen großer Threads, beim gleichzeitigen Herunterladen von Anhängen für viele Nachrichten oder beim Paginieren durch große Label-Anzahlen, während gleichzeitig Ergebnisse verarbeitet werden. Jeder Code, der mehr als 50 gleichzeitig laufende Anfragen an dasselbe Postfach startet, wird dieses Limit erreichen.
Wie man es repariert
nutzen Sie eine Nebenläufigkeitsbegrenzung (Semaphore), die pro authentifiziertem Benutzer geskort ist. In Node.js, Bibliotheken wie p-Grenze gut. In Python, ein asyncio.Semaphore(40) mit einem sicheren Puffer unter 50 wird ein Überlauf verhindert. Halten Sie Ihre Pro-Benutzer-Gleichzeitigkeit auf 40 oder darunter Für Sicherheitsmarge.
// p-limit hält die Gleichzeitigkeit pro Benutzer unter 40import pLimit from 'p-Limit';// Eine Limiter-Instanz pro authentifiziertem Benutzer (indiziert nach userId)const nutzerBeschränkungen = new Karte();Funktion Begrenzer abrufen(userId) { wenn !NutzerBeschränkungen.hat(userId)) { Nutzerbegrenzer.einrichten(BenutzerId, pLimit(40)); } return Nutzerbegrenzer.bekommen.(BenutzerId);}// Umschließen Sie jeden Gmail API-Aufruf mit dem Begrenzer des Benutzersasync function Nachricht abrufen(gmail, userId, messageId) { const Grenze = Begrenzer abrufen(BenutzerId); return limit(() => gmail.users.messages.bekommen.({ userId: ich, id: NachrichtId, Felder: 'id,threadId,payload.headers,snippet' }));}Fehler entschlüsseln: 429 vs. 403
Die Gmail API gibt zwei verschiedene HTTP-Statuscodes für Kontingent- und Zugriffsprobleme zurück: 429 (Zu viele Anfragen) und 403 (Verboten). Innerhalb dieser beiden Codes gibt es vier verschiedene Fehlergründe, jeder mit einer anderen Ursache und einer anderen Auflösung. Das Vermischen dieser Fehler verschwendet Zeit bei der Fehlersuche. Hinweis: Fehler im OAuth-Flow wie ungültiger_grant sind Fehler beim Aktualisieren des Tokens - sie sind vollständig von diesen Laufzeit-Gmail-API-Ratenbeschränkungen getrennt.
| HTTP-Code | Fehlergrund | Ursache | Korrigieren |
|---|---|---|---|
| 429 | RateLimitUeberschritten | Das 1,2 Mio. Quoten-Einheiten/Minute/Projekt-Limit wurde überschritten. Alle authentifizierten Benutzer im Projekt haben gemeinsam die Grenze erreicht. | Exponentielles Backoff + Jitter. Warten und erneut versuchen. Langfristig: Aufteilen auf mehrere GCP-Projekte oder Quotenanforderung erhöhen. |
| 429 | BenutzerRatenlimitÜberschritten | Ein einzelner authentifizierter Benutzer hat 6.000 Quota-Einheiten pro Minute überschritten ODER 50 gleichzeitige Anfragen an sein Postfach überschritten. Die häufigste Produktions-429. | Pro-Benutzer-Warteschlange mit Konkurrenzbegrenzer. Wenden Sie das Semaphore-Muster an (max. 40 gleichzeitig). Fügen Sie exponentielles Backoff für 429-Wiederholungen hinzu. |
| 403 | TageslimitÜberschritten | Das GCP-Projekt hat vor Mitternacht Pacific all seine 80 Millionen täglichen Kontingenteinheiten aufgebraucht. Kann bis zur Zurücksetzung nicht erneut versucht werden. Dies ist ein harter Stopp. | Warte auf den Reset um Mitternacht Pazifikzeit oder beantragen Sie eine Quotensteigerung über die GCP-Konsole. Implementieren Sie tägliches Quotenbudgeting pro Benutzer in Ihrer Anwendung. |
| 403 | Kontingentüberschritten | Ein bestimmter Unterquotenwert wurde überschritten. Kann auch darauf hinweisen, dass das Gmail-Sendelimit (500 E-Mails pro Tag kostenlos, 2.000 für Workspace) für eine bestimmte Absenderadresse erreicht wurde. | Überprüfe welches Kontingent. Für das Sendelimit: Wechseln Sie die Absenderadresse oder warten Sie 24 Stunden. Für andere Unterlimits: Identifizieren Sie die spezifische Metrik im GCP Quotas Dashboard. |
Projektweiter Grenzwert erreicht: 1,2 Mio. Quoten-Einheiten/Min. über alle Nutzer hinweg.
Korrigieren: Exponentieller Backoff + Jitter. Langfristig: mehrere GCP-Projekte oder Erhöhung der Kontingentgrenzen beantragen.
Einzelner Benutzer überschritt 6.000 Einheiten/Minute ODER 50 gleichzeitige Anfragen. Häufigster 429.
Korrigieren: Pro-Benutzer-Warteschlange + Semaphor (max. 40 gleichzeitig). Backoff-Retry hinzufügen.
Das Projekt hat das tägliche Kontingent von 80 Mio. Einheiten verbraucht. Harter Stopp bis Mitternacht Pazifikzeit.
Korrigieren: Warten Sie auf den Reset oder beantragen Sie eine Erhöhung des Kontingents über die GCP-Konsole.
Unter-Kontingent oder Gmail-Sendekontingent (500/Tag kostenlos, 2.000 Workspace) für Sender erreicht.
Korrigieren: Überprüfen Sie das GCP-Dashboard auf spezifische Unterkontingente. Für Senden: Adresse wechseln oder 24 Stunden warten.
ungültiger_grant, Zugriff verweigertund ungültiger_kunde stammen von der OAuth-Token-Austauschschicht und nicht von der Gmail-API-Kontingentdurchsetzung. Sie werden separat in der Google OAuth Fehlerleitfaden. Wenn Sie eine 401 Unauthorized sehen, ist das ebenfalls ein Authentifizierungsproblem - überprüfen Sie Ihre OAuth-App-Überprüfung Status und ob die Der Refresh-Token ist abgelaufen. Produktionsbereite Handhabung: exponentielle Backoff + Jitter
Exponentielles Backoff ist die einzig richtige Antwort auf eine 429-Fehlermeldung von der Gmail API. Ein sofortiges erneutes Versuchen verschlimmert das Problem: Sie häufen mehr Anfragen auf ein bereits gedrosseltes Kontingentfenster. Das Hinzufügen von zufälligem Jitter verhindert das "Thundering Herd"-Problem, bei dem alle Clients in einer Flotte zur exakt gleichen Zeit wiederholen. Nachfolgend finden Sie vollständige, produktionserprobte Implementierungen in Node.js und Python.
Anfängliche Verzögerung
Beginnen Sie mit 1.000 ms beim ersten Wiederholungsversuch. Versuchen Sie es nie sofort nach einer 429 erneut.
Exponentieller Multiplikator
Verdopple die Verzögerung bei jedem Versuch: 1s, 2s, 4s, 8s, 16s. Begrenze auf maximal 32-64 Sekunden.
Zufälliges Jitter
Füge 0-500ms zufälliges Jitter hinzu, um synchronisierte Wiederholungsversuche über konkurrierende Worker hinweg zu verhindern.
// gmail-backoff.js - production-ready exponential backoff + jitter// Handles rateLimitExceeded and userRateLimitExceeded (gmail api rate limits)const sleep = (ms) => new Promise(r => setTimeout(r, ms));async function withGmailBackoff(fn, { maxRetries = 5, initialDelay = 1000, maxDelay = 32000, jitter = 500} = {}) { let delay = initialDelay; for (let attempt = 0; attempt < maxRetries; attempt++) { try { return await fn(); } catch (err) { const code = err?.code || err?.response?.status; const reason = err?.errors?.[0]?.reason || ''; // Only retry on quota errors - not on 403 dailyLimitExceeded const isRetryable = code === 429 || reason === 'rateLimitExceeded' || reason === 'userRateLimitExceeded'; if (!isRetryable || attempt === maxRetries - 1) throw err; const wait = Math.min(delay + Math.random() * jitter, maxDelay); await sleep(wait); delay *= 2; } }}// Usage: on behalf of each authenticated userconst message = await withGmailBackoff(() => gmail.users.messages.get({ userId: 'me', id: messageId }));# gmail_backoff.py – Exponentieller Backoff + Jitter für die Ratenbegrenzungen der Gmail-APIimport asyncio, Zufallfrom googleapiclient.Fehler import HttpFehlerasync def mit_gmail_backoff( fn, max_versuche=5, Anfangsverzögerung=1.0, max_verzögerung=32.0, zucken=0.5): """Umschließe jeden Gmail API-Aufruf mit exponentiellem Backoff + zufälligem Jitter. Behandelt Gmail API-Ratenbegrenzungen: rateLimitExceeded und userRateLimitExceeded. """ Verzögerung = Anfangsverzögerung für Versuch in range(max_retries): versuchen: return fn() Die Funktion „#“ ist ein synchroner Aufruf des Gmail-Clients außer HttpFehler als e: status = e.resp.status Grund = e.Fehlerdetails[0].bekommen.('Grund', '') wenn e.fehlerdetails sonst '' # Wiederholungsversuch bei 429; KEIN Wiederholungsversuch bei dailyLimitExceeded wiederholbar = status == 429 oder Grund in ( 'rateLimitExceeded', 'BenutzerRatenLimitÜberschritten' ) wenn nicht wiederholbar oder Versuch == maximale_wiederholungen - 1: erhöhen warten = min(Verzögerung + Zufall.Uniform(0, Jitter), max_delay) await asyncio.Schlaf(warten) Verzögerung *= 2Strategien, um unter dem Limit zu bleiben
Backoff sorgt für den Notfall. Diese proaktiven Strategien verhindern von vornherein, dass Sie die Quotengrenzen der Gmail-API erreichen. Sie sind nach ihrer Auswirkung auf Ihren Quotenverbrauch geordnet, von der größten bis zur geringsten. Durch die Kombination von zwei oder drei dieser Strategien können Sie Ihre Kosten pro Einheit bei typischen, leseintensiven Workloads um 80% senken.
Warteschlange für authentifizierte Benutzer
Behalten Sie eine separate Anforderungs-Warteschlange pro authentifizierter Benutzer. Mischen Sie Anfragen von verschiedenen Benutzern niemals in einem gemeinsamen Pool. Dies isoliert die Ratenbegrenzungsexposition pro Benutzer und ermöglicht eine faire Warteschlange: Wenn ein Benutzer eine 429 auslöst, wird nur seine Warteschlange pausiert – andere fahren mit voller Geschwindigkeit fort. Verwenden Sie Redis oder eine In-Memory-Warteschlange mit einem Token-Bucket pro Benutzer.
Verwenden Sie history.list anstelle von messages.list für die Synchronisierung
Abfrage Nachrichtenliste Auf einen Timer zu achten ist der häufigste Fehler bei den Nutzungslimiten der Gmail API. Benutzerverlauf Liste nur Kosten 2 Einheiten (im Vergleich zu 5 bei „messages.list“) und gibt nur die Differenz seit Ihrem letzten Synchronisierungszeitpunkt zurück. Bei leseintensiven Anwendungen, die große Postfächer synchronisieren, kann diese Option allein den Quotenverbrauch um 601 TP3T senken. Speichern Sie die historyId mit jeder Antwort Ihres Cursors synchronisieren. Kombinieren Sie dies mit Gmail Push-Benachrichtigungen (Pub/Sub) für eine nahezu Echtzeit-Synchronisierung.
Batch-API-Aufrufe
Die Gmail API unterstützt Batch-Anfragen: Kombinieren Sie bis zu 100 einzelne Anfragen in einem einzigen HTTP-Aufruf. Jede Unteranfrage wird weiterhin mit ihren normalen Einheitskosten berechnet, aber Sie reduzieren die TCP-Overheads und die verbrauchten "Slots" für Ratenbegrenzungen. Dies ist besonders effektiv für Nachrichten.abrufen Operationen, bei denen viele Nachrichten aus einer Synchronisierungs-Delta abgerufen werden müssen. Überprüfen Sie die Gmail Stapelverarbeitung Leitfaden für Implementierungsdetails.
Verwenden Sie partielle Antworten (fields=)
Jede Gmail API-Methode unterstützt die Felder= Parameter, um nur die benötigten Eigenschaften abzufragen. Dies senkt zwar nicht die Kosten pro Anfrage, reduziert jedoch die Datenmenge der Antwort um 60–90 % und verbessert die Latenz. Für eine Nachrichten.abrufen nur zurückgeben id,threadId,payload.headers,snippet, fällt die Nutzlast von über 40 KB auf unter 2 KB. Weniger Netzwerk = schnellere Iteration = mehr Spielraum vor dem Erreichen der täglichen Obergrenze des Gmail API-Kontingents.
Push vs. Poll: Das richtige Synchronisationsmodell
5 Einheiten pro Abfrage + N x 5 Einheiten zum Abrufen jeder neuen Nachricht. Für 100 Benutzer x 30s Intervall = 1 Mio. Einheiten/Stunde nur an Abfrage-Overhead.
2 Einheiten pro Abfrage; es werden nur die Änderungen seit der letzten Synchronisierung zurückgegeben. 60% ist kostengünstiger als das Abfragen von „messages.list“, um dasselbe Ergebnis zu erzielen.
Keine Quotenkosten für die Zustellung. Google sendet eine Benachrichtigung, wenn sich ein Postfach ändert – Sie rufen nur die Delta-Änderungen ab. Benötigt einen öffentlichen Webhook-Endpunkt. Ideal für Nah-Echtzeitanwendungen.
Mandantenfähigkeit und Anforderung einer Quotaerhöhung
Sobald Sie über eine Handvoll verknüpfter Konten hinausgehen, werden die Gmail API-Kontingente zu einem architektonischen Anliegen. Dieser Abschnitt behandelt das Sharding von GCP-Projekten für groß angelegte Bereitstellungen und den schrittweisen Prozess zur Beantragung einer Erhöhung des Gmail API-Kontingents von Google.
GCP-Projekt-Sharding
Das 1,2M-Quota-Einheiten/Min-Limit ist pro GCP-Projekt. Wenn Sie 1.000 authentifizierte Benutzer haben, die alle aktiv synchronisieren, können Sie diese auf zwei GCP-Projekte aufteilen, um Ihre effektive Kapazität auf Projektebene zu verdoppeln. Jedes Projekt benötigt seine eigenen OAuth-Client-Anmeldeinformationen und einen eigenen Einwilligungsbildschirm. Benutzer, die mit Projekt A verknüpft sind, können die Kontingente von Projekt B nicht nutzen. Dies ist besonders nützlich für Szenarien mit hohem E-Mail-Synchronisationsvolumen, bei denen das tägliche Kontingentlimit der Gmail API ein Problem darstellt. Überwachen Sie Ihre Kontingentnutzung in der GCP-Konsole, um zu wissen, wann Sharding benötigt wird.
Kontingenterhöhung anfordern
Google gewährt auf Anfrage Quota-Erhöhungen, aber diese brauchen Zeit (typischerweise 3-5 Werktage für die Erstprüfung, bis zu 2 Wochen für große Erhöhungen). Einreichen über die GCP-Konsole: APIs & Dienste > Gmail API > Kontingente > "Kontingent erhöhen". Google benötigt eine detaillierte Begründung. Wichtige Punkte, die aufgenommen werden müssen: geschätzte tägliche aktive Nutzer, durchschnittliche Anfragen pro Nutzer pro Tag, Aufschlüsselung nach Methode (Nachrichten senden gegen Nachrichtenliste usw.), sowie den Produktionsanwendungsfall. Vage Anfragen werden abgelehnt. Geben Sie konkrete Zahlen aus Ihrer Staging-Telemetrie an.
Tägliches Kontingent überwachen und budgetieren
Implementieren Sie die Quotenbudget-Nachverfolgung pro authentifiziertem Benutzer in Ihrer eigenen Datenschicht. Verfolgen Sie genutzteQuotenEinheiten für jeden Nutzer täglich. Wenn ein Nutzer sich der 70–80 %-Marke seines täglichen Budgets nähert, wechsle für diesen Nutzer für den Rest des Tages vom Active-Sync-Modus in den reinen Push-Modus. Dadurch wird verhindert, dass ein Nutzer mit hohem Datenvolumen einen unverhältnismäßig großen Teil des täglichen Kontingents auf Projektebene aufbraucht. Die Häufigkeit, mit der Sie jedem Benutzer Kontingent zuweisen, ist eine Kundenentscheidung in Bezug auf Ihr Anwendungsdesign.
Was in Ihre Quotenanfrage aufgenommen werden sollte
Aktueller Nutzungsbasis: "Wir verbrauchen derzeit X Millionen Einheiten/Tag bei Y aktiven Nutzern."
Wachstumsprognose "In 6 Monaten erwarten wir Z Nutzer, was ungefähr W Millionen Einheiten/Tag erfordert."
Anwendungsfall "Unser Produkt liest Gmail, um [CRM-Synchronisierung / ATS-Posteingang / E-Mail-Analysen] zu ermöglichen. Benutzer authentifizieren sich individuell über OAuth."
Methodenaufschlüsselung: "Hauptmethoden: messages.list (40%), messages.get (35%), history.list (20%), messages.send (5%)."
Wie Unipile die Gmail-Drosselung im Namen des authentifizierten Benutzers verwaltet
Der Aufbau der gesamten in dieser Anleitung beschriebenen Drosselungsinfrastruktur – warteschlangen pro Benutzer, Semaphoren, exponentielles Backoff, tägliche Kontingentverwaltung, GCP-Projektmanagement – dauert Wochen und erfordert fortlaufende Wartung. Unipile übernimmt dies als unabhängiger technischer Vermittler, damit sich Ihr Team auf die Produktlogik konzentrieren kann und nicht auf Quoten-Regelungen. Der Gmail API-Zugang über Unipile ist nicht mit Google verbunden, wird von Google nicht unterstützt und steht nicht unter der Schirmherrschaft von Google.
Verwalteter exponentieller Backoff mit Jitter
Jeder Gmail API-Aufruf, der gemacht wird im Namen von Jeder authentifizierte Benutzer durchläuft die Backoff-Schicht von Unipile. 429-Fehler sind für Ihren Code transparent: Unipile versucht es automatisch mit vollständigem exponentiellem Backoff und Jitter, und gibt nur den erfolgreichen Abschluss oder einen klaren Fehler nach maximalen Wiederholungsversuchen zurück.
Pro-Benutzer-Warteschlangentrennung
Unipile gewährleistet eine strikte mandantenfähige Trennung. Ein gedrosselter authentifizierter Benutzer beeinträchtigt niemals den Durchsatz eines anderen Benutzers. Jeder verknüpftes Konto hat eine eigene Warteschlange mit individuellen Parallelitätsgrenzen, die eine faire Ressourcenverteilung für Ihre gesamte Benutzerbasis gewährleisten.
Vereinigtes Modell: Gmail + Outlook + IMAP
Dieselbe Drosselungslogik gilt einheitlich für Google Mail, Ausblick (Microsoft 365 und Exchange Online), und IMAP. Ihre Anwendung verwendet eine standardisierte API, unabhängig davon, welchen E-Mail-Anbieter der authentifizierte Benutzer verknüpft hat. Kein anbieterspezifischer Code für Ratenbegrenzungen muss gepflegt werden.
DSGVO-konform, SOC2-konform
Daten, auf die über Unipile zugegriffen wird, sind Geltungsbereich der Sitzung des authentifizierten Benutzers Wer die OAuth-Berechtigung erteilt hat. Kein paralleles Archiv, keine langfristige Speicherung von Postfachdaten über die Sitzungsanforderungen hinaus. DSGVO- und SOC2-Konformität integriert.
Mit Unipile: kein Backoff, keine Semaphoren, keine Kontingentverfolgung// Unipile kümmert sich als unabhängiger technischer Vermittler um alle Gmail API-Ratenbeschränkungenimport UnipileClient from '@unipile/node-sdk';const Kunde = new UnipileClient({ apiKey: process.env.UNIPILE_API_KEY, basisUrl: 'https://api3.unipile.com:13613'});// Liste Nachrichten für das verknüpfte Gmail-Konto eines authentifizierten Benutzers// Drosselung, Wiederholungsversuche und nutzerspezifische Isolierung werden serverseitig von Unipile gehandhabtasync function die_neuesten_E_Mails_abrufen(KontoId) { const Nachrichten = await client.messaging.listMessages({ account_id: accountId, // verknüpftes Konto des authentifizierten Benutzers Grenze: 25 }); return Nachrichten;}// Funktioniert identisch für Gmail-, Outlook- und IMAP-verbundene Konten// Gleicher Code, keine anbieterspezifische RatenbegrenzungGmail API Ratenbegrenzungen – FAQ
Antworten auf die häufigsten Fragen zu Gmail API-Ratenbegrenzungen, Kontingenteinheiten, 429-Fehlern und der Skalierung Ihrer Integration.
Die Gmail API erzwingt Limits über drei Dimensionen gleichzeitig. Auf Projektebene: 1.200.000 Quoten-Einheiten pro Minute gemeinsam für alle Benutzer, und 80.000.000 Quoten-Einheiten pro Tag. Auf Benutzerebene: 6.000 Quoten-Einheiten pro Minute pro Postfach. Es gibt auch ein verstecktes Limit von 50 gleichzeitige Anfragen pro Postfach die eine 429 auslösen können, selbst wenn Sie sich weit unter der Obergrenze der Quoteneinheiten befinden. Jede Methode hat unterschiedliche Einheitenkosten – Nachrichten senden kostet 100 Einheiten, während Nachrichtenliste kostet nur 5.
Implementieren Exponentielles Backoff mit Jitterbeginne bei 1.000 ms beim ersten Wiederholungsversuch, verdopple jeden Versuch, füge 0-500 ms zufälliges Jitter hinzu, begrenze auf 32.000 ms. Wiederhole niemals sofort. Füge einen Concurrency-Begrenzer bereits pro authentifiziertem Benutzer, wobei ausgehende Anfragen pro Postfach auf unter 40 begrenzt werden. Verwenden Sie eine Warteschlange pro Benutzer damit ein gedrosselter Benutzer andere nicht beeinträchtigt. Langfristig, das Abfragen ändern von Nachrichtenliste (5 Einheiten) bis Geschichte.Liste (2 Einheiten) und die Nutzung von Gmail Push-Benachrichtigungen zur vollständigen Eliminierung des Polling in Betracht ziehen.
Die Gmail API Das tägliche Kontingent beträgt 80.000.000 Kontingenteinheiten pro GCP-Projekt, zurückgesetzt um Mitternacht Pazifikzeit. Dieses Limit gibt eine 403 Tageslimit überschritten Fehler – anders als 429-Fehler pro Minute kann dieser Fehler erst beim täglichen Zurücksetzen erneut versucht werden. Um ihn zu erhöhen: GCP Console > APIs & Services > Gmail API > Quotas > Höhere Kontingente anfordern. Geben Sie die aktuelle Nutzung, Wachstumsprognosen und Ihren Anwendungsfall an. Die Genehmigung dauert in der Regel 3-5 Werktage.
Das Gmail Das Versandlimit beträgt 500 E-Mails pro Tag kostenlose Gmail-Konten und 2.000 E-Mails pro Tag für Google Workspace-Konten. Dieses Limit gilt pro Absenderadresse und ist vom API-Kontingent-Budget getrennt. Jede Nachrichten senden Ein Anruf kostet ebenfalls 100 Quota-Einheiten. Bei einem Limit von 6.000 Einheiten pro Minute pro Benutzer kann man also höchstens 60 E-Mails pro Minute senden, bevor man das Gmail API-Limit pro Benutzer erreicht – aber die tägliche Grenze von 500/2.000 wird bei typischen Anwendungsfällen wahrscheinlich zuerst erreicht.
RateLimitUeberschritten bedeutet, dass das gesamte GCP-Projekt 1.200.000 Quota-Einheiten/Minute überschritten hat – alle authentifizierten Benutzer zusammen. BenutzerRatenlimitÜberschritten bedeutet, dass ein einzelner Nutzer mehr als 6.000 Quota-Einheiten pro Minute überschritten hat oder mehr als 50 gleichzeitige Anfragen an ihre Mailbox gesendet haben. In produktiven Multi-Tenant-Anwendungen, BenutzerRatenlimitÜberschritten ist weitaus häufiger, da einzelne Benutzer unabhängig voneinander ihre Limits erreichen können, unabhängig vom Gesamtprojektbudget. Beide geben HTTP 429 zurück und beide reagieren auf exponentielle Backoffs.
Navigieren zu GCP Konsole > APIs & Dienste > Gmail API > Kontingente und klicken Sie auf "Höhere Kontingentanforderung beantragen". Ihre Anfrage muss eine konkrete Begründung enthalten: aktuelle tägliche Nutzungsbasis, voraussichtliches Benutzerwachstum für 6 Monate, Beschreibung, wie sich Benutzer einzeln über OAuth authentifizieren, und eine Aufschlüsselung der API-Methoden nach Anteil. Vage Anfragen werden abgelehnt. Stellen Sie außerdem sicher, dass Ihre App OAuth verifiziert - Unbestätigte Apps sind auf 100 Testbenutzer beschränkt, unabhängig vom Kontingent. Die Überprüfung dauert in der Regel 3-5 Werktage für eine erste Antwort.
Nachrichten senden Kosten 100 Quoteneinheiten pro Aufruf – die teuerste Methode der Gmail API. Mit dem nutzerbezogenen Limit von 6.000 Einheiten/Minute können Sie höchstens 60 E-Mails pro Minute pro authentifiziertem Nutzer senden. Zum Vergleich: Nachrichten.abrufen kostet 5 Einheiten (1.200 Anrufe/Min), Geschichte.Liste kostet 2 Einheiten (3.000 Anrufe/Min), und labels.list kostet 1 Einheit (6.000 Anrufe/Min.). Überlegen Sie für großvolumige Anrufe, ob Ihr Anwendungsfall tatsächlich Anrufe erfordert Nachrichten senden oder ob das Erstellen und versenden von Entwürfen in Stapeln effizienter ist.
Unipile greift nur auf die Daten zu, die von Ihrer Anwendung explizit angefordert werden., Geltungsbereich der Sitzung des authentifizierten Benutzers wer die OAuth-Berechtigung erteilt hat. Es gibt kein paralleles Archiv, keine unabhängige Langzeitspeicherung von Postfachdaten über das hinaus, was zur Bearbeitung der aktuellen API-Anfrage erforderlich ist. Die Daten jedes authentifizierten Benutzers sind isoliert: Unipile agiert als unabhängiger technischer Vermittler ausschließlich im Namen dieses spezifischen Benutzers.
Die Häufigkeit und das Volumen von API-Aufrufen, die im Namen jedes authentifizierten Benutzers erfolgen, sind ein Kundenentscheidung. Unipile verwaltet die Backoff- und Warteschlangen-Infrastruktur, aber Ihre Anwendung bestimmt, wie oft Daten angefordert werden. Unipile zeigt Kontingentfehler transparent an und wendet Wiederholungslogik an, aber die allgemeine Aufrufkadenz - einschließlich der Anzahl gleichzeitiger Benutzersynchronisationen und deren Häufigkeit - bleibt unter Ihrer Kontrolle als Entwickler, der auf Unipile aufbaut.
Nein. Unipile ist nicht mit Google verbunden, von Google unterstützt oder von Google gesponsert. Unipile ist ein unabhängiger technischer Vermittler, der Gmail API-Aufrufe im Auftrag authentifizierter Benutzer durchführt, die individuell OAuth-Zustimmung über ihre eigenen Google-Konten erteilt haben. Gmail ist eine Marke von Google LLC. Alle Gmail API-Kontingente, Ratenlimits und Richtlinien werden von Google definiert und können unabhängig von Unipile geändert werden.
Fragen zu Gmail API-Limits und Unipile-Integration? Unser Team steht Ihnen gerne zur Verfügung.
Der umfassende E-Mail-API-Leitfaden für Entwickler
Gmail-Limits sind ein Teil des Bildes der E-Mail-API. Der Leitfaden zu den Säulen behandelt die Integrationsmuster für Gmail, Outlook und IMAP End-to-End.
DE 
EN 
FR 
ES 
IT 
BR 
NL 
PL 
TR