Limites de débit des API e-mail : comparatif

Références des commandes : nylas email list, nylas email send, nylas email search.

Que sont les limites de débit de l'API Gmail ?

Les limites de débit des API e-mail côté Gmail se mesurent en unités de quota, pas en nombre brut de requêtes. Chaque méthode de l'API Gmail coûte un nombre d'unités différent, et chaque utilisateur dispose de 250 unités par seconde par défaut. Un appel messages.list coûte 5 unités, un messages.get coûte 5 unités, et un messages.send coûte 100 unités. Vous pouvez donc envoyer au maximum 2 messages par seconde et par utilisateur, mais lister 50 pages par seconde.

Selon la documentation des quotas de l'API Gmail de Google, la limite par utilisateur a été mise à jour le 1er mai 2026 à 250 unités/utilisateur/seconde (auparavant, seuls les quotas journaliers étaient suivis). La limite journalière par projet est de 1 milliard d'unités de quota. Dépasser l'une ou l'autre déclenche une réponse HTTP 429 avec un en-tête Retry-After.

Avec ce système d'unités de quota, une boucle de synchronisation naïve qui appelle messages.list puis messages.get sur chaque résultat consomme 10 unités par message. Synchroniser 1 000 messages coûte 10 000 unités au total, qu'un seul utilisateur peut épuiser en 40 secondes. Les endpoints batch réduisent les allers-retours mais ne changent pas le coût unitaire par message. Le CLI regroupe ces appels en interne et respecte les en-têtes Retry-After : un appel nylas email list --limit 1000 gère la pagination et le throttling sans aucun code supplémentaire.

# List up to 200 Gmail messages — the CLI handles pagination and rate limits
nylas email list --limit 200 --json

Quelles sont les limites de débit email de Microsoft Graph ?

Microsoft Graph applique un throttling de 10 000 requêtes par 10 minutes, par application et par boîte. Cela représente environ 16 requêtes par seconde et par boîte. Lorsque vous dépassez la limite, Graph renvoie HTTP 429 avec un en-tête Retry-After indiquant le nombre de secondes à attendre. Contrairement à Gmail, Graph n'utilise pas de système de coût en unités ; chaque requête compte pour 1, quelle que soit la complexité de l'endpoint.

Selon la documentation du throttling de l'API Graph de Microsoft, la limite de 10 000/10 min s'applique aux endpoints mail, calendrier et contacts d'Outlook. Les limites à l'échelle du tenant sont plus élevées (non publiées, selon le service). Les requêtes groupées via l'endpoint $batch comptent comme 1 requête pour le throttling mais sont limitées à 20 opérations par lot. Le plafond pratique pour la synchronisation mail est d'environ 3 200 messages par 10 minutes si chaque message nécessite un GET séparé.

Graph impose aussi une limite d'envoi de 10 000 destinataires par jour pour les comptes professionnels Microsoft 365, et de 300 messages par jour pour les comptes grand public Outlook.com. C'est le nombre de destinataires qui compte, pas le nombre de messages. Un seul message adressé à 50 destinataires compte pour 50 dans la limite journalière.

Le CLI masque ces limites derrière une seule commande. Exécuter nylas email send sur une boîte Outlook gère automatiquement les réponses 429 et réessaie avec le délai indiqué dans l'en-tête Retry-After.

# Send an email through Outlook — retries on 429 are handled by the CLI
nylas email send --to "recipient@example.com" --subject "Quarterly report" --body "Attached."

Comment les limites de débit se comparent-elles entre fournisseurs ?

L'application des limites de débit varie fortement entre les 5 grands fournisseurs de messagerie. Gmail utilise des unités de quota avec un coût par méthode. Microsoft Graph compte les requêtes de manière uniforme. Yahoo et iCloud appliquent des limites de connexions non documentées au niveau IMAP. Exchange EWS limite les requêtes simultanées. Le tableau ci-dessous présente les chiffres qui comptent le plus pour les workflows email automatisés : requêtes par seconde, messages par jour et taille maximale des pièces jointes.

