Pagination et sync de l'API Gmail expliquées

Comment fonctionnent nextPageToken et maxResults dans l'API Gmail ?

Le paramètre maxResults de l'API Gmail contrôle le nombre d'identifiants de messages que users.messages.list renvoie par page, jusqu'à un maximum de 500. Lorsqu'il existe d'autres messages correspondants, la réponse inclut nextPageToken. Renvoyez ce token comme pageToken dans la requête suivante, jusqu'à ce que la réponse ne contienne plus de token.

Pour la requête de recherche courante gmail api nextPageToken maxResults, la règle clé est que maxResults définit uniquement la taille de page, pas la limite totale de résultats. Une boîte mail contenant 10 000 messages correspondants exige toujours des requêtes répétées, la persistance des tokens, la gestion des retries et un second appel messages.get pour chaque corps de message.

Comment fonctionne la pagination de l'API Gmail

La pagination de l'API Gmail répartit les grands ensembles de résultats sur plusieurs réponses HTTP, chacune contenant un nextPageToken que l'appelant doit renvoyer pour récupérer le lot suivant. L'endpoint messages.list renvoie au maximum 500 résultats par requête : une boîte de réception de 10 000 messages exige donc au moins 20 appels API séquentiels pour être parcourue entièrement.

Selon la documentation messages.list de l'API Gmail, chaque appel coûte 5 unités de quota, et la taille de page par défaut est de 100 (configurable jusqu'à 500 avec maxResults). Chaque requête exige un token d'accès OAuth2 valide. La boucle ci-dessous illustre ce schéma en Python — elle appelle messages.list de manière répétée, collecte les identifiants de messages et s'arrête quand nextPageToken est absent :

from googleapiclient.discovery import build

service = build("gmail", "v1", credentials=creds)

all_messages = []
page_token = None

while True:
    response = service.users().messages().list(
        userId="me",
        maxResults=500,
        pageToken=page_token,
    ).execute()

    all_messages.extend(response.get("messages", []))
    page_token = response.get("nextPageToken")

    if not page_token:
        break

print(f"Fetched {len(all_messages)} message IDs")

Cela fait 18 lignes rien que pour collecter des identifiants de messages. Il faut encore appeler messages.get sur chacun d'eux pour récupérer les sujets, les expéditeurs et les corps — chaque appel coûtant 20 unités de quota supplémentaires selon la grille de quotas Gmail actuelle.

Comment fonctionne la synchronisation incrémentale Gmail

La synchronisation incrémentale Gmail suit les changements de la boîte mail via un historyId strictement croissant, afin de ne récupérer que ce qui a changé depuis votre dernière synchronisation. Re-paginer entièrement une boîte de 10 000 messages coûte au moins 100 unités de quota rien qu'en appels messages.list ; l'endpoint history.list existe pour éviter ce surcoût en ne renvoyant que les messages nouveaux, supprimés ou ré-étiquetés.

Vous stockez le historyId de votre dernière synchronisation. Au passage suivant, vous appelez history.list avec startHistoryId pour n'obtenir que les changements survenus depuis. Le guide de synchronisation Gmail recommande cette approche comme méthode principale pour maintenir une copie locale à jour. Le paramètre historyTypes permet de filtrer par type de changement : messageAdded, messageDeleted, labelAdded et labelRemoved. Chaque appel history.list coûte 2 unités de quota — 60 % moins cher qu'un appel messages.list à 5 unités. La fonction Python ci-dessous boucle sur les enregistrements d'historique paginés, collecte les changements et renvoie le dernier historyId pour votre prochaine synchronisation :

def get_changes_since(service, start_history_id):
    """Fetch all mailbox changes since the given historyId."""
    changes = []
    page_token = None

    while True:
        response = service.users().history().list(
            userId="me",
            startHistoryId=start_history_id,
            historyTypes=["messageAdded", "messageDeleted"],
            pageToken=page_token,
        ).execute()

        changes.extend(response.get("history", []))
        page_token = response.get("nextPageToken")

        if not page_token:
            break

    new_history_id = response.get("historyId")
    return changes, new_history_id

Il y a un piège : les history IDs expirent après environ 30 jours. Si votre historyId stocké est trop ancien, history.list renvoie un 404 Not Found (parfois un 410 Gone), et vous devez retomber sur une synchronisation complète. Votre code doit gérer les deux chemins.

