Démarrer

API de synchronisation des courriels pour une intégration logicielle transparente

Unipile - API de synchronisation d'e-mails Héros
API de synchronisation d'e-mails - Guide 2026

Email API de synchronisation: Comment fonctionne la synchronisation des e-mails pour les produits SaaS

Développez des fonctionnalités SaaS qui synchronisent les boîtes de réception des utilisateurs en temps réel. Connectez Gmail, Outlook et IMAP via une seule API de synchronisation d'e-mails, avec webhooks, flux OAuth et accès complet aux dossiers inclus.

Commencez à synchroniser gratuitement Voir la documentation
sync-emails.js
const UnipileClient = require('@unipile/node-sdk'); const client = new UnipileClient({ dsn : process.env.UNIPILE_DSN, token : process.env.UNIPILE_TOKEN }); // Récupérer les e-mails synchronisés du compte lié const courriels = await client.email.listeEmails({ account_id : 'acc_gmail_xyz', dossier : 'BOÎTE DE RÉCEPTION', limite : 50 }); Temps réel : enregistrer le webhook await client.webhook.create({ url : 'https://votresite.com/webhooks/email', événements : ['email.nouveau', 'email.lire'] });
Synchronisation unifiée sur Gmail, Outlook et IMAP
Les soutiens : Gmail Outlook IMAP
Définition

Qu'est-ce qu'une API de synchronisation des courriels ?

Un API de synchronisation d'e-mails est une interface programmatique qui permet à votre application de refléter en continu la boîte aux lettres d'un utilisateur - en lisant les nouveaux messages, en suivant les changements de statut (lus/non lus, déplacés, supprimés) et en reflétant la structure des dossiers - sans que l'utilisateur n'exporte manuellement de données. Contrairement à une API d'envoi uniquement, une API de synchronisation d'e-mails maintient une réplique intégrale et bidirectionnelle de la boîte de réception au sein de votre produit.

Au niveau du protocole, chaque fournisseur expose sa propre primitive de synchronisation : Gmail utilise histoire.liste avec un identifiantHistorique curseur, Microsoft Graph utilise des requêtes delta sur le /messages/delta point d'accès et les serveurs IMAP standard prennent en charge INACTIF Commande pour les notifications push de type A API de synchronisation d'e-mails unifiée comme Unipile abstrait ces trois protocoles derrière un seul point de terminaison, votre équipe écrit la logique de synchronisation une seule fois et l'expédie vers tous les fournisseurs.

Si vous créez un CRM, un outil d'engagement commercial, un assistant d'e-mails IA ou tout SaaS nécessitant des données de boîte de réception en direct, une API de synchronisation d'e-mails est la base. Pour l'envoi d'e-mails transactionnels (réinitialisations de mot de passe, reçus), il s'agit d'une catégorie différente - voir notre guide complet de l'API d'e-mail.

Mise en miroir de la boîte de réception en temps réel
Gmail, Outlook et IMAP
OAuth 2.0 + actualisation du token
Webhooks pour les nouveaux e-mails
Dossier + synchronisation des étiquettes
Concepts

Synchronisation d'e-mails et envoi d'e-mails : pourquoi la distinction est importante

Les développeurs confondent souvent les API de synchronisation d'e-mails avec les API d'e-mails transactionnels. Elles servent des objectifs opposés. Choisir la mauvaise catégorie peut retarder votre architecture de plusieurs semaines.

Ce que vous construisez
API de synchronisation d'e-mail