La colonne « lectures/s effectives » reflète le débit réaliste d'un schéma de synchronisation list + get, pas le maximum théorique annoncé dans la documentation du fournisseur. Le système d'unités de Gmail en fait le plus permissif pour les charges de lecture intensive. Le modèle de comptage uniforme de Graph est plus simple mais plus restrictif pour la synchronisation en masse. Yahoo et iCloud ne publient pas de chiffres exacts ; les estimations ci-dessus proviennent de tests empiriques menés avec le CLI sur des comptes d'âges variés.

Quels codes d'erreur SMTP signalent une limite de débit ?

Les erreurs de limite de débit SMTP se répartissent en deux catégories : les codes de statut HTTP renvoyés par les API REST et les codes de statut SMTP étendus renvoyés par les serveurs mail. La réponse HTTP 429 « Too Many Requests » est le signal standard de l'API Gmail et de Microsoft Graph. Les serveurs SMTP utilisent la famille de codes étendus 4.7.x. Savoir quel code vous avez sous les yeux détermine si vous devez réessayer immédiatement ou attendre des heures.

La distinction entre les codes étendus 4xx et 5xx compte. Un 4.7.28 de Gmail est temporaire et se résout de lui-même. Un 5.7.3 d'Exchange signifie que vous avez atteint un plafond journalier strict. Selon la documentation des limites d'envoi Google Workspace, les comptes Gmail gratuits sont plafonnés à 500 messages par jour, contre 2 000 pour les comptes Google Workspace. Le CLI analyse ces codes d'erreur et ajuste son comportement de retry en conséquence.

Comment réessayer après avoir atteint une limite de débit ?

Le backoff exponentiel avec jitter est la stratégie de retry standard face aux limites de débit des API e-mail. Le schéma double le temps d'attente après chaque tentative échouée (1 s, 2 s, 4 s, 8 s) et ajoute un jitter aléatoire de 0 à 1 seconde pour éviter les effets de « thundering herd » quand plusieurs clients atteignent la même limite simultanément. Sans jitter, les retries synchronisés de workers parallèles s'accumulent et prolongent la fenêtre de throttling.

Selon la documentation de gestion des erreurs d'API de Google, le nombre maximal de retries recommandé est de 5 tentatives, avec un plafond de 32 secondes sur l'intervalle de backoff. La documentation Graph de Microsoft recommande de respecter exactement la valeur de l'en-tête Retry-After plutôt que de calculer votre propre délai. En pratique, la valeur Retry-After de Gmail est généralement de 1 à 60 secondes, tandis que Graph renvoie 5 à 300 secondes selon la sévérité du throttling.

Si vous appelez directement l'API Gmail ou Graph, vous devez implémenter cette boucle vous-même. Le snippet Python ci-dessous montre une implémentation minimale avec jitter. Chaque retry double le délai de base et ajoute jusqu'à 1 seconde de jitter aléatoire. Après 5 échecs, la fonction lève une exception au lieu de boucler indéfiniment.

import time, random, requests

def call_with_backoff(url, headers, max_retries=5):
    delay = 1
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)
        if resp.status_code != 429:
            return resp
        retry_after = int(resp.headers.get("Retry-After", delay))
        jitter = random.uniform(0, 1)
        wait = retry_after + jitter
        print(f"Rate limited. Retry {attempt + 1}/{max_retries} in {wait:.1f}s")
        time.sleep(wait)
        delay = min(delay * 2, 32)
    raise Exception("Max retries exceeded")

Comment le CLI gère-t-il les limites de débit en interne ?

Nylas CLI gère les limites de débit au niveau de la plateforme, vous n'écrivez donc aucune logique de retry vous-même. Quand l'API Nylas sous-jacente reçoit un 429 de Gmail, de Graph ou de tout autre fournisseur connecté, elle réessaie automatiquement avec un backoff exponentiel. Le CLI hérite de ce comportement. Une seule commande nylas email list --limit 500 peut déclencher des dizaines d'appels API paginés en arrière-plan, et chacun respecte les signaux de throttling du fournisseur sans vous remonter d'erreurs.

La plateforme traite plus de 1,2 milliard d'appels API par mois entre Gmail, Outlook, Exchange, Yahoo, iCloud et les fournisseurs IMAP. À ce volume, la logique de retry a été éprouvée contre chaque schéma de limite du tableau ci-dessus. Le comportement côté fournisseur décrit ici repose sur la documentation des fournisseurs et sur nos tests avec Gmail et Outlook ; vérifiez localement avant de déployer des hypothèses spécifiques à Yahoo, iCloud ou EWS.