Les problèmes quand on fait tout soi-même

Construire un client de synchronisation Gmail de qualité production implique de gérer le cycle de vie des tokens OAuth2, le repli en cas d'historique expiré, la limitation de débit et les échecs partiels — le tout dans du code que vous maintenez vous-même. Ce qui commence comme une boucle de pagination de 20 lignes atteint 80 à 120 lignes une fois ajoutés les callbacks de rafraîchissement de token, le backoff exponentiel pour les réponses 429 et les deux chemins de code pour la synchro delta vs complète. Les cas limites s'accumulent :

• Gestion des tokens OAuth2 — les tokens d'accès Gmail expirent toutes les 3 600 secondes. Votre boucle de synchronisation doit détecter les tokens expirés, les rafraîchir à l'aide du refresh token et rejouer la requête échouée. Cela suppose un callback de rafraîchissement, de la gestion d'erreurs et une logique de retry.
• Repli en cas de historyId expiré — quand history.list renvoie un 404, vous devez abandonner la synchro delta et lancer une synchronisation complète par pagination à la place. Deux chemins de code, qui doivent tous deux fonctionner correctement.
• Limitation de débit — les nouveaux projets de l'API Gmail disposent de 6 000 unités de quota par minute, par utilisateur et par projet. Un appel messages.list coûte 5 unités, un messages.get 20 unités et un history.list 2 unités. Si vous synchronisez une grande boîte mail, il vous faut un throttling côté client et un backoff exponentiel sur les 429 Too Many Requests.
• Échecs de page partiels — une erreur réseau en pleine pagination vous laisse avec la moitié des résultats. Rejouez-vous depuis le début ou depuis le dernier page token ? Vous devez suivre l'état.
• Surcoût de mise en place de l'API Gmail — avant d'écrire la moindre ligne de code appelant l'API Gmail, il vous faut un projet Google Cloud, un écran de consentement OAuth, un client ID et un secret, et une URI de redirection configurée dans console.cloud.google.com. Soit 15 à 20 minutes à cliquer dans des formulaires web.

Une boucle de synchronisation fiable couvrant ces cinq points représente 80 à 120 lignes de Python avant même d'ajouter la journalisation, la persistance ou le support multi-comptes.

Guides associés : pagination d'API et workflows e-mail

La pagination Gmail côtoie généralement des travaux d'intégration adjacents : synchronisation d'événements Calendar, listing de boîte de réception indépendant du fournisseur, livraison de webhooks, planification de quotas API et accès e-mail sûr pour les agents. Utilisez cette carte quand vous avez besoin d'un parcours d'implémentation plus précis.

Lister les e-mails Gmail avec une seule commande

Nylas CLI remplace toute la pile pagination-et-synchronisation par une seule commande de terminal qui gère en interne le rafraîchissement des tokens OAuth2, la limitation de débit et la récupération multi-pages. Là où l'approche API Gmail exige 80 à 120 lignes de Python et 15 à 20 minutes de configuration dans Google Cloud, le CLI ramène cela à une ligne et une installation de 2 minutes.

Les trois commandes suivantes montrent des schémas courants : lister les messages récents, filtrer par sujet et filtrer par expéditeur. Chacune exécute un seul appel API sous le capot pendant que le CLI gère la pagination des réponses du fournisseur :

# List the 50 most recent emails
nylas email list --limit 50 --json

# Filter by subject
nylas email search "invoice" --json

# Filter by sender
nylas email list --from "boss@company.com" --json

Le CLI pagine l'API Gmail en coulisses, rafraîchit automatiquement les tokens OAuth2 expirés et renvoie les résultats en JSON. Aucun projet d'API Gmail à enregistrer, pas d'écran de consentement, pas d'URI de redirection. Nouveau sur le CLI ? Le guide de démarrage couvre l'installation et la première authentification.

Rechercher et filtrer

Nylas CLI prend en charge la recherche plein texte et des filtres par champ qui correspondent au même paramètre q de Gmail utilisé par messages.list, mais sans la boucle de pagination ni la plomberie OAuth2. L'API de Gmail exige au moins 3 appels API séquentiels pour rechercher, paginer et récupérer les corps de messages — le CLI condense tout cela en une seule commande.

