Guide

Ajouter la synchronisation e-mail sans IMAP

Construire une synchronisation e-mail signifie souvent maintenir une connexion IMAP IDLE persistante par boîte mail, rafraîchir OAuth et gérer les reconnexions à grande échelle. Ce guide montre le modèle qui remplace tout cela : webhooks pour les nouveaux messages, lectures à la demande pour le backfill, puis prototype complet depuis le terminal.

Written by Caleb Geene Director, Site Reliability Engineering

Reviewed by Qasim Muhammad

Verified — CLI 3.1.17 · Gmail, Outlook, IMAP · last tested June 9, 2026

Pourquoi l'infrastructure de sync IMAP est-elle difficile ?

La synchronisation IMAP est difficile parce que la livraison en temps réel exige une connexion IDLE persistante ouverte pour chaque boîte mail. Selon RFC 2177, un client doit réémettre IDLE au moins toutes les 29 minutes, sinon le serveur peut couper la connexion. 10 000 utilisateurs signifient donc 10 000 sockets de longue durée à maintenir, reconnecter et rééquilibrer entre les processus.

À ces sockets s'ajoutent le refresh de tokens OAuth par compte, l'authentification XOAUTH2, les particularités de chaque provider et les tempêtes de reconnexion quand un nœud redémarre et que des milliers de boîtes mail renégocient en même temps. Cela représente des semaines d'infrastructure avant de parser un seul message — et c'est la partie qui vous réveille à 3 h du matin, pas la fonctionnalité que vous vouliez créer.

Qu'est-ce qui remplace la sync IMAP ?

Le remplacement est un modèle push-plus-pull : un webhook livre une petite notification quand un nouveau message arrive, et votre app lit le message à la demande uniquement lorsqu'elle a besoin du contenu. Vous ne maintenez aucune connexion persistante. Le provider vous dit quand quelque chose a changé ; vous récupérez seulement cet élément, comme le font en dessous les modèles push de Gmail et de Microsoft Graph.

Cela inverse le coût. Au lieu de payer pour garder des milliers de sockets inactifs au chaud, vous payez un webhook léger par nouveau message plus les lectures que vous utilisez vraiment. Une boîte mail qui reçoit 50 messages par jour coûte 50 notifications, pas 24 heures de connexion maintenue.

Comment prototyper une sync e-mail sans IMAP ?

Vous prototypez tout le modèle depuis le terminal en deux commandes. Enregistrez un webhook message.created pour que votre endpoint soit notifié à chaque nouveau message, puis lancez le receiver intégré pour voir arriver les payloads. Pas de framework serveur, pas de pool de sockets — vous voyez exactement la forme push que votre app devra traiter.

# 1. Push new mail to your endpoint
nylas webhook create \
  --url https://your-app.example.com/inbound \
  --triggers message.created \
  --description "email sync"

# 2. Watch payloads locally while you build the handler
nylas webhook server --port 9000

Quand une notification arrive, récupérez le corps du message à la demande. La commande nylas email read prend l'ID du message fourni par le webhook et renvoie le contenu complet en JSON — la seule récupération que vous effectuez, et seulement quand vous en avez besoin.

# In your handler: fetch just the message the webhook pointed at
nylas email read "$MESSAGE_ID" --json | jq '{from: .from, subject: .subject}'

Comment backfiller les messages existants ?

Vous backfillez l'historique avec une recherche à la demande plutôt qu'une synchronisation complète. La commande nylas email search interroge directement la boîte mail, et le filtre de date --after limite l'import à une fenêtre récente pour éviter de tirer des années d'e-mails inutiles. La plupart des apps n'ont besoin que des 30–90 derniers jours lors de l'onboarding.

# One-time backfill of the last 30 days at user onboarding
nylas email search "*" --after 2026-05-10 --json > backfill.json
jq 'length' backfill.json

Quand ai-je encore besoin d'IMAP ?

Vous avez encore besoin d'IMAP lorsqu'une boîte mail n'a pas d'API moderne — un serveur Dovecot auto-hébergé, un hébergeur ancien ou un provider de niche qui n'expose qu'IMAP. Dans ces cas, aucun webhook n'est disponible, donc un client de polling ou IDLE est inévitable. Le compromis honnête : le modèle push exige un provider qui prend en charge les notifications.

Même dans ce cas, le CLI se connecte aux comptes IMAP génériques via la même surface de commandes. Vous obtenez donc un modèle de lecture unifié sans écrire vous-même le client IMAP. La plupart des équipes constatent que le chemin sans IMAP couvre Gmail, Outlook et les principaux providers — la majorité des vrais utilisateurs — et réservent un fallback par polling à la longue traîne.

Étapes suivantes