Pour voir la réponse API brute, y compris les en-têtes de limite de débit, ajoutez --json à n'importe quelle commande. La sortie JSON inclut des champs de métadonnées qui exposent les en-têtes de réponse du fournisseur. C'est utile pour déboguer des scripts qui enchaînent plusieurs commandes CLI, car vous pouvez vérifier si un 429 a été rencontré et combien de temps le retry a attendu.

# Fetch 500 messages with full JSON output including response metadata
nylas email list --limit 500 --json | jq '.[0:3]'

Pour les opérations en masse comme la synchronisation d'une boîte entière ou l'envoi d'une campagne de 2 000 messages, le CLI met les requêtes en file en interne et reste dans les limites du fournisseur. Une synchronisation complète d'une boîte Gmail de 10 000 messages prend environ 3 minutes au rythme soutenu que le quota autorise, contre environ 40 secondes si vous pouviez ignorer totalement les limites.

Quelles sont les limites des opérations batch par fournisseur ?

Les opérations batch regroupent plusieurs appels API dans une seule requête HTTP, ce qui réduit les allers-retours et contourne parfois les throttles par requête. Gmail accepte des lots de 100 appels maximum, tandis que Microsoft Graph plafonne les lots à 20 opérations. Exchange EWS n'a pas d'endpoint batch formel mais permet des opérations groupées via FindItem avec pagination.

Selon la documentation des requêtes batch de Google, chaque opération individuelle d'un lot Gmail coûte toujours l'intégralité de ses unités de quota. Un lot de 100 appels messages.get coûte 500 unités, autant que 100 appels individuels. Le gain porte sur la latence, pas sur le quota. L'endpoint $batch de Microsoft est différent : le lot lui-même compte comme une seule requête pour le throttle de 10 000/10 min, mais chaque opération interne s'exécute indépendamment et peut échouer individuellement.

Le CLI utilise le batching là où le fournisseur le permet. Pour Gmail, il regroupe les appels messages.get par lots de 100 pour réduire la latence pendant la pagination. Pour Graph, il empile jusqu'à 20 opérations par requête $batch pour maximiser l'avantage côté throttling. Rien à configurer : tout se passe automatiquement derrière nylas email list.

Comment surveiller votre consommation de quota ?

Gmail expose la consommation de quota dans la console Google Cloud sous APIs & Services > Gmail API > Quotas, où vous voyez la consommation d'unités en temps réel, ventilée par méthode. Microsoft Graph fournit les données d'usage dans le portail Azure sous App Registrations > votre app > Performance. Les deux tableaux de bord se rafraîchissent toutes les 5 minutes et affichent 30 jours d'historique, de quoi repérer des motifs récurrents dans les événements de throttling.

Pour les workflows en CLI, ajoutez --json à n'importe quelle commande et passez la sortie dans jq pour compter les résultats et estimer le volume d'appels API. La commande ci-dessous liste 100 messages, les compte et calcule approximativement les unités de quota Gmail consommées. À 5 unités par page messages.list (100 résultats par page) plus 5 unités par messages.get pour chaque message, 100 messages coûtent environ 505 unités de quota.

# Count messages returned and estimate Gmail quota cost
COUNT=$(nylas email list --limit 100 --json | jq 'length')
echo "$COUNT messages fetched"
echo "Estimated quota cost: $((5 + COUNT * 5)) units"

Si vous exécutez des scripts de synchronisation périodiques, journalisez le décompte et l'horodatage après chaque exécution. Un cron qui synchronise toutes les 5 minutes et récupère 200 messages par exécution consomme environ 1 005 unités par cycle, soit à peu près 289 440 unités par jour. C'est très en dessous de la limite journalière de 1 milliard d'unités par projet, mais à surveiller si vous passez à l'échelle de milliers d'utilisateurs.

Étapes suivantes

• Parcourez la référence complète des commandes pour voir toutes les commandes email, calendrier et contacts
• Pagination et synchronisation de l'API Gmail expliquées pour une plongée dans nextPageToken et historyId
• Envoyer un e-mail depuis le terminal pour démarrer rapidement avec nylas email send
• La meilleure infrastructure email pour les agents IA pour comparer les plateformes API pour les workflows email automatisés