Les trois exemples ci-dessous couvrent les schémas de recherche les plus courants : recherche par mot-clé, filtrage des non-lus et filtrage par plage de dates. Les filtres de date se trouvent sur nylas email search via --after et --before, qui prennent des dates YYYY-MM-DD et acceptent "*" comme requête attrape-tout. Chaque exemple renvoie le JSON complet des messages, sujets, expéditeurs et corps inclus :

# Full-text search
nylas email search "quarterly report" --json

# Unread emails only
nylas email list --unread --json

# Emails received in the last 7 days
nylas email search "*" --after 2026-06-02 --json

L'équivalent API Gmail impose de construire la chaîne de requête, de la passer à messages.list, de paginer les résultats avec nextPageToken et d'appeler messages.get sur chacun des identifiants renvoyés pour obtenir les sujets et les corps. Soit 4 étapes et au moins 10 unités de quota par page.

Lire le contenu des messages, pas seulement les identifiants

L'endpoint messages.list de l'API Gmail ne renvoie que des identifiants de messages — jamais les sujets, les expéditeurs ou les corps. Pour lire le contenu réel, vous appelez messages.get sur chaque identifiant collecté, et chaque appel coûte 20 unités de quota supplémentaires. Après avoir paginé 10 000 messages, vous effectuez 10 000 appels API de plus pour un total de 200 000 unités de quota, soit plus de 33 minutes-utilisateur de quota sous la limite par utilisateur et par projet de 2026.

Le CLI fusionne les deux étapes en une seule commande. nylas email read <id> récupère un message unique avec son corps complet en un appel. nylas email search exécute une requête côté serveur et renvoie les messages correspondants avec leur contenu dans la même réponse. Les deux supportent trois modes de sortie via le flag global --format — table, json et yaml — avec --json comme raccourci pour le mode JSON. Pour la source RFC822 brute que messages.get renvoie avec format=raw, passez --mime à nylas email read. La sortie JSON s'enchaîne proprement dans jq pour les traitements shell en aval.

# Read a single message
nylas email read 18b9a3f2cd47e102 --json

# Search and return full bodies in one round-trip
nylas email search "urgent" --from boss@example.com --json

Paginer les fils de discussion plutôt que les messages

Gmail organise les messages en fils de conversation, et l'endpoint threads.list est une ressource paginée distincte de messages.list. Une boîte de 10 000 messages se résout typiquement en 2 000 à 4 000 fils selon la densité des conversations : lister les fils réduit donc le nombre total de pages de 60 à 80 %. Chaque réponse de fils respecte le même contrat nextPageToken que messages.list, plus un tableau threads[].messages[] contenant chaque message de la conversation.

La surface des fils dans le CLI reflète celle des messages avec cinq commandes. nylas email threads list pagine les fils. nylas email threads show récupère un fil unique par identifiant. nylas email threads search prend une chaîne de requête au format Gmail. nylas email threads mark change l'état de lecture de tous les messages du fil d'un coup. nylas email threads delete supprime la conversation entière.

# Paginate threads in pages of 50
nylas email threads list --limit 50 --json

# Mark a whole conversation as read in one command
nylas email threads mark <thread-id> --read

Paginer au sein d'un libellé ou d'un dossier précis

Gmail organise les messages par libellés — des libellés système comme INBOX, SENT, STARRED, UNREAD, SPAM et TRASH, plus les libellés créés par l'utilisateur. Microsoft Graph et les fournisseurs IMAP utilisent des dossiers à la place. L'endpoint messages.list de Gmail accepte un tableau labelIds pour les libellés système, ou le paramètre q avec une syntaxe de recherche comme label:Receipts pour les libellés personnalisés. Les tokens de pagination conservent la portée du filtre : une archive de 50 000 messages restreinte à un seul libellé renvoie proportionnellement moins de pages.

nylas email search accepte --in pour restreindre une requête à un libellé ou dossier — passez "*" comme requête pour correspondre à tous les messages qu'il contient. nylas email folders list renvoie chaque libellé ou dossier du compte connecté ; le même flag fonctionne donc avec les libellés Gmail, les dossiers Outlook et les noms de dossiers IMAP sans changer de syntaxe. La surface de flags de la commande de recherche inclut aussi --unread, --starred et --has-attachment.

# List every label or folder on the connected account
nylas email folders list --json

# Paginate only inside the Receipts label
nylas email search "*" --in Receipts --limit 100 --json