Lit et reflète la boîte de réception existante d'un utilisateur dans votre application. Nécessite que l'utilisateur autorise l'accès à son compte (identifiants OAuth ou IMAP). Votre application devient un lecteur secondaire de sa boîte de réception.

  • Lit les messages entrants et sortants
  • Pistes lues/non lues, étiquettes, dossiers
  • Notifications par webhook pour les nouveaux e-mails
  • Accès complet au fil de discussion et aux pièces jointes
  • Synchronisation Delta - ne récupère que les modifications

    • Utilisé par : CRM, outils d'engagement commercial, assistants d'e-mails IA, centres d'assistance, archivage d'e-mails, analyses de boîte de réception.

    Catégorie différente
    API d'e-mails transactionnels

    Envoie des courriels générés par le système depuis ton propre domaine. Aucune autorisation de l'utilisateur n'est nécessaire. Tu t'authentifies en tant qu'expéditeur (clé API), et non en tant qu'utilisateur. Exemples : SendGrid, Mailgun, Resend, Amazon SES.

  • Sortant uniquement (réinitialisations de mot de passe, reçus)
  • Authentifié via une clé API, pas OAuth
  • Axé sur le taux de livraison et SPF/DKIM
  • Pas d'accès en lecture à la boîte de réception
  • Aucun consentement OAuth côté utilisateur requis

    • Unipile n'est PAS dans cette catégorie. Unipile est le côté synchronisation - lecture et mirroring des boîtes de réception des utilisateurs via OAuth.

    Cas d'usage

    Qui a besoin d'une API de synchronisation d'e-mails ?

    Tout produit SaaS qui a besoin d'afficher, d'analyser ou d'agir sur l'e-mail entrant d'un utilisateur s'appuie sur une API de synchronisation d'e-mails. Voici les cinq cas d'utilisation les plus courants que nous rencontrons en production.

    Synchronisation des e-mails CRM

    Enregistrez automatiquement chaque e-mail entrant et sortant sur le bon enregistrement de contact. Les commerciaux cessent de copier-coller des e-mails ; le CRM devient le système de référence en temps réel. Aucune mise en copie carbone (BCC) manuelle requise.

    Guide de l'API e-mail
    Engagement commercial

    Suivez les taux de réponse, détectez les réponses d'absence du bureau et déclenchez des séquences de suivi en fonction des événements de la boîte de réception. Une API de synchronisation d'e-mails permet à vos séquences d'être conscientes en temps réel de ce qui se passe dans la boîte de réception du prospect.

    Envoyer un e-mail par programme
    Agents d'e-mail IA

    Alimentez un flux d'e-mails en direct vers un agent LLM qui rédige des réponses, catégorise les messages entrants, extrait les éléments d'action ou achemine les tickets. L'agent a besoin d'un flux de synchronisation continu, pas d'une exportation unique. Une API de synchronisation d'e-mails en temps réel est obligatoire.

    Lire les e-mails par programme
    Intégration du service d'assistance

    Convertissez automatiquement les e-mails des clients en tickets de support, en incluant tout le contexte du fil de discussion et les pièces jointes. Synchronisez le statut du ticket lorsque l'agent répond, de sorte que la boîte de réception du client reflète le fil de résolution.

    Comparer les fournisseurs d'API d'e-mail
    Archivage d'e-mails

    Capturez chaque e-mail entrant et sortant pour des raisons de conformité, de découverte légale ou d'analyse. Une API de synchronisation d'e-mails vous permet de construire une archive interrogeable de toutes les communications d'entreprise sans toucher directement au serveur de messagerie.

    Niveau gratuit d'API d'e-mail
    Analyse de la boîte de réception

    Analyser le volume des e-mails, les temps de réponse, les modèles de conversation et le sentiment sur les comptes liés d'une équipe. Les équipes marketing, opérations et finance utilisent l'analyse de la boîte de réception pour mesurer la qualité de la communication et identifier les goulets d'étranglement.

    Guide complet de l'API d'e-mail
    Sous le capot

    Comment fonctionne la synchronisation des e-mails : OAuth, Delta Sync et Webhooks

    Une API de synchronisation d'e-mails est plus qu'un point d'accès en lecture. C'est un pipeline avec état qui authentifie les utilisateurs, maintient la fraîcheur des jetons, suit l'état de la boîte aux lettres et livre les changements en temps quasi réel. Voici ce qui se passe à chaque niveau.

    1
    Flux d'autorisation OAuth 2.0

    L'utilisateur clique sur " Connecter votre boîte de réception " dans votre application. Il est redirigé vers l'écran de consentement de Google ou Microsoft, où il approuve les champs d'application que votre application demande. Pour Gmail, cela signifie gmail.lecture seule ou gmail.modifier; pour Outlook cela signifie Mail.Read ou Mail.ReadWrite. Après consentement, votre application reçoit un jeton d'accès (valable 1 heure pour Google, 1 heure pour Microsoft) et un jeton de rafraîchissement (à longue durée de vie). Les comptes IMAP utilisent un nom d'utilisateur + mot de passe ou OAuth selon la configuration du fournisseur.

    2
    Instantané initial de la boîte aux lettres

    Lors de la première synchronisation, l'API de synchronisation d'e-mails effectue un remplissage complet : elle récupère la liste des dossiers (BOITE DE RECEPTION, Envoyés, Brouillons, libellés personnalisés), et récupère les messages récents jusqu'à une profondeur d'historique configurable. Pour Gmail, cela utilise Utilisateurs.messages.lister avec pagination. Pour Microsoft Graph, il utilise GET /moi/messages. Pour IMAP, il émet un BOÎTE DE RÉCEPTION suivi de CHERCHER plage. L'instantané donne à votre base de données son état de référence, y compris les ID de message et groupements de fils.

    3
    Delta Sync - Récupérer uniquement les modifications

    Après la capture initiale, l'interrogation répétée de la boîte aux lettres entière gaspillerait le quota et ralentirait votre application. La synchronisationDelta est la solution. Gmail fournit un identifiantHistorique curseur : vous appelez historique.utilisateurs.liste avec le dernier connu identifiantHistorique et ne recevoir que les modifications (nouveaux messages, changements d'étiquettes, suppressions) depuis ce point. Microsoft Graph utilise GET /moi/messages/delta avec un $jeton delta. IMAP utilise UID RECHERCHE avec un CHANGEDSINCE modifier (extension CONDSTORE). Ceci synchronisation delta Le modèle maintient les appels API au minimum, même pour les boîtes aux lettres à haut volume.

    4
    Rafraîchissement de jeton et maintenance de session

    Les jetons d'accès expirent. Votre infrastructure de synchronisation d'e-mails doit détecter 401 Non autorisé réponses, utilisez le jeton d'actualisation pour obtenir un nouveau jeton d'accès auprès de Google ou Microsoft, et réessayez la requête ayant échoué. Cela doit se produire de manière transparente, sans interrompre la session de l'utilisateur. Les jetons d'actualisation eux-mêmes peuvent être révoqués - par l'utilisateur, par une politique d'administrateur, ou après 6 mois d'inactivité (Google) - votre système doit donc détecter la révocation et inviter l'utilisateur à ré-autoriser.

    5
    Webhooks pour les notifications en temps réel

    Le sondage sur un calendrier introduit de la latence : un sondage de 30 secondes signifie que les e-mails peuvent être obsolètes jusqu'à 30 secondes. Pour les fonctionnalités de boîte de réception en temps réel, l'API de synchronisation des e-mails doit prendre en charge notifications push. Gmail utilise Google Cloud Pub/Sub : vous enregistrez un sujet et Gmail publie une notification à chaque fois que identifiantHistorique avancées. Microsoft Graph utilise les notifications de changement sur le /me/mailFolders/inbox/messages Ressource. Une API de synchronisation d'e-mails unifiée (comme Unipile) les normalise en un seul événement webhook - email.nouveau - livré à votre point de terminaison quel que soit le fournisseur.

    Unipile - APIs de synchronisation d'e-mails natives
    Approfondissement du fournisseur

    API de synchronisation native des e-mails : Gmail, Microsoft Graph et IMAP

    Chacun des trois fournisseurs de messagerie expose un primitive de synchronisation différent. Comprendre les différences vous explique pourquoi la création d'une API de synchronisation d'e-mails multi-fournisseurs à partir de zéro prend des mois, et non des jours.

    Logo Gmail Gmail - historique.liste + Pub/Sub Comptes Google Workspace et personnels

    Le modèle de synchronisation de Gmail est bâti autour du identifiantHistorique curseur. Après votre synchronisation initiale, chaque appel ultérieur à historique.utilisateurs.liste retourne uniquement les modifications depuis votre dernière connaissance identifiantHistorique - nouveaux messages, ajouts d'étiquettes, suppressions d'étiquettes et suppressions.

    Pour push en temps réel, Gmail vous demande de configurer un sujet Google Cloud Pub/Sub et d'appeler utilisateurs.regarder pour l'enregistrer. Gmail publie alors une notification (contenant un nouveau identifiantHistorique) à votre rubrique chaque fois que la boîte aux lettres change. Votre worker s'abonne à la rubrique et appelle histoire.liste pour récupérer les modifications réelles.

    Limites de taux : 1 milliard d'unités de quota par jour et par projet, avec des limites par utilisateur. utilisateurs.messages.obtenir coûte 5 unités ; historique.utilisateurs.liste coûte 2 unités. Pour une application multi-locataire, la gestion des quotas devient une préoccupation à temps plein. Voir le Guide API d'envoi d'e-mails pour plus.

    gmail-delta-sync.py
    from googleapiclient.discovery import construire Synchronisation Delta # à l'aide du curseur historyId déf récupérer les modifications(service, id_historique) résultat = service.users().historique().list( identifiantUtilisateur=moi, identifiantDébutHistorique=id_historique, types d'historique=[ 'messageAjouté', 'messageSupprimé', 'labelAjouté' ] ).exécutez() return résultat.obtenir('histoire', [])
    Logo Outlook et Microsoft 365 Outlook / Microsoft 365 - Requêtes delta Graph Outlook Personnel et Exchange Online / M365

    Microsoft Graph utilise requêtes delta sur le /moi/messages/delta point de terminaison. Le premier appel renvoie une page complète de messages plus un @odata.deltaLink. Les appels ultérieurs à ce lien delta renvoient uniquement les messages modifiés depuis l'appel précédent : éléments nouveaux, modifiés et supprimés.

    Pour push en temps réel, Microsoft Graph prend en charge les notifications de modification via les webhooks. Vous enregistrez un abonnement sur /me/mailFolders/inbox/messages avec un notificationUrl. Microsoft envoie un POST à votre URL lorsque les messages changent. Les abonnements doivent être renouvelés toutes les 4230 minutes (environ 3 jours) ou ils expirent.

    Remarque : Ceci couvre à la fois les comptes Outlook personnels et Microsoft 365 / Exchange Online – ils utilisent la même API Graph. Voir le Guide d'intégration de la messagerie Microsoft Graph pour plus de détails sur l'enregistrement de l'application et le consentement de l'administrateur.

    graph-delta-sync.js
    SynchronisationDelta de Microsoft Graph async function fetchDeltaMessages(client, deltaLink) { const url = lienDelta || '/moi/messages/delta'; const res = await client .api(URL) .sélectionner('id,sujet,de,dateRéception') .obtenir(); return { messages : res.value, nextDelta : res['@odata.deltaLink'] }; }
    Logo IMAP IMAP - commande IDLE + UID FETCH Solution de repli universelle pour tout serveur de messagerie

    IMAP (RFC 3501) est antérieur aux API de synchronisation modernes de plusieurs décennies. Il expose, par dossier numéros de séquence et UIDs. Pour la synchronisation delta, le CONDSTORE extension (RFC 7162) ajoute une MODSEQ valeur à chaque message, vous permettant de ne récupérer que les messages ayant une MODSEQ plus élevé que ta dernière valeur connue via UID FETCH * (FLAGS) (CHANGEDSINCE modseq).

    Pour push en temps réel, IMAP prend en charge INACTIF commande (RFC 2177). Votre client envoie INACTIF et le serveur pousse EXISTE ou EFFACER réponses lorsque le dossier change - pas de sondage nécessaire. La plupart des serveurs IMAP prennent en charge IDLE ; les connexions doivent être actualisées toutes les 29 minutes pour éviter les interruptions.

    IMAP est essentiel car il prend en charge tous les serveurs de messagerie non gérés par Google ou Microsoft : Exchange d'entreprise (sur site), ProtonMail, Zoho, Fastmail et domaines personnalisés. Voir le Guide d'intégration IMAP pour une explication complète de la mise en œuvre.

    imap-idle-sync.js
    const Imap = require('imap'); const imap = new Imap({ hôte, port : 993, tls : true }); imap.une fois('prêt', () => { imap.ouvrir une boîte('BOÎTE DE RÉCEPTION', true, () => { imap.on('courriel', (nouveauNombre) => { // POUSSER au repos : nouveau courrier arrivé récupérerNouveauxMessages(numNouvel); }); }); });
    Unipile - Couverture des fonctionnalités de l'API d'e-mail
    Capacités de l'API

    Couverture des fonctionnalités de l'API d'e-mail par fournisseur

    Une seule intégration Unipile vous donne accès à toutes les opérations d'e-mail sur les fournisseurs Gmail, Outlook et IMAP. Cliquez sur l'en-tête de n'importe quel fournisseur pour lire le guide d'intégration complet.

    Fonctionnalité Gmail Outlook / M365 IMAP / SMTP
    Authentification
    OAuth2 (pas de stockage de mot de passe) ✓ ✓ Mot de passe d'application
    Flux d'authentification / consentement hébergé ✓ ✓ ✓
    Actualisation automatique du jeton ✓ ✓ ✓
    Opérations par e-mail
    Envoyer un e-mail depuis le compte utilisateur ✓ ✓ ✓
    Lire et lister les e-mails ✓ ✓ ✓
    Envoyez avec pièces jointes ✓ ✓ ✓
    Répondre dans le fil de discussion existant ✓ ✓ ✓
    Gestion des brouillons ✓ ✓ ✓
    Étiquettes / Dossiers ✓Étiquettes ✓Dossiers ✓Dossiers
    Limite d'envoi quotidienne (env.) ~500 / jour ~10 000 / jour Dépendant du serveur
    Synchronisation et événements
    Webhooks en temps réel ✓ ✓ ✓
    Synchronisation delta incrémentielle ✓ ✓ ✓
    Regroupement de fils ✓ ✓ ✓
    SOC 2 Type II / CASA Niveau 2 ✓ ✓ ✓
    Guides d'intégration des fournisseurs
    Gmail
    Gmail Lire le guide d'intégration
    Outlook
    Outlook / M365 Lire le guide d'intégration
    IMAP
    IMAP / SMTP Lire le guide d'intégration
    Authentification
    OAuth2 (pas de stockage de mot de passe)
    GmailGmail
    ✓
    OutlookOutlook / M365
    ✓
    IMAPIMAP / SMTP
    Mot de passe d'application
    Flux d'authentification / consentement hébergé
    GmailGmail
    ✓
    OutlookOutlook / M365
    ✓
    IMAPIMAP / SMTP
    ✓
    Actualisation automatique du jeton
    GmailGmail
    ✓
    OutlookOutlook / M365
    ✓
    IMAPIMAP / SMTP
    ✓
    Opérations par e-mail
    Envoyer un e-mail depuis le compte utilisateur
    GmailGmail
    ✓
    OutlookOutlook / M365
    ✓
    IMAPIMAP / SMTP
    ✓
    Lire et lister les e-mails
    GmailGmail
    ✓
    OutlookOutlook / M365
    ✓
    IMAPIMAP / SMTP
    ✓
    Envoyez avec pièces jointes
    GmailGmail
    ✓
    OutlookOutlook / M365
    ✓
    IMAPIMAP / SMTP
    ✓
    Répondre dans le fil de discussion existant
    GmailGmail
    ✓
    OutlookOutlook / M365
    ✓
    IMAPIMAP / SMTP
    ✓
    Gestion des brouillons
    GmailGmail
    ✓
    OutlookOutlook / M365
    ✓
    IMAPIMAP / SMTP
    ✓
    Étiquettes / Dossiers
    GmailGmail
    ✓Étiquettes
    OutlookOutlook / M365
    ✓Dossiers
    IMAPIMAP / SMTP
    ✓Dossiers
    Limite d'envoi quotidienne (env.)
    GmailGmail
    ~500 / jour
    OutlookOutlook / M365
    ~10 000 / jour
    IMAPIMAP / SMTP
    Dépendant du serveur
    Synchronisation et événements
    Webhooks en temps réel
    GmailGmail
    ✓
    OutlookOutlook / M365
    ✓
    IMAPIMAP / SMTP
    ✓
    Synchronisation delta incrémentielle
    GmailGmail
    ✓
    OutlookOutlook / M365
    ✓
    IMAPIMAP / SMTP
    ✓
    Regroupement de fils
    GmailGmail
    ✓
    OutlookOutlook / M365
    ✓
    IMAPIMAP / SMTP
    ✓
    SOC 2 Type II / CASA Niveau 2
    GmailGmail
    ✓
    OutlookOutlook / M365
    ✓
    IMAPIMAP / SMTP
    ✓
    Essai gratuit

    Évitez les remplissages Gmail + Graph + IMAP. Une seule API de synchronisation d'e-mails couvre les trois.

    L'API de synchronisation unifiée d'e-mails d'Unipile se connecte à Gmail, Outlook et IMAP via un point d'accès unique. Flux OAuth, rafraîchissement de jeton, synchronisation delta et webhooks - tout est géré pour vous. Commence gratuitement, aucune carte de crédit requise.

    Essai gratuit Lire la documentation
    Sans cb
    Niveau d'API d'e-mail gratuit disponible
    En marche en 5 minutes
    Ingénierie de la réalité

    La complexité cachée de la synchronisation des e-mails à grande échelle

    Construire une preuve de concept d'API de synchronisation d'e-mails prend un week-end. En construire une qui soit fiable en production avec 1 000 comptes connectés prend des mois. Voici ce que personne ne vous dit au départ.

    Gestion des limites de taux

    Gmail applique des quotas par utilisateur (250 unités de quota/seconde) et des limites quotidiennes par projet. Microsoft Graph limite à 10 000 requêtes toutes les 10 minutes par application. Avec 500 comptes liés effectuant une synchronisation planifiée, vous avez besoin d'un limiteur de débit distribué avec réessai exponentiel, jitter et isolation des files d'attente par compte. Une seule rafale d'un compte peut épuiser le quota de tous les autres.

    Rafraîchissement de jeton à grande échelle

    Chaque compte lié possède un jeton d'accès qui expire. À 1 000 comptes, attendez-vous à des dizaines de rafraîchissements de jetons simultanés pendant les fenêtres de synchronisation de pointe. Un seul rafraîchissement échoué entraîne une cascade de cycles de synchronisation manqués. Vous avez besoin d'un service de cycle de vie de jetons dédié avec une logique de nouvelle tentative, une détection de révision et un pipeline d'alerte pour inciter les utilisateurs à réautoriser lorsque les jetons d'actualisation expirent.

    Complexité des dossiers et des étiquettes

    Gmail utilise des libellés (un message peut avoir plusieurs libellés simultanément). Outlook utilise des dossiers (hiérarchiques, avec des opérations de déplacement). IMAP utilise également des dossiers, mais avec espaces de noms qui varient selon le fournisseur du serveur. La normalisation de ces éléments en un modèle de dossier cohérent pour votre application nécessite une logique de mappage spécifique au fournisseur. Les cas limites incluent les boîtes aux lettres partagées, l'accès délégué et la distinction de Gmail entre "Tous les e-mails" et "Boîte de réception".

    Stockage et streaming de pièces jointes

    Les pièces jointes des e-mails peuvent être volumineuses. La récupération et le stockage des pièces jointes pour chaque e-mail synchronisé sur des milliers de comptes augmentent rapidement les coûts en bande passante et en stockage. Vous avez besoin d'un pipeline de streaming qui télécharge les pièces jointes uniquement à la demande, d'un stockage dédupliqué et d'une couche CDN pour les diffuser depuis votre produit. L'analyse MIME elle-même introduit des bogues - les e-mails multiparti, le codage quoted-printable et les pièces jointes intégrées nécessitent chacun un traitement spécifique.

    Reconstruction du fil

    Fils Gmail par threadId - un concept côté serveur. IMAP n'a pas de hiérarchisation native des fils de discussion ; vous reconstruisez les fils en utilisant Références et En réponse à en-têtes (RFC 5322). Outlook a identifiant_conversation. La normalisation des fils de discussion entre les fournisseurs, en particulier pour les réponses inter-fournisseurs, nécessite des heuristiques de secours basées sur la normalisation des sujets et les chaînes d'identifiants de message.

    Fiabilité des webhooks et nouvelle livraison

    Les notifications Pub/Sub de Gmail ne sont pas garanties – les messages manqués pendant les temps d'arrêt ne sont pas renvoyés. Les abonnements aux webhooks de Microsoft Graph expirent et doivent être renouvelés. Si votre récepteur de webhook est en panne lors d'une notification push, vous manquez l'événement et devez recourir à l'interrogation. Une API de synchronisation d'e-mails de production nécessite une boucle de réconciliation qui rattrape périodiquement les événements manqués à l'aide du curseur de synchronisation delta, indépendamment de la disponibilité des webhooks.

    Comparaison d'architecture

    3 Architectures de Synchronisation d'E-mails Comparées

    Les équipes qui développent des fonctionnalités de synchronisation d'e-mails évaluent généralement trois modèles d'implémentation. Voici une comparaison honnête de chacun, du coût de développement au coût de maintenance continue.

    Bricolage
    Intégration directe du fournisseur
    Gmail API + Microsoft Graph + IMAP - séparément
    Temps de construction 3-6 mois
    Fournisseurs couverts 1 par sprint
    Gestion des jetons OAuth codebase 3x
    Gestion des webhooks 3 systèmes différents
    Maintenance en cours Élevé (changements d'API)
    Modèle de coûts Génie du temps
    Idéal pour: les équipes qui souhaitent un contrôle total et qui ont 6 mois ou plus à investir dans l'infrastructure.
    Auto-hébergé
    Couche IMAP auto-hébergée
    Exécutez votre propre proxy de messagerie (Dovecot / Cyrus / personnalisé)
    Temps de construction 2-4 mois
    Fournisseurs couverts IMAP uniquement (général)
    Gestion des jetons OAuth Identifiants IMAP uniquement
    Gestion des webhooks Basé sur IDLE, personnalisé
    Maintenance en cours Moyen
    Modèle de coûts Infra + ingénierie
    Idéal pour : les équipes dont les utilisateurs sont exclusivement sur des serveurs compatibles IMAP et n'ont pas besoin d'OAuth Google ou Microsoft.
    Recommandé
    API de synchronisation d'e-mails unifiée
    Unipile - une API pour Gmail, Outlook et IMAP
    Temps de construction 1-3 jours
    Fournisseurs couverts Gmail + Outlook + IMAP
    Gestion des jetons OAuth Géré par Unipile
    Gestion des webhooks Modèle d'événement unifié
    Maintenance en cours Faible
    Modèle de coûts Par compte lié
    Idéal pour : les équipes SaaS qui ont besoin d'expédier la synchronisation des e-mails rapidement et qui ne veulent pas maintenir une infrastructure spécifique au fournisseur.
    Démarrage rapide

    Synchronisation des e-mails avec l'API de synchronisation d'e-mails unifiée d'Unipile

    L'API de synchronisation d'e-mails d'Unipile couvre Gmail, Outlook et IMAP via une interface unifiée. Les flux OAuth, le rafraîchissement des jetons, la synchronisation delta et la livraison des webhooks sont tous gérés pour vous – votre équipe livre la fonctionnalité, pas l'infrastructure.

    1
    Créer un compte Unipile

    Inscription à tableau de bord.unipile.com. Le niveau gratuit de l'API d'e-mail vous donne accès à tous les fournisseurs sans carte de crédit requise. Vous obtenez votre DSN (Data Source Name) et votre jeton API immédiatement.

    2
    Lier le compte e-mail d'un utilisateur

    Utilisez le flux OAuth hébergé d'Unipile pour permettre à votre utilisateur d'autoriser l'accès à son compte Gmail ou Outlook. Pour IMAP, collectez leurs identifiants et transmettez-les à POST /comptes. Unipile gère la redirection OAuth, l'échange de jetons et stocke le jeton de rafraîchissement en toute sécurité.

    3
    Liste des e-mails synchronisés

    Appel GET /emails avec le account_id du compte lié. Unipile exécute la synchronisation delta contre Gmail histoire.liste, le point de terminaison delta de Microsoft Graph, ou IMAP CONDSTORE - vous obtenez toujours la même réponse JSON normalisée quel que soit le fournisseur.

    4
    Enregistrer un webhook pour la synchronisation en temps réel

    POSTez l'URL de votre point de terminaison à l'API webhook d'Unipile. Lorsqu'un nouvel e-mail arrive dans un compte lié - qu'il s'agisse de Gmail, Outlook ou IMAP - Unipile livre un courriel normalisé email.nouveau événement à votre URL. Pas de configuration Pub/Sub, pas de renouvellement d'abonnement au graphique, pas de gestion de connexion IDLE. Voir le Guide API d'envoi d'e-mails pour la référence complète de l'événement.

    5
    Lire le contenu complet de l'e-mail et les pièces jointes

    Appel GET /emails/{id} pour récupérer le corps complet du message (HTML et texte brut), les en-têtes, les parties MIME et les références aux pièces jointes. Les pièces jointes sont servies via des URL signées - vous n'avez jamais à stocker vous-même les données MIME brutes. Voir lire des e-mails par programmation par exemple.

    unipile-email-sync.js
    const axios = require('axios'); const DSN = process.env.UNIPILE_DSN; const Jeton = process.env.UNIPILE_TOKEN; const api = axios.create({ baseURL: https://${DSN}/api/v1, headers : { 'X-API-KEY': JETON } }); // Étape 3 - Lister les e-mails synchronisés async function listeEmails(accountId) { const { données } = await api.obtenir('/courriels', { params : { account_id: account_id, dossier : 'BOÎTE DE RÉCEPTION', limite : 20 } }); return données.éléments; } // Étape 4 - Enregistrer le webhook async function enregistrerWebhook() { await api.poste('/webhooks', { url : 'https://yourapp.com/api/email-events', événements : ['email.nouveau', 'email.modifié'] }); } // Étape 5 - Obtenir le contenu complet de l'e-mail async function ObtenirEmail(emailId) { const { données } = await api.obtenir(`/emails/${emailId}`); return données; }
    Fonctionne avec Gmail, Outlook et IMAP - même code
    API de synchronisation des e-mails Unipile

    Arrêtez de reconstruire le même pipeline de synchronisation d'e-mails pour chaque fournisseur.

    Connectez Gmail, Outlook et IMAP grâce à une seule API de synchronisation d'e-mails. Webhooks en temps réel, synchronisationDelta et gestion des jetons OAuth - tout est pris en charge. Votre équipe se concentre sur le produit, pas sur l'infrastructure.

    Essai gratuit Aucune carte de crédit n'est requise Voir le niveau gratuit de l'API d'e-mails
    Unipile - Comparaison de la synchronisation d'e-mails en temps réel
    Options en temps réel

    Synchronisation d'e-mails en temps réel : Webhooks vs. Interrogation vs. IMAP IDLE

    Choisir le mauvais mécanisme en temps réel pour votre API de synchronisation d'e-mails ajoute de la latence, consomme votre quota, ou laisse votre application dans l'incapacité de fonctionner lors de pannes. Voici une comparaison directe des trois approches.

    Approche Comment cela fonctionne-t-il ? Temps de latence Meilleur pour Complexité
    Webhooks (push) Le fournisseur envoie une requête HTTP POST à votre point de terminaison lorsqu'une boîte aux lettres change. Gmail utilise Pub/Sub ; Microsoft Graph utilise les notifications de modification. Moins de 5 ans Gmail, Outlook, API unifiées comme Unipile Moyen gestion des abonnements requise
    Sondage (programmé) Votre travailleur appelle l'API du fournisseur selon une planification (toutes les 30s, 1min, 5min) et récupère les modifications à l'aide d'un curseur delta. 30s-5min Tous les prestataires, configurations simples Faible - mais intensif en quotas à grande échelle
    IMAP IDLE (sonde longue) Votre client envoie IDLE au serveur ; le serveur envoie des notifications EXISTS lorsque de nouveaux e-mails arrivent. Connexion maintenue ouverte jusqu'à 29 min. Moins de 1 an Serveurs IMAP uniquement Elevé - une connexion TCP par boîte aux lettres
    Webhooks (push)
    Comment cela fonctionne-t-il ? Le fournisseur envoie une requête HTTP POST à votre point de terminaison lorsqu'une boîte aux lettres change. Gmail utilise Pub/Sub ; Microsoft Graph utilise les notifications de modification.
    Temps de latence Moins de 5 ans
    Meilleur pour Gmail, Outlook, API unifiées comme Unipile
    Complexité Moyengestion des abonnements requise
    Sondage (programmé)
    Comment cela fonctionne-t-il ? Votre travailleur appelle l'API du fournisseur selon une planification (toutes les 30s, 1min, 5min) et récupère les modifications à l'aide d'un curseur delta.
    Temps de latence 30s-5min
    Meilleur pour Tous les prestataires, configurations simples
    Complexité Faiblemais gourmande en quotas à grande échelle
    IMAP IDLE (sonde longue)
    Comment cela fonctionne-t-il ? Votre client envoie IDLE au serveur ; le serveur envoie des notifications EXISTS lorsque de nouveaux e-mails arrivent. Connexion maintenue ouverte jusqu'à 29 min.
    Temps de latence Moins de 1 an
    Meilleur pour Serveurs IMAP uniquement
    Complexité Elevéune connexion TCP par boîte aux lettres

    Recommandation de production : Utilisez les webhooks comme mécanisme principal en temps réel et exécutez un secours de synchronisation incrémentielle par interrogation (toutes les 5 minutes) pour rattraper les événements manqués pendant les temps d'arrêt. Avec l'API de synchronisation des e-mails d'Unipile, les deux sont configurés une seule fois - l'unifié email.nouveau le webhook se déclenche que le compte soit Gmail, Outlook ou IMAP, et une boucle de rapprochement en arrière-plan gère automatiquement les événements manqués.

    La sécurité et la conformité

    Sécurité et conformité pour les API de synchronisation des e-mails

    L'accès aux boîtes de réception des utilisateurs crée d'importantes obligations de sécurité et réglementaires. Voici ce que votre implémentation d'API de synchronisation d'e-mails doit aborder avant d'être mise en production.

    OAuth Scopes - Moindre privilège

    Demandez uniquement les étendues dont votre application a besoin. Pour la synchronisation des e-mails en lecture seule, demandez gmail.lecture seule au lieu de gmail.modifier. Pour Microsoft Graph, la demande Mail.Read au lieu de Mail.ReadWrite. La vérification CASA de Google (requise pour les applications comptant plus de 100 utilisateurs) examine de près les champs que vous avez demandés ; un sur-dimensionnement retarde l'approbation.

    Stockage de jetons - Chiffrement au repos

    Les jetons de rafraîchissement OAuth sont des identifiants de longue durée qui accordent un accès complet à la boîte aux lettres. Ils doivent être stockés chiffrés au repos (AES-256 minimum) et ne jamais être enregistrés dans les journaux. Faites pivoter périodiquement les clés de chiffrement de vos jetons. Une compromission d'un jeton de rafraîchissement équivaut à une compromission du mot de passe pour le compte de messagerie connecté.

    RGPD et résidence des données

    Le contenu des e-mails synchronisé par les utilisateurs de l'UE est considéré comme des données personnelles au sens du RGPD. Vous avez besoin d'une base juridique pour le traitement (généralement le consentement explicite de l'utilisateur via OAuth), d'un accord de traitement des données avec votre fournisseur d'API de synchronisation d'e-mails et d'une politique claire de conservation des données. Si votre infrastructure est basée aux États-Unis, assurez-vous d'avoir des clauses contractuelles types (CCT) ou un mécanisme de transfert équivalent pour les données de l'UE.

    Vérification Google CASA

    Toute application utilisant des scopes OAuth Gmail avec plus de 100 utilisateurs doit compléter le processus de Google. CASA (Cloud Application Security Assessment). Ceci est une révision de sécurité de votre application, incluant le code, l'infrastructure et la justification de la portée OAuth. Le processus prend 4 à 8 semaines. Commencez tôt – échouer à la CASA signifie perdre l'accès à Gmail pour tous les utilisateurs jusqu'à ce que vous réussissiez.

    Vérification de signature de webhook

    Toujours vérifier la signature des charges utiles de webhook entrantes de votre API de synchronisation d'e-mails. Un webhook non signé ou mal vérifié peut être usurpé pour injecter de faux événements d'e-mail dans votre application. Unipile signe toutes les livraisons de webhook avec HMAC-SHA256. Vérifiez la X-Unipile-Signature en-tête avant de traiter tout événement.

    Journalisation d'audit

    Enregistrez chaque action que votre application effectue sur les données d'e-mail synchronisées : qui a accédé à quels messages, quand et ce qui a été fait avec les données. Les journaux d'audit sont requis pour la conformité SOC 2 Type II et sont souvent la première chose que les clients d'entreprise demandent lors des examens de sécurité. Conservez les journaux pendant au moins 90 jours, idéalement 1 an.

    Pièges courants

    Pièges courants lors de la création d'une API de synchronisation d'e-mails

    Voici les bogues et les erreurs d'architecture que nous rencontrons le plus souvent dans les implémentations d'API de synchronisation d'e-mails. Tous ces problèmes sont évitables grâce à de bons choix de conception dès le départ.

    1
    Ne pas gérer les échecs de rafraîchissement de jeton avec élégance

    Lorsqu'un jeton de rafraîchissement expire ou est révoqué, une implémentation naïve génère une erreur et arrête la synchronisation - silencieusement. L'utilisateur ne sait pas que sa boîte de réception a cessé de se synchroniser avant de remarquer des données obsolètes. Réparer : mettre en œuvre une couche de détection de révocation qui intercepte grant_invalide erreurs, marque le compte lié comme nécessitant une ré-autorisation et informe l'utilisateur via le système de notification de votre produit.

    2
    Interrogation de manière trop agressive et atteinte des limites de débit

    Interroger toutes les 10 secondes sur 200 comptes liés épuise le quota par projet de Gmail en quelques heures. Microsoft Graph commence à retourner 429 Trop de demandes. Le résultat est des échecs de synchronisation silencieux pour tous les comptes - pas seulement ceux qui ont déclenché le ralentissement. Réparer : Utilisez les webhooks comme mécanisme principal avec un repli de sondage toutes les 5 minutes, et implémentez une limitation de débit par compte avec une exponentielle décroissante sur tous les [éléments]. 429 réponses.

    3
    Stocker le corps MIME brut au lieu du contenu analysé

    Le MIME brut est volumineux, difficile à interroger et coûteux à analyser à la lecture. Un seul e-mail avec pièces jointes peut peser plusieurs centaines de kilo-octets. Réparer : Analyser le format MIME lors de l'importation : extraire séparément le corps HTML, le texte brut de secours, les en-têtes et les métadonnées des pièces jointes. Stocker les fichiers binaires des pièces jointes dans un système de stockage objet (S3 ou équivalent), et non dans votre base de données principale. Cette mesure permet à elle seule de réduire vos coûts de stockage de 60 à 80 % pour des boîtes mail d'entreprise classiques.

    4
    Fil d'e-mails manquant entre différents fournisseurs

    Gmail threadId fonctionne uniquement dans Gmail. Si votre application affiche un fil de discussion qui s'étend sur un compte Gmail et un compte Outlook (par exemple, une réponse envoyée depuis une boîte aux lettres différente), les identifiants de fil natifs sont inutiles. Réparer : concevoir un moteur de threading inter-fournisseurs basé sur le Message-ID, En réponse à, ou encore Références en-têtes. Normaliser les lignes d'objet (supprimer les préfixes Re:/Fwd:) comme solution de repli pour les e-mails où ces en-têtes sont manquants.

    5
    Perte du curseur de synchronisation au redémarrage

    La synchronisation Delta s'appuie sur un curseur stocké : celui de Gmail. identifiantHistorique, l'API Microsoft Graph lienDelta, IMAP MODSEQ. Si votre worker de synchronisation redémarre et que le curseur n'est stocké qu'en mémoire, vous perdez votre position dans le flux de modifications. La prochaine synchronisation redémarre à partir de zéro, dupliquant tous les messages historiques ou manquant le décalage. Réparer : persister le curseur dans votre base de données après chaque cycle de synchronisation réussi, de manière atomique avec le dernier lot de modifications traitées.

    6
    En ignorant la distinction entre les e-mails envoyés et reçus

    Pour les cas d'utilisation de CRM, vous avez besoin des e-mails entrants (reçus) et sortants (envoyés) pour construire une chronologie complète des communications. L'étiquette BOÎTE DE RÉCEPTION de Gmail ne couvre que les e-mails reçus ; vous avez également besoin VOYAGE. Microsoft Graph exige de requêter les Éléments envoyés dossier séparément. IMAP requiert de sélectionner le Envoyés dossier explicitement. Réparer : synchroniser tous les dossiers pertinents lors de la configuration du compte, pas seulement la boîte de réception, et mapper les noms de dossiers spécifiques au fournisseur à des types normalisés dans votre modèle de données.

    FAQ

    Questions fréquemment posées sur les API de synchronisation d'e-mails

    Les questions les plus fréquentes des développeurs lors de la première implémentation d'une API de synchronisation d'e-mails.

    1
    Qu'est-ce qu'une API de synchronisation d'e-mails ?
    +
    Un API de synchronisation d'e-mails est une interface programmatique qui synchronise en continu la boîte de messagerie d'un utilisateur avec votre application. Elle lit les messages entrants et sortants, suit les changements de statut (lu/non lu, déplacements dans les dossiers, suppressions) et diffuse des notifications en temps réel via des webhooks lorsque de nouveaux e-mails arrivent. Contrairement à une API d'e-mails transactionnels (qui envoie des e-mails système), une API de synchronisation d'e-mails nécessite que l'utilisateur autorise l'accès à sa boîte de réception existante via OAuth.
    2
    Quelle est la différence entre une API de synchronisation d'e-mails et une API d'e-mails transactionnels ?
    +
    Une API de synchronisation d'e-mails lit et reflète la boîte de réception existante d'un utilisateur (Gmail, Outlook, IMAP) dans votre application à l'aide d'OAuth. Une API d'e-mails transactionnels (comme SendGrid ou Mailgun) envoie des e-mails générés par le système à partir de votre propre domaine à l'aide d'une clé API, sans accès à la boîte de réception de l'utilisateur. Elles servent des objectifs opposés et ciblent des marchés complètement différents. Unipile appartient à la catégorie de la synchronisation d'e-mails - ce n'est pas un expéditeur transactionnel.
    3
    Quels fournisseurs d'e-mail l'API de synchronisation d'e-mails d'Unipile prend-elle en charge ?
    +
    L'API de synchronisation d'e-mails d'Unipile prend en charge trois fournisseurs : Gmail (Google), Outlook / Microsoft 365 (Microsoft Graph - couvre à la fois Outlook personnel et M365 professionnel / Exchange Online), et IMAP (couvrant tout serveur de messagerie, y compris Exchange d'entreprise, ProtonMail, Zoho, Fastmail et domaines personnalisés). Les trois sont accessibles via le même point d'accès API unifié.
    4
    Comment fonctionne la synchronisation delta dans une API de synchronisation d'e-mails ?
    +
    Delta sync signifie la récupération des modifications depuis la dernière position connue dans le flux de modifications de la boîte aux lettres, plutôt que de récupérer tous les messages à chaque sonderie. Gmail utilise un identifiantHistorique curseur avec le historique.utilisateurs.liste point de terminaison. Microsoft Graph utilise une lienDelta retourné par le /messages/delta point de terminaison. IMAP utilise le MODSEQ valeur de l'extension CONDSTORE. Une API de synchronisation d'e-mails unifiée normalise ces trois mécanismes différents derrière une interface cohérente.
    5
    Quelle est la différence entre le polling et les webhooks pour la synchronisation des e-mails ?
    +
    Le "polling" signifie que votre système interroge l'API de messagerie à intervalles réguliers (toutes les 30 secondes, toutes les minutes, etc.) pour vérifier la présence de nouveaux messages. Les "webhooks" sont basés sur le push : le fournisseur (ou une API unifiée) envoie une requête HTTP POST à votre point de terminaison immédiatement dès qu'un nouvel e-mail arrive. Les webhooks offrent une synchronisation quasi en temps réel (latence inférieure à 5 secondes), tandis que le polling introduit une latence égale à votre intervalle de polling. En production, la meilleure approche est d'utiliser les webhooks comme méthode principale, avec un fallback de polling de synchronisation delta pour les événements manqués.
    6
    Combien de temps faut-il pour configurer la synchronisation d'e-mails avec Unipile ?
    +
    La plupart des développeurs ont un travail synchronisation des e-mails intégration s'exécutant en une seule journée. Les étapes clés sont : créer un compte Unipile (gratuit, sans carte de crédit), utiliser le flux OAuth hébergé pour permettre à un utilisateur de connecter son compte Gmail ou Outlook, appeler GET /emails avec le account_id pour récupérer les messages synchronisés, et enregistrer un point de terminaison webhook pour recevoir en temps réel email.nouveau événements. Unipile gère automatiquement l'OAuth, le rafraîchissement des jetons, la synchronisation différentielle et la livraison des webhooks.
    7
    Quels scopes OAuth ai-je besoin pour la synchronisation des e-mails ?
    +
    Pour la synchronisation Gmail en lecture seule, demande gmail.lecture seule. Si vous avez besoin de marquer les messages comme lus ou de les déplacer, demandez gmail.modifier. Pour Microsoft Graph, la demande Mail.Read pour un accès en lecture seule ou Mail.ReadWrite pour un accès complet. Demandez toujours le minimum d'étendues dont votre application a réellement besoin - la vérification CASA de Google (requise pour les applications avec plus de 100 utilisateurs) examine attentivement la justification des étendues, et un surdimensionnement peut retarder votre approbation.
    8
    Existe-t-il un niveau d'API de synchronisation d'e-mails gratuit ?
    +
    Oui. Unipile propose un niveau API e-mail gratuit cela donne accès aux trois fournisseurs (Gmail, Outlook, IMAP) sans carte de crédit requise. Le niveau gratuit convient au développement, aux tests et à la production précoce avec un petit nombre de comptes liés. Consultez la page de tarification Unipile ou la documentation de l'API d'e-mails gratuite pour connaître les limites actuelles.
    9
    Comment gérer les jetons OAuth expirés dans une API de synchronisation d'e-mails ?
    +
    Les jetons d'accès expirent (généralement 1 heure pour Google et Microsoft). Votre infrastructure de synchronisation doit détecter 401 Non autorisé réponses, utilisez le jeton d'actualisation stocké pour obtenir un nouveau jeton d'accès, et réessayez la requête échouée de manière transparente. Les jetons d'actualisation eux-mêmes peuvent être révoqués. Lorsque la révocation est détectée (grant_invalide (erreur), marquer le compte comme nécessitant une ré-autorisation et en informer l'utilisateur. Unipile gère automatiquement tout le cycle de vie des jetons pour les comptes liés.
    10
    IMAP IDLE est une commande du protocole IMAP qui permet aux clients de messagerie de rester connectés à un serveur de messagerie et de recevoir des notifications quasi instantanées lorsque de nouveaux messages arrivent, sans avoir à interroger le serveur régulièrement. Voici comment il permet la synchronisation en temps réel : 1. **Connexion persistante :** Lorsqu'un client de messagerie prend en charge IMAP IDLE, il établit une connexion IMAP persistante avec le serveur de messagerie. Au lieu de se déconnecter après chaque vérification, la connexion reste ouverte. 2. **Commande IDLE :** Le client envoie la commande `IDLE` au serveur. Cela indique au serveur que le client attend des notifications. 3. **Serveur en attente :** Le serveur maintient la connexion ouverte et surveille la boîte aux lettres du client. Dès qu'un nouveau message arrive, est marqué comme lu, supprimé, ou qu'un changement se produit dans la boîte aux lettres, le serveur envoie immédiatement une notification au client. 4. **Notification (உதவி) :** La notification typique envoyée par le serveur est `* OK [ALERT] ...` ou une notification de ce type. Le client reçoit alors cette notification. 5. **Mise à jour de l'interface :** En recevant cette notification, le client de messagerie sait qu'il y a une nouvelle activité et met à jour son interface utilisateur en conséquence (par exemple, en affichant un nouveau message dans la boîte de réception, en mettant à jour un compteur de messages non lus, etc.). 6. **Continuité :** Le client peut rester en mode `IDLE` tant qu'il le souhaite, le serveur le tenant informé de tout changement. Si la connexion est interrompue, le client essaiera de se reconnecter et de renvoyer la commande `IDLE`. En résumé, au lieu d'un modèle de "polling" où le client demande périodiquement au serveur s'il y a du nouveau, IMAP IDLE adopte un modèle de "push" où le serveur informe proactivement le client des changements dès qu'ils surviennent. Cela permet une expérience utilisateur plus fluide et quasi instantanée pour la gestion des e-mails.
    +
    IMAP IDLE (RFC 2177) est une commande qui met une session IMAP en mode push : au lieu que votre client interroge le serveur de manière répétée, le serveur envoie des notifications non sollicitées EXISTE notifications lors de l'arrivée de nouveaux messages. Cela permet une synchronisation quasi instantanée de la boîte de réception (latence inférieure à 1 seconde) sans requêtes constantes. Les connexions IDLE doivent être rafraîchies toutes les 29 minutes pour éviter les timeouts du serveur. IDLE fonctionne avec tout serveur IMAP qui le prend en charge, ce qui inclut la plupart des serveurs de messagerie modernes, y compris Exchange d'entreprise, Gmail via IMAP et Outlook via IMAP.
    fr_FRFR
    en_USEN es_ESES de_DEDE it_ITIT pt_BRBR nl_NLNL pl_PLPL tr_TRTR fr_FRFR