LinkedIn
Instagram
WhatsApp
Telegram
Gmail
Outlook
Google Agenda
Rejoindre la communauté SlackLimites de l'API Gmail en 2026 : Quotas, Limites de débit, et Comment Gérer
Référence complète des quotas de l'API Gmail couvrant les limites par minute, par utilisateur et quotidiennes, les coûts unitaires par méthode, la gestion des erreurs 429 et un modèle de retrait exponentiel prêt à la production pour les utilisateurs authentifiés.
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; } }}Mir à la session authentifiée de l'utilisateur
Unipile ne maintient pas d'archive parallèle des données de la boîte aux lettres Gmail. Tout accès aux e-mails est dans la portée de la session de l'utilisateur authentifié qui a explicitement accordé le consentement OAuth. Aucune donnée n'est stockée indépendamment de ce qui est requis pour répondre à cette demande spécifique.
Intermédiaire technique indépendant
Unipile agit comme un intermédiaire technique indépendant, effectuant des appels à l'API Gmail pour le compte de chaque utilisateur authentifié individuellement. Unipile n'est ni un partenaire ni un affilié de Google. Aucune information d'identification n'est partagée entre les utilisateurs. Chaque jeton OAuth appartient exclusivement à l'utilisateur qui l'a accordé.
La cadence est une décision côté client
Unipile relaie les limites de débit et les contraintes de quota de l'API Gmail telles que définies par Google. La fréquence et le volume des appels API effectués au nom de chaque utilisateur est un décision côté client. Unipile signale les erreurs de quota et applique une logique de *backoff*, mais la cadence d'appel reste sous le contrôle du développeur.
Limites de l'API Gmail en un coup d'œil
Avant d'écrire la moindre ligne de logique de nouvelle tentative, vous devez avoir une vision claire des trois axes de quotas que Google applique. Le tableau ci-dessous est la référence que vous mettrez en favoris : débit par projet, plafonds par utilisateur et plafond quotidien qui se réinitialise à minuit, heure du Pacifique.
| Limite | Valeur | Dimension | Notes |
|---|---|---|---|
| Limite de débit de l'API Gmail (unités de quota) | 1 200 000 / min | Par projet GCP | Partagé entre tous les utilisateurs du projet |
| Limite de débit par utilisateur pour l'API Gmail | 6 000 / min | Par boîte aux lettres utilisateur | Déclencheur le plus courant pour 429 en production |
| Quota journalier | 80 000 000 par jour | Par projet GCP | Réinitialisations à minuit, heure du Pacifique |
| Quota d'envoi Gmail (Gmail gratuit) | 500 e-mails par jour | Par adresse d'expéditeur | 2 000 / jour pour Google Workspace |
| Requêtes simultanées par boîte aux lettres | 50 | Par boîte aux lettres | Limite cachée - déclenche 429 quel que soit le quota |
| Requêtes par lots par appel | 100 demandes | Par lotPar appel de lot | Utiliser le traitement par lots pour réduire la consommation d'unités de quota |
| Taille maximale du message (pièces jointes) | 25 Mo | Par message | En-têtes inclus et corps encodé |
Source : Documentation de Google Developers, API Gmail - Limites d'utilisation (dernière vérification en mai 2026). Les limites sont susceptibles d'être modifiées ; vérifiez toujours la page des quotas de votre console GCP pour connaître les valeurs actuelles de votre projet.
Les trois dimensions du quota
Les limites d'utilisation de l'API Gmail fonctionnent simultanément sur trois axes indépendants. Une requête peut être bloquée même si deux des trois sont valides. Comprendre la séparation entre les limites par projet, par utilisateur et journalières est la première étape pour écrire du code résilient pour n'importe quel utilisateur authentifié.
Par projet (GCP)
1 200 000 unités/minIl s’agit du logiciel de plafond agrégé sur tous les utilisateurs au sein d'un même projet GCP. Si vous avez 500 utilisateurs authentifiés effectuant simultanément des appels à l'API Gmail, toute leur consommation de quota compte pour ce seau unique. L'atteindre déclenche un Limite de débit dépassée 429. L'équivalent journalier est 80 millions d'unités, réinitialisation à minuit, heure du Pacifique.
Par utilisateur (par boîte aux lettres)
6 000 unités/minCe plafond s'applique indépendamment à chaque utilisateur authentifié. Même si votre projet dispose d'une marge de quota, un seul utilisateur faisant un usage intensif de sa propre boîte aux lettres avec un interogation rapide déclenchera un Dépassement de la limite de débit utilisateur 429. Dans les applications multi-locataires, c'est la limite qui se déclenche le plus souvent : elle est par utilisateur, et non partagée.
Quota journalier
80 000 000 unités/jourLa limite quotidienne est également par projet. Contrairement aux fenêtres par minute qui récupèrent automatiquement après 60 secondes, atteindre la quota journalier signifie qu'il n'y aura plus d'accès à l'API avant minuit, heure du Pacifique. L'erreur est LimiteQuotidienneDépassée. Vous pouvez demander une augmentation de quota via la console GCP - nous traitons cela dans la section multi-locataires.
Important : Les limites du débit de l'API Gmail ci-dessus sont mesurées en "unités de quota", et non en nombre brut de requêtes. messages.envoyer un appel coûte 100 unités, tandis qu'un messages.liste coûte seulement 5. Cela signifie que votre budget de requête pratique varie considérablement en fonction des méthodes que vous appelez. Voir le tableau des coûts unitaires dans la section suivante. Notez également que Vérification de la portée OAuth les erreurs du flux de consentement sont complètement distinctes de ces erreurs de quota d'exécution.
Coût unitaire du quota par méthode
Toutes les appels de l'API Gmail ne sont pas égaux. Google compte l'utilisation des quotas en "unités" abstraites, et chaque méthode a un coût différent. Connaître ces coûts vous permet de calculer votre capacité de requêtes réelle et d'optimiser les points de terminaison que vous appelez. La limite de débit par utilisateur de l'API Gmail de 6 000 unités/min se comporte très différemment en fonction de votre mélange d'appels.
| Méthode | Coût unitaire | Requêtes / min (par utilisateur) | Astuce d'optimisation |
|---|---|---|---|
| messages.envoyer | 100 | 60 envois/min max | Coût le plus élevé - utiliser le brouillon + envoyer uniquement lorsque nécessaire |
| messages.insérer | 25 | 240/min max | Insertion dans la boîte aux lettres - inférieur à l'envoi |
| threads.get | 10 | 600/min max | Préférez threads.get à plusieurs messages.get |
| messages.get | 5 | 1 200 tr/min max | Ajoutez des champs= réponse partielle pour maintenir le coût à 5 |
| messages.liste | 5 | 1 200 tr/min max | Utilisez history.list pour les modèles de synchronisation |
| threads.list | 5 | 1 200 tr/min max | Utilisez la pagination avec maxResults pour réduire le nombre d'appels |
| historique.utilisateurs.liste | 2 | 3 000 tr/min max | Idéal pour la synchronisation incrémentielle – interrogation au moindre coût |
| liste des étiquettes | 1 | 6 000 tr/min max | Cacher le résultat - les étiquettes changent rarement |
| modifier les messages | 5 | 1 200 tr/min max | Utilisez batchModify pour mettre à jour les étiquettes en masse |
| messages.attachments.get | 5 | 1 200 tr/min max | Ne récupérer les pièces jointes que lorsque cela est explicitement nécessaire |
Conseil de pro : Vous pouvez utiliser la champs= paramètre de requête permettant d'obtenir des réponses partielles pour n'importe quelle méthode. Le fait de ne demander que les champs dont votre application a besoin ne réduit pas le coût unitaire brut, mais il diminue considérablement la taille de la charge utile de la réponse et la latence — un compromis qui en vaut la peine lorsque vous approchez des limites de quota de l'API Gmail. Testez vos requêtes de manière interactive à l'aide de la Gmail OAuth Playground avant de déployer en production.
La limite cachée de 50 requêtes simultanées par boîte aux lettres
Il existe une limite que la plupart des tutoriels sur l'API Gmail n'abordent jamais, pourtant c'est la cause d'étranges erreurs 429 dans les applications multithread ou asynchrones : Gmail impose un maximum de 50 requêtes simultanées en cours de traitement par boîte aux lettres. Cette limite est totalement indépendante de votre budget en unités de quota. Même si vous n'avez utilisé que 500 unités de quota sur les 6 000 disponibles, vous pouvez tout de même recevoir un code d'erreur 429 si 51 requêtes sont en cours simultanément sur la boîte aux lettres du même utilisateur authentifié.
Pourquoi cela surprend les développeurs
Frameworks asynchrones comme Node.js Promise.all() ou Python asyncio.gather() rendre la tâche triviale de lancer plus de 100 requêtes simultanées. Lorsque vous traitez une synchronisation de boîte aux lettres et que vous déployez pour récupérer 200 messages simultanément au nom d'un utilisateur authentifié unique, Gmail voit 200 connexions TCP ouvertes pour une seule boîte aux lettres et limite immédiatement. Le tableau de bord des quotas dans GCP montrera de nombreuses unités restantes - le plafond de 50 simultanés n'est pas exposé en tant que métrique de quota.
Quand cela se déclenche
La limite de 50 requêtes simultanées se déclenche lors des opérations de synchronisation en masse de boîtes aux lettres : récupération de fils de discussion volumineux, téléchargement de pièces jointes pour de nombreux messages simultanément, ou pagination à travers de nombreux libellés tout en traitant également les résultats de manière concurrente. Tout code qui lance plus de 50 requêtes en cours sur la même boîte aux lettres atteindra cette limite.
Comment régler ça
Utilisez un limiteur de concurrence (sémaphore) limité par utilisateur authentifié. Dans Node.js, des bibliothèques comme p-limite fonctionne bien. En Python, un asyncio.Semaphore(40) avec une marge de sécurité inférieure à 50, cela évite l'éclatement. Maintenez votre concurrence par utilisateur à 40 ou moins par marge de sécurité.
// p-limit maintient la concurrence par utilisateur sous 40import Pression limite from 'limite-p';// Une instance de limiteur par utilisateur authentifié (indexée par userId)const LimiteursUtilisateur = new Carte();fonction getLimiter(idUtilisateur) { si !limiteursUtilisateur.a)) { Limiteurs d'utilisateur.ensemble(identifiantUtilisateur, Pression limite(40)); } return Limiteurs d'utilisateur.obtenir(userId);}// Encapsuler chaque appel à l'API Gmail avec le limiteur de l'utilisateurasync function récupérerMessage(gmail, idUtilisateur, idMessage) { const limite = getLimiter(userId); return limite(() => gmail.users.messages.obtenir({ userId : moi, id : messageId, champs : 'id,threadId,payload.headers,snippet' }));}Décryptage des erreurs : 429 vs 403
L'API Gmail renvoie deux codes d'état HTTP différents pour les problèmes de quota et d'accès : 429 (Trop de requêtes) et 403 (Interdit). Au sein de ces deux codes, il y a quatre raisons d'erreur distinctes, chacune avec une cause profonde différente et une résolution différente. Les confondre fait perdre du temps de débogage. Remarque : les erreurs de flux OAuth telles que grant_invalide sont erreurs de jeton de rafraîchissement ils sont complètement séparés des limites de débit de l'API Gmail au moment de l'exécution.
| Code HTTP | Raison de l'erreur | Cause | Réparer |
|---|---|---|---|
| 429 | Limite de débit dépassée | Quota de 1,2 million d'unités par minute dépassée au niveau du projet GCP. Tous les utilisateurs authentifiés du projet ont collectivement atteint la limite. | Rétromontée exponentielle + gigue. Attendez et réessayez. À long terme : diviser en plusieurs projets GCP ou demander une augmentation de quota. |
| 429 | Dépassement de la limite de débit utilisateur | Un seul utilisateur authentifié a dépassé 6 000 unités de quota par minute, OU a dépassé 50 requêtes simultanées vers sa boîte aux lettres. La cause la plus fréquente en production pour les erreurs 429. | File d'attente par utilisateur avec limiteur de concurrence. Appliquer le modèle de sémaphore (40 simultanés max). Ajouter une exponentielle du backoff sur les tentatives 429. |
| 403 | LimiteQuotidienneDépassée | Le projet GCP a consommé la totalité des 80 millions d'unités de quota quotidiennes avant minuit, heure du Pacifique. Impossible de réessayer avant la réinitialisation. C'est un arrêt complet. | Attendre la réinitialisation de minuit, heure du Pacifique ou demander une augmentation de quota via la console GCP. Implémentez une budgétisation quotidienne des quotas par utilisateur dans votre application. |
| 403 | quotaDépassée | Un sous-quota spécifique a été dépassé. Peut également indiquer que le quota d'envoi Gmail (500 e-mails/jour gratuit, 2 000 Workspace) a été atteint pour une adresse d'expéditeur spécifique. | Vérifier quel quota. Pour le quota d'envoi : changez l'adresse d'envoi ou attendez 24h. Pour les autres sous-quotas : identifiez la métrique spécifique dans le tableau de bord des quotas GCP. |
Plafond du projet atteint : 1,2 million d'unités de quota/min pour tous les utilisateurs.
Réparer : Backoff exponentiel + jitter. Long terme : plusieurs projets GCP ou demande d'augmentation de quota.
Un utilisateur unique a dépassé 6 000 unités/min OU 50 requêtes simultanées. Erreur 429 la plus courante.
Réparer : File d'attente par utilisateur + sémaphore (max 40 simultanés). Ajouter une nouvelle tentative avec backoff.
Le projet a consommé la totalité des 80 millions d'unités du quota quotidien. Arrêt complet jusqu'à minuit, heure du Pacifique.
Réparer : Attendez la réinitialisation ou demandez une augmentation de quota via la console GCP.
Sous-quotas ou quota d'envoi Gmail (500/jour gratuit, 2 000 Workspace) atteint pour l'expéditeur.
Réparer : Vérifiez le tableau de bord GCP pour des sous-quotas spécifiques. Pour envoyer : changez d'adresse ou attendez 24h.
grant_invalide, accès_refusé, ou encore client_invalide proviennent de la couche d'échange de jetons OAuth, et non du contrôle des quotas de l'API Gmail. Ils sont traités séparément dans Guide des erreurs Google OAuth. Si vous voyez un 401 Non autorisé, il s'agit également d'un problème d'authentification - vérifiez votre Vérification d'application OAuth statut et si le le jeton d'actualisation a expiré. Gestion prête pour la production : backoff exponentiel + jitter
Le réessai exponentiel est la seule réponse correcte à un 429 de l'API Gmail. Retenter immédiatement aggrave le problème : vous ajoutez plus de requêtes à une fenêtre de quota déjà limitée. L'ajout d'un "jitter" aléatoire évite le problème du "thundering herd" où tous les clients d'une flotte retentent exactement au même moment. Ci-dessous, vous trouverez des implémentations complètes et testées en production en Node.js et Python.
Délai initial
Commencez avec 1 000 ms lors de la première nouvelle tentative. Ne retentez jamais immédiatement après un 429.
Multiplicateur exponentiel
Double delai à chaque tentative : 1s, 2s, 4s, 8s, 16s. Plafonné à 32-64 secondes maximum.
Gigue aléatoire
Ajouter un délai aléatoire de 0 à 500 ms pour éviter les nouvelles tentatives synchronisées entre les workers concurrents.
// 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 - délai d'attente exponentiel + variation pour les limites de débit de l'API Gmailimport asynchrone, aléatoirefrom googleapiclient.errors import HttpErreurasynchrone def avec_ralentissement_gmail( Fn, max_tentatives=5, délai_initial=1.0, délai_max=32.0, gigue=0.5): "Enveloppez tout appel à l'API Gmail avec une extinction exponentielle + un jitter aléatoire. Gère les limitations de débit de l'API Gmail : rateLimitExceeded et userRateLimitExceeded. """ délai = délai_initial pour tentative en range(max_retries): essayer: return fn() La fonction # est un appel client Gmail synchrone sauf HttpErreur En tant que e : statut = e.resp.status raison = e.error_details[0].obtenir('raison', '') si détails d'erreur sinon '' # : réessayer pour le code 429 ; NE PAS réessayer pour le code dailyLimitExceeded réessayable = état == 429 ou raison en ( 'limiteDeTauxDépassée', 'Limite d'utilisation dépassée par l'utilisateur' ) sinon réessayable ou tentative == nombre_max_tentatives - 1: soulever attendre = moindre(délai + aléatoire.uniforme(0, gigue), delai_max) await asyncio.Dormir(attendre) retard *= 2Stratégies pour rester dans la limite
Backoff gère les situations d'urgence. Ces stratégies proactives vous évitent dès le départ d'atteindre les limites de quota de l'API Gmail. Elles sont classées par ordre décroissant d'impact sur votre consommation de quota. En combinant deux ou trois d'entre elles, vous pouvez réduire vos coûts unitaires de 80% pour les charges de travail typiques impliquant une forte activité de lecture.
File d'attente par utilisateur authentifié
Maintenir une file de requêtes distincte par utilisateur authentifié. Ne mélangez jamais les requêtes de différents utilisateurs dans un pool partagé. Ceci isole l'exposition aux limites de débit par utilisateur et permet une mise en file d'attente équitable : si un utilisateur déclenche une 429, seule sa file d'attente se met en pause - les autres continuent à pleine vitesse. Utilisez Redis ou une file d'attente en mémoire avec un seau de jetons par utilisateur.
Utilisez history.list au lieu de messages.list pour la synchronisation
Sondage messages.liste sur minuterie est l'erreur la plus courante concernant les limites d'utilisation de l'API Gmail. historique.utilisateurs.liste ne coûte que 2 unités (contre 5 pour messages.list) et ne renvoie que les modifications intervenues depuis votre dernier point de synchronisation. Pour les applications à forte intensité de lecture qui synchronisent des boîtes aux lettres volumineuses, cette option peut à elle seule réduire la consommation de quota de 60%. Enregistrez le identifiantHistorique de chaque réponse comme le curseur. Associez avec les notifications push Gmail (Pub/Sub) pour une synchronisation quasi en temps réel.
Appels API par lots
L'API Gmail prend en charge les requêtes par lots : combinez jusqu'à 100 requêtes individuelles en un seul appel HTTP. Chaque sous-requête coûte toujours son unité normale, mais vous réduisez la surcharge TCP et les "emplacements" de limite de débit consommés. Ceci est particulièrement efficace pour messages.get opérations où vous devez récupérer de nombreux messages d'un delta de synchronisation. Vérifiez Guide de lot Gmail pour les détails de mise en œuvre.
Utiliser des réponses partielles (champs=)
Chaque méthode de l'API Gmail prend en charge champs= paramètre permettant de ne demander que les propriétés dont vous avez besoin. Bien que cela ne réduise pas le coût unitaire de la requête, cela diminue la taille de la réponse de 60 à 90 % et améliore la latence. Pour un messages.get revenir seulement id,threadId,payload.en-têtes,extrait, la charge utile passe de 40 Ko+ à moins de 2 Ko. Moins de réseau = itération plus rapide = plus de marge avant d'atteindre le plafond du quota quotidien de l'API Gmail.
Push contre Poll : le bon modèle de synchronisation
5 unités par sondage + N x 5 unités pour récupérer chaque nouveau message. Pour 100 utilisateurs x intervalle de 30 s = 1 million d'unités/heure juste pour la surcharge de sondage.
2 unités par interrogation ; ne renvoie que les modifications intervenues depuis la dernière synchronisation. 60% est moins coûteux que l'interrogation de messages.list pour obtenir le même résultat.
Aucun coût de quota pour la livraison. Google envoie une notification lorsqu'une boîte aux lettres change – vous ne récupérez que la différence. Nécessite un point de terminaison webhook public. Idéal pour les applications quasi en temps réel.
Mise à l'échelle multi-locataire et demande d'augmentation de quota
Une fois que vous dépassez une poignée de comptes liés, les quotas de l'API Gmail deviennent une préoccupation architecturale. Cette section couvre le partitionnement des projets GCP pour les déploiements à grande échelle et le processus étape par étape pour demander une augmentation du quota de l'API Gmail auprès de Google.
sharding de projet GCP
La limite de 1,2 million d'unités de quota par minute est par projet GCP. Si vous avez 1 000 utilisateurs authentifiés, tous en cours de synchronisation active, vous pouvez les répartir sur deux projets GCP pour doubler votre capacité effective au niveau du projet. Chaque projet a besoin de ses propres identifiants client OAuth et d'un écran de consentement. Les utilisateurs liés au projet A ne peuvent pas utiliser le quota du projet B. Ceci est particulièrement utile pour les scénarios de synchronisation d'e-mails à haut volume où le plafond de quota quotidien de l'API Gmail est une préoccupation. Surveillez votre utilisation de quota dans la console GCP pour savoir quand le sharding est nécessaire.
Demande d'augmentation de quota
Google accorde des augmentations de quota sur demande, mais cela prend du temps (généralement 3 à 5 jours ouvrables pour l'examen initial, jusqu'à 2 semaines pour les augmentations importantes). Soumettez via la console GCP : APIs et services > API Gmail > Quotas > "Demander une augmentation de quota". Google exige une justification détaillée. Éléments clés à inclure : nombre estimé d'utilisateurs actifs par jour, nombre moyen de requêtes par utilisateur par jour, répartition par méthode (messages.envoyer vs messages.liste etc.), et le cas d'utilisation de la production. Les demandes vagues sont refusées. Fournir des nombres concrets provenant de votre télémétrie de staging.
Surveiller et budgétiser le quota quotidien
Implémenter le suivi du budget de quota par utilisateur authentifié dans votre propre couche de données. Suivre unitésCotéesUtilisées pour chaque utilisateur, chaque jour. Lorsqu'un utilisateur approche les 70-80 % de son quota quotidien, basculez de la synchronisation active vers le mode « push uniquement » pour cet utilisateur jusqu'à la fin de la journée. Cela évite qu'un utilisateur très actif n'épuise de manière disproportionnée le quota quotidien alloué au projet. La fréquence à laquelle vous allouez du quota par utilisateur est une décision côté client en termes de conception de votre application.
Ce qu'il faut inclure dans votre demande d'augmentation de quota
Utilisation de base actuelle : "Nous utilisons actuellement X millions d'unités par jour pour Y utilisateurs actifs."
Projection de croissance : "Dans 6 mois, nous prévoyons Z utilisateurs, ce qui nécessitera environ W million d'unités/jour."
Cas d'utilisation : "Notre produit lit Gmail pour alimenter [synchronisation CRM / boîte de réception ATS / analyse d'e-mails]. Les utilisateurs s'authentifient individuellement via OAuth."
Décomposition de la méthode : " Méthodes principales : messages.list (40%), messages.get (35%), history.list (20%), messages.send (5%). "
Comment Unipile gère la limitation de Gmail pour le compte de l'utilisateur authentifié
La mise en place de toute l'infrastructure de limitation décrite dans ce guide – files d'attente par utilisateur, sémaphores, exponentielle de décrémentation, budgétisation des quotas quotidiens, gestion des projets GCP – prend des semaines et nécessite une maintenance continue. Unipile gère tout cela en tant qu'intermédiaire technique indépendant, afin que votre équipe se concentre sur la logique du produit, pas sur les plombages de quotas. L'accès à l'API Gmail via Unipile n'est pas affilié, approuvé ou sponsorisé par Google.
Backoff exponentiel géré avec gigue
Chaque appel à l'API Gmail effectué au nom de chaque utilisateur authentifié passe par la couche de backoff d'Unipile. Les erreurs 429 sont transparentes pour votre code : Unipile retente automatiquement avec une stratégie de backoff exponentiel complète et du jitter, n'affichant que le succès final ou une erreur nette après les nouvelles tentatives maximales.
Isolement de file d'attente par utilisateur
Unipile maintient une isolation stricte par utilisateur. Un utilisateur authentifié limité en débit n'impacte jamais le débit d'un autre utilisateur. Chaque compte associé possède sa propre file d'attente avec des limites de concurrence individuelles, garantissant une allocation équitable des ressources pour l'ensemble de votre base d'utilisateurs.
Modèle unifié : Gmail + Outlook + IMAP
La même logique de limitation s'applique uniformément à travers Gmail, Outlook (Microsoft 365 et Exchange Online), et IMAP. Votre application utilise une API standardisée, quel que soit le fournisseur de messagerie lié par l'utilisateur authentifié. Pas de code spécifique au fournisseur pour les limites de débit à maintenir.
Conforme au RGPD, aligné sur SOC2
Les données accessibles via Unipile sont dans la portée de la session de l'utilisateur authentifié Qui a accordé le consentement OAuth. Pas d'archive parallèle, pas de stockage à long terme des données de boîte aux lettres au-delà des exigences de la session. Conformité RGPD et SOC2 intégrée.
// Avec Unipile : pas de backoff, pas de sémaphores, pas de suivi des quotasUnipile gère toutes les limites de taux de l'API Gmail en tant qu'intermédiaire technique indépendantimport UnipileClient from '@unipile/node-sdk';const client = new UnipileClient({ apiKey : process.env.UNIPILE_API_KEY, adresseBase: 'https://api3.unipile.com:13613'});// Lister les messages d'un compte Gmail lié à un utilisateur authentifiéLimitation, retrait et isolement par utilisateur gérés côté serveur par Unipileasync function getRecentEmails(accountId) { const messages = await client.messaging.listerMessages({ account_id: account_id, // compte lié de l'utilisateur authentifié limite : 25 }); return messages;}// Fonctionne de la même manière pour les comptes Gmail, Outlook et IMAP connectés// Même code, aucune gestion spécifique de limite de débit du fournisseurLimites de débit de l'API Gmail - FAQ
Réponses aux questions les plus fréquentes sur les limites de débit de l'API Gmail, les unités de quota, les erreurs 429 et la mise à l'échelle de votre intégration.
L'API Gmail applique des limites sur trois dimensions simultanément. Au niveau du projet : 1 200 000 unités de quota par minute partagé par tous les utilisateurs, et 80 000 000 unités de quota par jour. Au niveau de l'utilisateur : 6 000 unités de quota par minute par boîte aux lettres. Il y a aussi une limite cachée de 50 requêtes simultanées par boîte aux lettres qui peuvent déclencher un 429 même lorsque vous êtes bien en deçà du plafond des unités de quota. Chaque méthode a un coût unitaire différent - messages.envoyer coûte 100 unités tandis que messages.liste coûte seulement 5.
Implémenter attente exponentielle avec gigue: commencez à 1 000 ms lors de la première nouvelle tentative, doublez chaque tentative, ajoutez un décalage aléatoire de 0 à 500 ms, plafonnez à 32 000 ms. Ne retentez jamais immédiatement. Ajoutez un limiteur de concurrence limité par utilisateur authentifié, en maintenant les requêtes en cours en dessous de 40 par boîte aux lettres. Utiliser un file d'attente par utilisateur afin qu'un utilisateur limité en débit n'en impacte pas les autres. À plus long terme, passer le sondage de messages.liste (5 unités) vers histoire.liste (2 unités) et envisagez les notifications push de Gmail pour éliminer complètement le sondage.
L'API Gmail le quota quotidien est de 80 000 000 unités de quota par projet GCP, réinitialisant à minuit, heure du Pacifique. Cette limite renvoie un 403Limite quotidienne dépassée Erreur – contrairement aux erreurs 429 par minute, celle-ci ne peut pas être retentée avant la réinitialisation quotidienne. Pour l'augmenter : Console GCP > API et services > Gmail API > Quotas > Demander une quota plus élevée. Incluez l'utilisation actuelle, les projections de croissance et votre cas d'utilisation. L'approbation prend généralement 3 à 5 jours ouvrables.
Le Gmail la limite d'envoi est de 500 e-mails par jour pour des comptes Gmail gratuits et 2 000 courriels par jour pour les comptes Google Workspace. Cette limite est par adresse d'expéditeur et est distincte du budget d'unités de quota de l'API. Chaque messages.envoyer un appel coûte également 100 unités de quota, donc avec une limite de 6 000 unités/minute par utilisateur, vous pouvez envoyer au maximum 60 e-mails par minute avant d'atteindre la limite de débit de l'API Gmail par utilisateur, mais le plafond quotidien de 500/2 000 sera probablement atteint en premier dans les cas d'utilisation typiques.
Limite de débit dépassée signifie que l'ensemble du projet GCP a dépassé 1 200 000 unités de quota par minute - tous les utilisateurs authentifiés ensemble. Dépassement de la limite de débit utilisateur signifie qu'un utilisateur unique a dépassé 6 000 unités de quota/min ou envoyé plus de 50 requêtes simultanées à leur boîte aux lettres. Dans les applications multi-locataires en production, Dépassement de la limite de débit utilisateur est beaucoup plus courant car les utilisateurs individuels peuvent indépendamment atteindre leurs limites, quelle que soit la marge de manœuvre globale du projet. Les deux renvoient un HTTP 429 et les deux répondent à une déconnexion exponentielle.
Naviguer vers Console GCP > API et services > API Gmail > Quotas et cliquez sur " Demander un quota plus élevé ". Votre demande doit inclure une justification concrète : votre utilisation quotidienne actuelle de base, une projection de croissance des utilisateurs sur 6 mois, une description de la manière dont les utilisateurs s'authentifient individuellement via OAuth, et une répartition des méthodes d'API par proportion. Les demandes vagues sont refusées. Assurez-vous également que votre application est OAuth vérifié - les applications non vérifiées sont limitées à 100 utilisateurs de test, quelle que soit la quotité. L'examen prend généralement 3 à 5 jours ouvrables pour une première réponse.
messages.envoyer coûts 100 unités de quota par appel - la méthode la plus coûteuse de l'API Gmail. Avec une limite par utilisateur de 6 000 unités/minute, vous pouvez envoyer au maximum 60 e-mails par minute par utilisateur authentifié. À titre de comparaison : messages.get coûte 5 unités (1 200 appels/min), histoire.liste coûte 2 unités (3 000 appels/min), et liste des étiquettes coûte 1 unité (6 000 appels/min). Pour une diffusion à grand volume, déterminez si votre cas d'utilisation nécessite réellement d'appeler messages.envoyer ou si la création de brouillons et l'envoi par lots sont plus efficaces.
Unipile n'accède qu'aux données explicitement demandées par votre application, dans la portée de la session de l'utilisateur authentifié qui a accordé le consentement OAuth. Il n'y a pas d'archive parallèle, pas de stockage indépendant à long terme des données de la boîte aux lettres au-delà de ce qui est nécessaire pour répondre à la requête API actuelle. Les données de chaque utilisateur authentifié sont isolées : Unipile agit en tant qu'intermédiaire technique indépendant au nom de cet utilisateur spécifique uniquement.
La fréquence et le volume des appels API effectués pour chaque utilisateur authentifié sont un décision côté client. Unipile gère l'infrastructure de backoff et de mise en file d'attente, mais votre application détermine la fréquence à laquelle solliciter les données. Unipile affiche les erreurs de quota de manière transparente et applique une logique de relance, mais la cadence globale d'appel — y compris le nombre d'utilisateurs synchronisés simultanément et leur fréquence — reste sous votre contrôle en tant que développeur construisant sur Unipile.
Non. Unipile n'est n'est ni affilié à Google, ni approuvé par Google, ni parrainé par Google. Unipile est un intermédiaire technique indépendant qui effectue des appels à l'API Gmail au nom d'utilisateurs authentifiés qui ont accordé individuellement leur consentement OAuth via leurs propres comptes Google. Gmail est une marque commerciale de Google LLC. Tous les quotas, limites de débit et politiques de l'API Gmail sont définis par Google et sont susceptibles de changer indépendamment d'Unipile.
Des questions sur les limites de l'API Gmail et l'intégration Unipile ? Notre équipe est là pour vous aider.
Le guide complet de l'API e-mail pour les développeurs
Les limites de Gmail ne sont qu'un élément du tableau de bord des API d'e-mail. Le guide des piliers couvre l'intégration de Gmail, Outlook et IMAP de bout en bout.
FR 
EN 
ES 
DE 
IT 
BR 
NL 
PL 
TR