# Combine label scope with a query
nylas email search "stripe" --in Receipts --json

Paginer sur plusieurs comptes

Les clients de synchronisation en production gèrent souvent plusieurs boîtes mail connectées — une équipe sales-ops agrégeant quatre boîtes partagées, un agent IA opérant sur cinq comptes utilisateur, un CRM extrayant des signaux e-mail de chaque compte d'un espace de travail. L'API Gmail applique le quota par grant OAuth : synchroniser 10 comptes en parallèle fonctionne donc sans throttling inter-comptes, mais le code applicatif doit gérer 10 refresh tokens distincts, 10 minuteurs d'expiration de token et 10 points de contrôle historyId.

Les grants sont des objets de premier plan dans le CLI. nylas auth list affiche chaque compte connecté. nylas auth whoami indique quel grant la prochaine commande utilisera. nylas auth switch change le grant actif. Les commandes e-mail et calendrier acceptent aussi un identifiant de grant comme argument positionnel optionnel : un même script shell peut donc itérer sur les grants sans changer l'état actif.

# Show every connected grant as JSON
nylas auth list --json

# Run the same sync across every Google grant
for grant in $(nylas auth list --json | jq -r '.[] | select(.provider == "google") | .id'); do
  nylas email search "*" "$grant" --after 2026-05-01 --json
done

Synchroniser en CI, dans des cron jobs et en environnement headless

La pop-up OAuth2 dans le navigateur exigée par l'API Gmail est un blocage absolu en CI, dans les conteneurs Docker, les sandboxes d'agents IA et tout environnement sans surveillance. Le flux offline-access de Google impose à l'application de capturer un refresh token lors d'une configuration interactive unique, puis de le stocker dans un gestionnaire de secrets et de le rafraîchir par programmation. L'alternative recommandée (un compte de service avec délégation à l'échelle du domaine) est réservée aux administrateurs Google Workspace et exige un changement de configuration au niveau de l'espace de travail.

Nylas CLI contourne entièrement le navigateur grâce à l'authentification par clé API. nylas auth config --api-key stocke une clé localement sans ouvrir de navigateur. nylas auth token génère un bearer token à portée limitée pour les appels API en aval. nylas auth status rapporte l'état d'authentification courant — utile pour les health checks dans les déploiements conteneurisés.

# In a GitHub Action or cron job — no browser needed
export NYLAS_API_KEY="nyk_..."
nylas auth config --api-key "$NYLAS_API_KEY"
nylas email search "*" --after $(date -u -v-1d +%Y-%m-%d) --json > /var/log/digest.json

Dans Manus, Replit et les sandboxes d'agents IA similaires dépourvues de navigateur, le même flux s'applique — l'agent provisionne une clé une fois, la conserve dans son environnement, et chaque commande suivante s'exécute sans étape interactive.

Des webhooks plutôt que du polling

Interroger une boîte Gmail toutes les 5 minutes génère 288 appels API par jour et par boîte. Sur 1 000 utilisateurs connectés, cela représente 288 000 appels quotidiens, dont la plupart ne renvoient aucun nouveau message. Gmail propose une alternative en notifications push via Cloud Pub/Sub : vous créez un topic Pub/Sub, accordez à gmail-api-push@system.gserviceaccount.com le rôle pubsub.publisher, appelez users.watch sur chaque boîte et renouvelez le watch tous les 7 jours parce que Google le fait expirer. Le coût de mise en place est élevé, et un renouvellement manqué casse la synchronisation en silence.

Les webhooks du CLI fonctionnent sans topic Pub/Sub. nylas webhook create enregistre un endpoint HTTPS et une liste de déclencheurs. nylas webhook list montre ce qui est enregistré. nylas webhook triggers affiche tous les types d'événements supportés (message.created, message.updated, thread.replied, plus les événements calendrier et contacts). nylas webhook test send envoie un payload d'exemple à votre endpoint pour valider le récepteur avant la mise en production. nylas webhook verify valide la signature HMAC des payloads entrants.

# Register a webhook for new message events
nylas webhook create \
  --url https://example.com/hooks/nylas \
  --triggers message.created \
  --json

# Verify a payload from your receiver
nylas webhook verify \
  --payload-file ./incoming.json \
  --signature "$X_NYLAS_SIGNATURE" \
  --secret "$WEBHOOK_SECRET"

