LinkedIn
Instagram
WhatsApp
Telegram
Google Agenda
Rejoindre la communauté SlackEmail API de synchronisation: Comment fonctionne la synchronisation des emails 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'emails, avec webhooks, flux OAuth et accès complet aux dossiers inclus.
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']
});
Qu'est-ce qu'une API de synchronisation des emails ?
Un API de synchronisation d'emails 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'emails 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'emails 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'emails IA ou tout SaaS nécessitant des données de boîte de réception en direct, une API de synchronisation d'emails est la base. Pour l'envoi d'emails 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 Email ou notre dédié synchronisation vs transactionnel comparaison.
Synchronisation d'emails et envoi d'emails : pourquoi la distinction est importante
Les développeurs confondent souvent les API de synchronisation d'emails avec les API Email transactionnels. Elles servent des objectifs opposés. Choisir la mauvaise catégorie peut retarder votre architecture de plusieurs semaines.
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.
Utilisé par : CRM, outils d'engagement commercial, assistants d'emails IA, centres d'assistance, archivage d'emails, analyses de boîte de réception.
Envoie des emails 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.
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.
Qui a besoin d'une API de synchronisation d'emails ?
Tout produit SaaS qui a besoin d'afficher, d'analyser ou d'agir sur l'email entrant d'un utilisateur s'appuie sur une API de synchronisation d'emails. Voici les cinq cas d'utilisation les plus courants que nous rencontrons en production.
Enregistrez automatiquement chaque email entrant et sortant sur le bon enregistrement de contact. Les commerciaux cessent de copier-coller des emails ; 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 EmailSuivez 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'emails 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 email par programmeAlimentez un flux d'emails 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'emails en temps réel est obligatoire.
Lire les emails par programmeConvertissez automatiquement les emails 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 EmailCapturez chaque email entrant et sortant pour des raisons de conformité, de découverte légale ou d'analyse. Une API de synchronisation d'emails vous permet de construire une archive interrogeable de toutes les communications d'entreprise sans toucher directement au serveur de messagerie.
Niveau gratuit d'API EmailAnalyser le volume des emails, 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 EmailComment fonctionne la synchronisation des emails : OAuth, Delta Sync et Webhooks
Une API de synchronisation d'emails 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.
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.
Lors de la première synchronisation, l'API de synchronisation d'emails 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.
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.
Les jetons d'accès expirent. Votre infrastructure de synchronisation d'emails 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.
Le sondage sur un calendrier introduit de la latence : un sondage de 30 secondes signifie que les emails 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 emails 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'emails unifiée (comme Unipile) les normalise en un seul événement webhook - email.nouveau - livré à votre point de terminaison quel que soit le fournisseur.
API de synchronisation native des emails : 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'emails multi-fournisseurs à partir de zéro prend des mois, et non des jours.
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'emails pour plus.
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', [])
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.
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']
};
}
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.
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);
});
});
});Couverture des fonctionnalités de l'API Email par fournisseur
Une seule intégration Unipile vous donne accès à toutes les opérations d'email 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 email | |||
| Envoyer un email depuis le compte utilisateur | ✓ | ✓ | ✓ |
| Lire et lister les emails | ✓ | ✓ | ✓ |
| 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 | ✓ | ✓ | ✓ |
GmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPÉvitez les remplissages Gmail + Graph + IMAP. Une seule API de synchronisation d'emails couvre les trois.
L'API de synchronisation unifiée d'emails 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.
La complexité cachée de la synchronisation des emails à grande échelle
Construire une preuve de concept d'API de synchronisation d'emails 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.
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.
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.
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 emails" et "Boîte de réception".
Les pièces jointes des emails peuvent être volumineuses. La récupération et le stockage des pièces jointes pour chaque email 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 emails multiparti, le codage quoted-printable et les pièces jointes intégrées nécessitent chacun un traitement spécifique.
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.
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'emails 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.
3 Architectures de Synchronisation d'Emails Comparées
Les équipes qui développent des fonctionnalités de synchronisation d'emails é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.
Synchronisation des emails avec l'API de synchronisation d'emails unifiée d'Unipile
L'API de synchronisation d'emails 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.
Inscription à tableau de bord Unipile.. Le niveau gratuit de l'API Email 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.
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é.
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.
POSTez l'URL de votre point de terminaison à l'API webhook d'Unipile. Lorsqu'un nouvel email arrive dans un compte lié - qu'il s'agisse de Gmail, Outlook ou IMAP - Unipile livre un email 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'emails pour la référence complète de l'événement.
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 emails par programmation par exemple.
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;
}Arrêtez de reconstruire le même pipeline de synchronisation d'emails pour chaque fournisseur.
Connectez Gmail, Outlook et IMAP grâce à une seule API de synchronisation d'emails. 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.
Synchronisation d'emails 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'emails 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 emails arrivent. Connexion maintenue ouverte jusqu'à 29 min. | Moins de 1 an | Serveurs IMAP uniquement | 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 emails 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.
Sécurité et conformité pour les API de synchronisation des emails
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'emails doit aborder avant d'être mise en production.
Demandez uniquement les étendues dont votre application a besoin. Pour la synchronisation des emails 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.
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é.
Le contenu des emails 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'emails 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.
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.
Toujours vérifier la signature des charges utiles de webhook entrantes de votre API de synchronisation d'emails. Un webhook non signé ou mal vérifié peut être usurpé pour injecter de faux événements d'email 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.
Enregistrez chaque action que votre application effectue sur les données d'email 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 lors de la création d'une API de synchronisation d'emails
Voici les bogues et les erreurs d'architecture que nous rencontrons le plus souvent dans les implémentations d'API de synchronisation d'emails. Tous ces problèmes sont évitables grâce à de bons choix de conception dès le départ.
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.
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.
Le MIME brut est volumineux, difficile à interroger et coûteux à analyser à la lecture. Un seul email 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.
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 emails où ces en-têtes sont manquants.
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.
Pour les cas d'utilisation de CRM, vous avez besoin des emails 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 emails reçus ; vous avez également besoin ENVOYÉ. 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.
Questions fréquemment posées sur les API de synchronisation d'emails
Les questions les plus fréquentes des développeurs lors de la première implémentation d'une API de synchronisation d'emails.
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'emails unifiée normalise ces trois mécanismes différents derrière une interface cohérente.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.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.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.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.