Les webhooks se déclenchent sur des événements réels, généralement moins de 100 par boîte et par jour pour un utilisateur moyen. Une charge de polling de 288 000 appels par jour se réduit à environ 100 000 événements quotidiens sur les mêmes 1 000 boîtes, et la latence entre l'arrivée d'un nouveau message et sa prise en compte par l'application passe de 5 minutes au maximum à environ 1 seconde.

Comment les autres fournisseurs e-mail gèrent la pagination

Gmail n'est pas le seul fournisseur dont le contrat de pagination mérite d'être compris. Microsoft Graph (Outlook et Exchange Online) utilise @odata.nextLink — une URL complète que le client suit telle quelle. IMAP (Yahoo Mail, iCloud Mail, IMAP hébergé) ne pagine pas au sens classique : UID SEARCH renvoie tous les UID correspondants en une seule réponse, ce qui peut être lent sur les grandes boîtes mais élimine la logique de curseur côté client. Exchange Web Services (EWS, utilisé par les déploiements Exchange plus anciens) utilise une pagination indexée avec IndexedPageItemView et un offset BasePoint.

Les guides par fournisseur traitent le même problème de pagination dans chaque contrat : Lister les e-mails Outlook depuis la ligne de commande, Lister les e-mails Exchange, Lister les e-mails Yahoo, Lister les e-mails iCloud et Lister les e-mails IMAP. La même commande nylas email list est documentée pour fonctionner avec chaque fournisseur, avec des flags identiques.

Le comportement côté fournisseur décrit ci-dessus pour Outlook, Exchange, Yahoo, iCloud et IMAP provient de la documentation publique de chaque fournisseur, pas d'une exécution de bout en bout vérifiée sur chaque backend. Testez localement avant de déployer des workflows propres à un fournisseur.

Combien de temps prend la synchronisation d'une boîte Gmail ?

Des benchmarks synthétiques sur une boîte mail de test, exécutés sur une connexion haut débit résidentielle (~150 ms de latence médiane vers les serveurs Google), montrent la différence de coût entre la pagination manuelle et une seule commande CLI. La colonne « boucle Python » inclut les appels messages.list + messages.get avec backoff exponentiel sur les réponses 429. Les chiffres du CLI incluent les mêmes appels internes, regroupés et parallélisés.

Le coût en quota est fixé par la tarification par appel de Gmail, pas par le client. Le CLI ne peut pas rendre un appel messages.list moins cher, mais il peut garder la pagination et la logique de retry hors de votre code applicatif. Une boucle Python naïve qui récupère 10 000 corps complets dépense environ 200 000 unités de quota rien qu'en appels messages.get. Suivre ces chiffres compte au moment de planifier une synchronisation complète ; voir nylas email list pour les flags qui contrôlent le batching et la concurrence.

Recettes courantes

Quatre schémas shell qui combinent la pagination e-mail avec les outils UNIX standard. Chacun utilise jq pour parser la sortie JSON et --json pour un format lisible par machine.

Compter tous les e-mails non lus

Enchaînez nylas email list --unread --json avec jq 'length' pour obtenir un seul nombre. Utile pour les tableaux de bord scriptés ou les alertes d'astreinte. Combinez avec watch -n 60 pour un compteur en direct rafraîchi chaque minute. La sortie JSON est paginée automatiquement — vous n'avez pas à gérer nextPageToken dans le wrapper.

nylas email list --unread --json | jq 'length'

Cron job de digest quotidien

Un script de digest exécuté une fois par jour sous cron utilise nylas email search avec --after calé sur la date d'hier, écrit le JSON dans un fichier temporaire et envoie un résumé d'une ligne par message vers mail. Remplacez nylas auth login par nylas auth config --api-key sur la machine qui exécute cron, afin qu'aucun navigateur ne soit nécessaire.

# /etc/cron.daily/email-digest.sh
yesterday=$(date -u -v-1d +%Y-%m-%d)
nylas email search "*" --after "$yesterday" --json > /tmp/digest.json
jq -r '.[] | "\(.from) - \(.subject)"' /tmp/digest.json \
  | mail -s "Daily digest" you@example.com

Trouver tous les e-mails avec pièce jointe d'un expéditeur précis

Chaînez nylas email search avec nylas email attachments list pour trouver toutes les pièces jointes d'un expéditeur en un seul pipeline. email search applique les filtres --from et --has-attachment côté serveur, puis attachments list énumère chaque correspondance. Enchaînez vers nylas email attachments download quand vous voulez les fichiers sur disque.

nylas email search "*" --from billing@stripe.com --has-attachment --json \
  | jq -r '.[].id' \
  | xargs -I{} nylas email attachments list {} --json

Extraire automatiquement les codes OTP des e-mails de connexion récents

Récupérez tous les e-mails liés à une connexion reçus depuis hier, extrayez tout nombre à 6 chiffres du corps et affichez la première correspondance. La requête par mot-clé verification capte le sujet transactionnel le plus courant ; relancez avec OTP ou code pour couvrir d'autres expéditeurs. Pris isolément, c'est la base du guide dédié à l'extraction d'OTP. Pour des analyses de boîte de réception qui vont au-delà du simple comptage, voir nylas email ai analyze. Les utilisateurs PowerShell peuvent adapter ces schémas dans Rapports e-mail en PowerShell.

nylas email search "verification" \
  --after "$(date -u -v-1d +%Y-%m-%d)" \
  --json \
  | jq -r '.[].body' \
  | grep -oE '[0-9]{6}' \
  | head -1

Comparaison côte à côte

Le tableau ci-dessous compare l'approche Python de l'API Gmail à Nylas CLI sur 9 capacités qui comptent en production. La plus grande différence est le temps de mise en place : le chemin API Gmail exige 15 à 20 minutes de configuration dans la console plus 80 à 120 lignes de code, tandis que le CLI prend environ 2 minutes à installer et authentifier.

Questions fréquentes

Qu'est-ce que nextPageToken dans l'API Gmail ?

Quand vous appelez messages.list, l'API Gmail renvoie jusqu'à 500 résultats par page. S'il existe d'autres messages, la réponse inclut une chaîne nextPageToken. Vous passez ce token comme paramètre pageToken dans la requête suivante pour récupérer la page d'après. Vous bouclez ainsi jusqu'à ce que la réponse ne contienne plus de nextPageToken, ce qui signifie que vous avez atteint la fin.

Comment fonctionne la synchronisation incrémentale Gmail avec historyId ?

Chaque changement dans une boîte Gmail (nouveaux messages, suppressions, changements de libellés) reçoit un historyId strictement croissant. Vous stockez le historyId de votre dernière synchronisation, puis appelez history.list avec startHistoryId pour n'obtenir que les changements survenus depuis. Les history IDs expirent après environ 30 jours. Si votre identifiant stocké est trop ancien, l'API renvoie un 404 et il vous faut un repli en synchronisation complète.

Puis-je lister mes e-mails Gmail sans configurer l'API Gmail ?

Oui. Nylas CLI gère OAuth2 et l'authentification fournisseur en interne. Lancez nylas email list --limit 50 --json pour lister votre boîte Gmail sans enregistrer de client API Gmail dans Google Cloud, sans configurer d'écran de consentement OAuth et sans gérer de tokens d'accès. Le CLI fonctionne de la même façon avec six fournisseurs.

Le CLI gère-t-il les limites de débit de l'API Gmail ?

Oui. L'API Gmail accorde aux nouveaux projets 6 000 unités de quota par minute, par utilisateur et par projet, et un appel messages.list coûte 5 unités. Le CLI gère en interne la limitation de débit, la pagination, le rafraîchissement des tokens et la logique de retry. Vous obtenez les résultats sans écrire le moindre code de suivi de quota ou de backoff.

Puis-je paginer les fils Gmail plutôt que les messages ?

Oui. nylas email threads list pagine l'endpoint threads.list au lieu de messages.list. Une boîte mail typique compte environ 1 fil pour 3 à 4 messages : le nombre de pages est donc inférieur de 60 à 80 %. Combinez avec nylas email threads mark pour marquer comme lus tous les messages d'une conversation en une seule commande.

Comment lister les e-mails d'un seul libellé Gmail ?

Passez le nom du libellé à --in sur nylas email search. La commande nylas email search "*" --in Receipts --json ne renvoie que les messages portant le libellé Receipts. Utilisez nylas email folders list pour voir chaque libellé ou dossier du compte. Le même flag fonctionne pour les dossiers Outlook, les dossiers IMAP de Yahoo et les dossiers iCloud sans changer de syntaxe.

Puis-je synchroniser Gmail dans un cron job sans pop-up OAuth ?

Oui. Utilisez nylas auth config --api-key au lieu de nylas auth login. Le flux par clé API n'ouvre pas de navigateur : il fonctionne sur les machines headless, dans les conteneurs Docker, dans les pipelines CI et dans les sandboxes d'agents IA comme Manus. Stockez la clé comme secret dans l'environnement qui exécute le cron job.

Comment synchroniser uniquement les dernières 24 heures d'e-mails ?

Passez --after à nylas email search. Pour les dernières 24 heures : nylas email search "*" --after $(date -u -v-1d +%Y-%m-%d) --json. Le flag prend une date YYYY-MM-DD, et le CLI la traduit dans la syntaxe de filtre du fournisseur sous-jacent — pour Gmail, cela devient une requête q=after: contre l'API.

Le CLI fonctionne-t-il de la même façon avec Outlook, Yahoo et iCloud ?

Oui. Les mêmes commandes nylas email list, nylas email search et nylas email read fonctionnent avec Gmail, Outlook, Exchange, Yahoo, iCloud et IMAP. L'outil traduit chaque commande dans l'appel API propre au fournisseur : l'API REST de Gmail, Microsoft Graph, UID SEARCH en IMAP ou EWS. Les parcours par fournisseur se trouvent dans Lister les e-mails Outlook, Lister les e-mails IMAP et Lister les e-mails Exchange.

Que se passe-t-il si mon historyId a plus de 30 jours ?

Gmail renvoie un 404 depuis history.list et vous devez retomber sur une synchronisation complète par pagination. Le CLI gère ce repli automatiquement — vous ne voyez pas le 404 et vous n'avez pas à écrire deux chemins de code. Le contrôle de concurrence par ETag et la gestion de If-Match sont couverts dans Gestion d'If-Match et des ETags dans l'API Gmail.

Puis-je recevoir des notifications push au lieu de faire du polling ?

Oui. nylas webhook create enregistre un endpoint HTTPS pour des événements comme message.created et thread.replied, sans exiger de topic Cloud Pub/Sub ni d'administrateur Google Workspace. Lancez nylas webhook triggers pour voir tous les types d'événements supportés.

Étapes suivantes

La pagination Gmail et la synchronisation incrémentale sont deux des défis d'intégration API les plus courants, mais pas les seuls. Les guides associés ci-dessous couvrent des workflows adjacents : envoi d'e-mails, contrôle de concurrence par ETag et surface complète des commandes du CLI.

• Lister les e-mails Gmail depuis la ligne de commande — filtrez par expéditeur, sujet, date et état de lecture
• Envoyer du Gmail depuis la ligne de commande — envoi propre à Gmail sans code client API Gmail ni configuration SMTP
• Exemples de requêtes de recherche de l'API Gmail — q, libellés, catégories, pièces jointes et équivalents CLI
• Synchronisation incrémentale de l'API Gmail avec historyId et ETags — plongée dans les ETags, If-Match et la gestion des 412
• Quotas de l'API Gmail en 2026 — unités de quota actuelles, coûts par méthode, seuil de facturation et schémas sûrs pour les agents
• Pourquoi l'API Gmail casse les agents IA — invites OAuth, état de pagination, parsing MIME et pression sur les quotas
• Comparatif des API e-mail pour agents IA — compromis entre Gmail, Microsoft Graph, IMAP et API neutres
• Pagination et synchronisation de l'API Google Calendar — les mêmes schémas appliqués à events.list et syncToken
• Tester les webhooks e-mail en local — validez la synchronisation événementielle avant de remplacer les boucles de polling
• Lister les e-mails Outlook depuis la ligne de commande — pagination Microsoft Graph avec @odata.nextLink
• Lister les e-mails IMAP depuis la ligne de commande — Yahoo, iCloud et IMAP hébergé via UID SEARCH
• Envoyer un e-mail depuis le terminal — workflows d'envoi bash, zsh et multiplateformes
• Extraire les codes OTP des e-mails — automatisez la récupération des codes de vérification dans vos scripts
• Rapports e-mail en PowerShell — les mêmes schémas de pagination adaptés aux shells Windows
• Bien démarrer — méthodes d'installation (Homebrew, script shell, PowerShell, Go) et première authentification
• Référence complète des commandes — chaque flag et sous-commande documentés