LinkedIn
Instagram
WhatsApp
Telegramma
Calendario di Google
Partecipare alla comunità SlackEmail API di sincronizzazione: Come funziona la sincronizzazione delle e-mail per i prodotti SaaS
Crea funzionalità SaaS che sincronizzino le caselle di posta degli utenti in tempo reale. Connetti Gmail, Outlook e IMAP tramite una singola API di sincronizzazione email, con webhook, flussi OAuth e accesso completo alle cartelle inclusi.
const UnipileClient = require('@unipile/node-sdk');
const client = new UnipileClient({
dsn: process.env.UNIPILE_DSN,
token: process.env.UNIPILE_TOKEN
});
// Recupera le email sincronizzate dall'account collegato
const e-mail = await client.email.elencaEmail({
account_id: 'acc_gmail_xyz',
cartella: 'POSTA IN ARRIVO',
limite: 50
});
// Tempo reale: registra webhook
await client.webhook。.create({
url: 'https://yourapp.com/webhooks/email',
eventi: ['email.nuova', 'email.lettura']
});
Che cos'è un'API di sincronizzazione e-mail?
Un API di sincronizzazione email è un'interfaccia programmatica che consente alla tua applicazione di rispecchiare continuamente la casella di posta di un utente, leggendo nuovi messaggi, monitorando le modifiche di stato (letto/non letto, spostato, eliminato) e riflettendo la struttura delle cartelle, senza che l'utente esporti manualmente i dati. A differenza di un API di sola invio, un API di sincronizzazione email mantiene una replica live, bidirezionale della casella di posta all'interno del tuo prodotto.
A livello di protocollo, ogni provider espone il proprio primitivo di sincronizzazione: Gmail utilizza storia.elenco with a idStoria cursore, Microsoft Graph utilizza query delta su /messaggi/delta endpoint, e i server IMAP standard supportano INATTIVO comando per notifiche push. A API di sincronizzazione email unificata come Unipile astrae questi tre protocolli dietro un unico endpoint, così il tuo team scrive la logica di sincronizzazione una volta sola e la distribuisce a tutti i provider.
Se stai costruendo un CRM, uno strumento di sales engagement, un assistente email AI o qualsiasi SaaS che necessita di dati live dalla casella di posta, un'API di sincronizzazione email è il fondamento. Per l'invio di email transazionali (reset password, ricevute), questa è una categoria diversa - vedi la nostra guida completa all'API email.
Sincronizzazione Email vs Invio Email: Perché la Distinzione è Importante
Gli sviluppatori spesso confondono le API di sincronizzazione delle e-mail con le API di e-mail transazionali. Servono scopi opposti. Scegliere la categoria sbagliata può ritardare l'architettura di settimane.
Legge e rispecchia la casella di posta elettronica esistente di un utente nella tua applicazione. Richiede all'utente di autorizzare l'accesso al proprio account (credenziali OAuth o IMAP). La tua app diventa un lettore secondario della loro casella di posta.
Utilizzato da: CRM, strumenti di sales engagement, assistenti email AI, helpdesk, archiviazione email, analisi della casella di posta.
Invia email generate dal sistema dal tuo dominio. Non è necessaria alcuna autorizzazione da parte dell'utente. Ti autentichi come mittente (chiave API), non come utente. Esempi: SendGrid, Mailgun, Resend, Amazon SES.
Unipile NON rientra in questa categoria. Unipile è il lato di sincronizzazione, lettura e mirroring delle caselle di posta elettronica degli utenti tramite OAuth.
Chi ha bisogno di un'API di sincronizzazione email?
Qualsiasi prodotto SaaS che necessita di visualizzare, analizzare o agire sulle email in arrivo di un utente si basa su un'API di sincronizzazione email. Questi sono i cinque casi d'uso più comuni che vediamo in produzione.
Registra automaticamente ogni email in entrata e in uscita rispetto al record di contatto corretto. I rappresentanti di vendita smettono di copiare e incollare email; il CRM diventa il sistema di registrazione in tempo reale. Nessun inoltro manuale in Ccn richiesto.
Guida all'API EmailMonitora i tassi di risposta, rileva le risposte di assenza e attiva sequenze di follow-up in base agli eventi della casella di posta. Un'API di sincronizzazione delle email conferisce alle tue sequenze la consapevolezza in tempo reale di ciò che accade nella casella di posta del potenziale cliente.
Invio di email programmaticamenteAlimenta uno stream di email live a un agente LLM che crea bozze di risposte, categorizza i messaggi in arrivo, estrae gli elementi d'azione o instrada i ticket. L'agente necessita di un feed di sincronizzazione continuo, non di un'esportazione una tantum. Un'API di sincronizzazione email in tempo reale è obbligatoria.
Leggere email programmaticamenteConverti automaticamente le email dei clienti in ticket di supporto, includendo tutto il contesto della conversazione e gli allegati. Sincronizza lo stato del ticket quando l'agente risponde, in modo che la casella di posta del cliente rifletta la conversazione di risoluzione.
Confrontare i fornitori di API emailAcquisisci ogni email in entrata e in uscita per conformità, discovery legale o analisi. Un'API di sincronizzazione email ti consente di creare un archivio interrogabile di tutte le comunicazioni aziendali senza toccare direttamente il server di posta.
Livello gratuito API emailAnalizza il volume delle email, i tempi di risposta, i modelli di conversazione e il sentiment nei conti collegati di un team. I team di marketing, operazioni e finanza utilizzano le analisi della casella di posta per misurare la qualità della comunicazione e identificare i colli di bottiglia.
Guida completa all'API delle emailCome funziona la sincronizzazione delle e-mail: OAuth, Delta Sync e Webhook
Un'API di sincronizzazione email è più di un endpoint di lettura. È una pipeline stateful che autentica gli utenti, mantiene la freschezza dei token, tiene traccia dello stato della casella di posta e fornisce le modifiche quasi in tempo reale. Ecco cosa succede a ogni livello.
L'utente fa clic su "Connetti la tua casella di posta" nella tua app. Viene reindirizzato alla schermata di consenso di Google o Microsoft, dove approva gli ambiti richiesti dalla tua applicazione. Per Gmail ciò significa gmail.solodlettura o modifica gmail; per Outlook significa Posta.Leggi o Mail.ReadWrite. Dopo il consenso, la tua applicazione riceve un token di accesso (valido 1 ora per Google, 1 ora per Microsoft) e un token di aggiornamento (a lunga conservazione). Gli account IMAP utilizzano nome utente + password o OAuth a seconda della configurazione del provider.
Alla prima sincronizzazione, l'API di sincronizzazione delle email esegue un riempimento completo: recupera l'elenco delle cartelle (INBOX, Inviato, Bozze, etichette personalizzate) e recupera i messaggi recenti fino a una profondità di cronologia configurabile. Per Gmail, questo utilizza utenti.messaggi.elenca con paginazione. Per Microsoft Graph, usa Ottieni /me/messaggi. Per IMAP, emette un SELEZIONA POSTA IN ARRIVO seguito da un RECUPERA range. Lo snapshot fornisce al tuo database il suo stato di base, inclusi gli ID dei messaggi e raggruppamenti di thread.
Dopo lo snapshot iniziale, il controllo ripetuto della mailbox completa sprecherebbe la quota e rallenterebbe la tua app. La sincronizzazione Delta è la soluzione. Gmail fornisce un idStoria cursore: chiami Elenco cronologia utenti con l'ultima nota idStoria e ricevere solo le modifiche (nuovi messaggi, modifiche alle etichette, eliminazioni) da quel punto in poi. Microsoft Graph utilizza GET /me/messages/delta with a $token delta. IMAP utilizza UID recupera with a CAMBIATO DA modificatore (estensione CONDSTORE). Questo sincronizzazione delta Il pattern mantiene al minimo le chiamate API anche per caselle di posta ad alto volume.
I token di accesso scadono. La tua infrastruttura di sincronizzazione e-mail deve rilevare 401 Non autorizzato Per le risposte, utilizza il token di aggiornamento per ottenere un nuovo token di accesso da Google o Microsoft e riprova la richiesta fallita. Questo deve avvenire in modo trasparente, senza interrompere la sessione dell'utente. I token di aggiornamento stessi possono essere revocati - dall'utente, da una policy dell'amministratore, o dopo 6 mesi di inattività (Google) - quindi il tuo sistema deve rilevare la revoca e richiedere all'utente di riautorizzare.
Il polling su un programma introduce latenza: un polling di 30 secondi significa che le email possono essere obsolete fino a 30 secondi. Per le funzionalità di posta in arrivo in tempo reale, l'API di sincronizzazione delle email deve supportare notifiche push. Gmail utilizza Google Cloud Pub/Sub: si registra un argomento e Gmail pubblica una notifica ogni volta che idStoria avanzamenti. Microsoft Graph utilizza le notifiche di modifica su /me/mailFolders/inbox/messages risorsa. Un'API unificata di sincronizzazione e-mail (come Unipile) le normalizza in un singolo evento webhook - email.nuova - recapitato al tuo endpoint indipendentemente dal provider.
API di sincronizzazione email native: Gmail, Microsoft Graph e IMAP
Ciascun provider di posta elettronica espone un primitivo di sincronizzazione diverso. Comprendere le differenze spiega perché costruire un'API di sincronizzazione email multi-provider da zero richiede mesi, non giorni.
Gmail - history.list + Pub/Sub
Account Google Workspace e personali
Il modello di sincronizzazione di Gmail è costruito attorno al idStoria cursor. Dopo la sincronizzazione iniziale, ogni chiamata successiva a Elenco cronologia utenti restituisce solo le modifiche dall'ultima nota idStoria - nuovi messaggi, aggiunte di etichette, rimozioni di etichette ed eliminazioni.
Per push in tempo reale, Gmail richiede di impostare un argomento Google Cloud Pub/Sub e chiamare utenti.guarda per registrarlo. Gmail quindi pubblica una notifica (contenente un nuovo idStoria) al tuo argomento ogni volta che la casella di posta cambia. Il tuo worker si iscrive all'argomento e chiama storia.elenco per recuperare le modifiche effettive.
Limiti tariffari: 1 miliardo di unità di quota al giorno per progetto, con limiti per utente. utenti.messaggi.get costa 5 unità; Elenco cronologia utenti costa 2 unità. Per un'app multi-tenant, la gestione delle quote diventa un problema a tempo pieno. Vedi guida API email per saperne di più.
from googleapiclient.discovery import costruire
Sincronizzazione Delta # tramite cursore historyId
def recupera_modifiche(servizio, history_id)
risultato = servizio.utenti().cronologia().list(
ID utente='me',
startHistoryId=id_storia,
tipi di cronologia=[
'messaggioAggiunto',
'messaggioEliminato',
'etichettaAggiunta'
]
).eseguire()
return risultato.ottenere('storia', [])
Outlook / Microsoft 365 - Query delta di Graph
Outlook personale e Exchange Online / M365
Microsoft Graph usa query delta sul /me/messages/delta endpoint. La prima chiamata restituisce una pagina completa di messaggi più un @odata.deltaLink. Chiamate successive a quel delta link restituiscono solo messaggi modificati dall'ultima chiamata: elementi nuovi, modificati ed eliminati.
Per push in tempo reale, Microsoft Graph supporta le notifiche di modifica tramite webhook. Registri un abbonamento su /me/mailFolders/inbox/messages with a URL di notifica. Microsoft invia una POSTA al tuo URL quando i messaggi cambiano. Le sottoscrizioni devono essere rinnovate ogni 4230 minuti (circa 3 giorni) o scadono.
Nota: Questo copre sia gli account Outlook personali che Microsoft 365 / Exchange Online: utilizzano la stessa Graph API. Vedi il Guida all'integrazione delle e-mail con Microsoft Graph per i dettagli sulla registrazione dell'app e sul consenso dell'amministratore.
// Sincronizzazione delta di Microsoft Graph
async function scaricaMessaggiDelta(cliente, deltaLink) {
const url = deltaLink
|| '/me/messages/delta';
const res = await client
.api(url)
.seleziona('id,oggetto,da,dataRicezione')
.ottenere();
return {
messaggi: res.value,
nextDelta: res['@odata.deltaLink']
};
}
IMAP - comando IDLE + UID FETCH
Fallback universale per qualsiasi server di posta
IMAP (RFC 3501) precede le moderne API di sincronizzazione di decenni. Espone per cartella numeri di sequenza e UID. Per la sincronizzazione delta, il CONDSTORE estensione (RFC 7162) aggiunge un MODSEQ valore a ogni messaggio, permettendoti di recuperare solo i messaggi con un MODSEQ più alto del tuo ultimo valore conosciuto tramite UID FETCH * (FLAGS) (CHANGEDSINCE modseq).
Per push in tempo reale, IMAP supporta il INATTIVO comanda (RFC 2177). Il tuo client invia INATTIVO e il server spinge ESISTE o CANCELLARE risposte quando la cartella cambia - non è necessario alcun polling. La maggior parte dei server IMAP supporta IDLE; le connessioni devono essere aggiornate ogni 29 minuti per evitare timeout.
IMAP è fondamentale perché copre qualsiasi server di posta non gestito da Google o Microsoft: Exchange aziendali (on-premise), ProtonMail, Zoho, Fastmail e domini personalizzate. Vedi la Guida all'integrazione IMAP per una guida completa all'implementazione.
const Imap = require('imap');
const imap = new Imap({ host, porta: 993, tls: true });
imap.una volta('pronto', () => {
imap.Apri la scatola('POSTA IN ARRIVO', true, () => {
imap.on('posta', (numNuovo) => {
// IDLE push: nuova email arrivata
recuperaNuoviMessaggi(numNuovo);
});
});
});Copertura funzionalità API Email per provider
Una singola integrazione Unipile ti dà accesso a tutte le operazioni di posta elettronica tramite provider Gmail, Outlook e IMAP. Clicca sull'intestazione di qualsiasi provider per leggere la guida completa all'integrazione.
| Caratteristica | Gmail | Outlook / M365 | IMAP / SMTP |
|---|---|---|---|
| Autenticazione | |||
| OAuth2 (nessuna memorizzazione password) | ✓ | ✓ | Password dell'app |
| Flusso di autenticazione/consenso ospitato | ✓ | ✓ | ✓ |
| Rinnovo automatico del token | ✓ | ✓ | ✓ |
| Operazioni email | |||
| Invia email dall'account utente | ✓ | ✓ | ✓ |
| Leggi e elenca email | ✓ | ✓ | ✓ |
| Inviare con allegati | ✓ | ✓ | ✓ |
| Rispondi nella discussione esistente | ✓ | ✓ | ✓ |
| Gestione bozza | ✓ | ✓ | ✓ |
| Etichette / Cartelle | ✓Etichette | ✓Cartelle | ✓Cartelle |
| Limite di invio giornaliero (circa) | ~500 / giorno | ~10.000 al giorno | Dipendente dal server |
| Sincronizzazione ed Eventi | |||
| Webhook in tempo reale | ✓ | ✓ | ✓ |
| Sincronizzazione incrementale delta | ✓ | ✓ | ✓ |
| Raggruppamento di thread | ✓ | ✓ | ✓ |
| SOC 2 Tipo II / CASA Livello 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 / SMTPEvita il testo di avvio generico di Gmail + Graph + IMAP. Una singola API di sincronizzazione email copre tutti e tre.
L'API unificata di sincronizzazione email di Unipile si connette a Gmail, Outlook e IMAP tramite un singolo endpoint. Flussi OAuth, aggiornamento dei token, sincronizzazione delta e webhook: tutto gestito per te. Inizia gratuitamente, nessuna carta di credito richiesta.
La complessità nascosta della sincronizzazione delle email su larga scala
Costruire un'API di sincronizzazione email come prova di concetto richiede un fine settimana. Costruirne una affidabile in produzione con 1.000 account collegati richiede mesi. Ecco cosa nessuno ti dice in anticipo.
Gmail impone quote per utente (250 unità di quota/secondo) e limiti giornalieri per progetto. Microsoft Graph limita a 10.000 richieste ogni 10 minuti per app. Con 500 account collegati che sincronizzano tutti in programma, è necessario un limitatore di frequenza distribuito con backoff esponenziale, jitter e isolamento delle code per account. Un singolo picco da un account può esaurire la quota per tutti gli altri.
Ogni account collegato ha un token di accesso che scade. A 1.000 account, puoi aspettarti dozzine di refresh simultanei dei token durante le finestre di sincronizzazione più intense. Un singolo refresh fallito si propaga in cicli di sincronizzazione persi. Hai bisogno di un servizio dedicato al ciclo di vita dei token con logica di retry, rilevamento della revoca e una pipeline di avvisi per sollecitare gli utenti a ri-autorizzare quando i token di refresh scadono.
Gmail usa le etichette (un messaggio può avere più etichette contemporaneamente). Outlook usa cartelle (gerarchiche, con operazioni di spostamento). IMAP usa anche cartelle ma con spazi dei nomi che variano a seconda del fornitore del server. Normalizzarli in un modello di cartella coerente per la tua app richiede una logica di mapping specifica del provider. I casi limite includono cassette postali condivise, accesso delegato e la distinzione di Gmail tra "Tutte le email" e "Posta in arrivo".
Gli allegati delle email possono essere di grandi dimensioni. Il recupero e l'archiviazione degli allegati per ogni email sincronizzata su migliaia di account aumentano rapidamente sia i costi di larghezza di banda che di archiviazione. È necessaria una pipeline di streaming che scarichi gli allegati solo su richiesta, con archiviazione deduplicata e un livello CDN per servirli dal tuo prodotto. Il parsing MIME stesso introduce bug: email multipart, codifica quoted-printable e allegati inline richiedono ognuno una gestione specifica.
Thread di Gmail per ID del thread - un concetto lato server. IMAP non ha thread nativi; si ricostruiscono i thread utilizzando Riferimenti e In-Reply-To intestazioni (RFC 5322). Outlook ha ID conversazione. La normalizzazione dei thread tra i provider, in particolare per le risposte tra provider diversi, richiede euristiche di fallback basate sulla normalizzazione dell'oggetto e sulle catene di message-ID.
Le notifiche Pub/Sub di Gmail non sono garantite: i messaggi persi durante i tempi di inattività non vengono reinviati. Gli abbonamenti webhook di Microsoft Graph scadono e devono essere rinnovati. Se il tuo ricevitore webhook è inattivo durante una notifica push, perdi l'evento e ripieghi sul polling. Un'API di sincronizzazione e-mail di produzione necessita di un ciclo di riconciliazione che recuperi periodicamente gli eventi persi utilizzando il cursore di sincronizzazione delta, indipendentemente dalla disponibilità dei webhook.
3 Architetture di Sincronizzazione Email Confrontate
I team che sviluppano funzionalità di sincronizzazione delle email valutano tipicamente tre schemi di implementazione. Qui di seguito un confronto onesto di ciascuno, dall'impegno di realizzazione al costo di manutenzione continuativa.
Sincronizza le email con l'API di sincronizzazione unificata delle email di Unipile
L'API di sincronizzazione email di Unipile gestisce Gmail, Outlook e IMAP attraverso un'unica interfaccia unificata. Flussi OAuth, aggiornamento token, sincronizzazione delta e consegna webhook sono tutti gestiti per te: il tuo team implementa la funzionalità, non l'infrastruttura.
Registrati su dashboard.unipile.com. Il livello gratuito dell'API email ti dà accesso a tutti i provider senza bisogno di carta di credito. Ottieni immediatamente il tuo DSN (Data Source Name) e il token API.
Utilizza il flusso OAuth ospitato da Unipile per consentire al tuo utente di autorizzare l'accesso al proprio account Gmail o Outlook. Per IMAP, raccogli le loro credenziali e passale a POST /conti. Unipile gestisce il reindirizzamento OAuth, lo scambio di token e memorizza in modo sicuro il token di refresh.
Chiama GET /email con il account_id dell'account collegato. Unipile esegue la sincronizzazione differenziale contro Gmail storia.elenco, l'endpoint delta di Microsoft Graph, o IMAP CONDSTORE - ottieni sempre la stessa risposta JSON normalizzata indipendentemente dal provider.
Invia l'URL del tuo endpoint all'API webhook di Unipile. Quando arriva una nuova email in qualsiasi account collegato, che si tratti di Gmail, Outlook o IMAP, Unipile ne consegna una normalizzata email.nuova evento al tuo URL. Nessuna configurazione Pub/Sub, nessun rinnovo dell'abbonamento Grafana, nessuna gestione delle connessioni IDLE. Vedi la guida API email per riferimento completo dell'evento.
Chiama GET /email/{id} per recuperare il corpo completo del messaggio (HTML e testo normale), le intestazioni, le parti MIME e i riferimenti agli allegati. Gli allegati vengono forniti tramite URL firmati, quindi non dovrai mai archiviare dati MIME grezzi. Vedi leggere email programmaticamente per esempio.
const axios = require('axios');
const DSN = process.env.UNIPILE_DSN;
const TOKEN = process.env.UNIPILE_TOKEN;
const api = axios.create({
URL di base: `https://${DSN}/api/v1`,
intestazioni: { 'X-API-KEY': TOKEN }
});
// Passaggio 3 - Elenca le email sincronizzate
async function elencaEmail(idConto) {
const { dati } = await API.ottenere('/email', {
params: {
ID_account: accountID,
cartella: 'POSTA IN ARRIVO',
limite: 20
}
});
return articoli di dati;
}
// Passo 4 - Registra webhook
async function registraWebhook() {
await API.posta('/webhooks', {
url: 'https://yourapp.com/api/email-events',
eventi: ['email.nuova', 'email.aggiornato']
});
}
// Passo 5 - Ottieni il contenuto completo dell'email
async function OttieniEmail(emailId) {
const { dati } = await API.ottenere(`/emails/${emailId}`);
return dati;
}Smetti di ricostruire lo stesso pipeline di sincronizzazione e-mail per ogni provider.
Collega Gmail, Outlook e IMAP tramite un'unica API di sincronizzazione delle e-mail. Webhook in tempo reale, sincronizzazione delta e gestione dei token OAuth, tutto gestito. Il tuo team si concentra sul prodotto, non sull'infrastruttura.
Sincronizzazione Email in Tempo Reale: Webhook vs Polling vs IMAP IDLE
Scegliere il meccanismo in tempo reale sbagliato per la tua API di sincronizzazione delle e-mail aggiunge latenza, consuma quote o lascia la tua app alla cieca durante i downtime. Ecco un confronto diretto dei tre approcci.
| Approccio | Come funziona | Latenza | Il migliore per | Complessità |
|---|---|---|---|---|
| Webhook (push) | Il provider invia una richiesta HTTP POST al tuo endpoint quando una cassetta postale cambia. Gmail utilizza Pub/Sub; Microsoft Graph utilizza le notifiche di modifica. | Sotto i 5 anni | Gmail, Outlook, API unificate come Unipile | Medio - gestione dell'abbonamento richiesta |
| Sondaggio (pianificato) | Il tuo worker chiama l'API del provider su una pianificazione (ogni 30s, 1min, 5min) e recupera le modifiche utilizzando un cursore delta. | 30s-5min | Tutti i provider, configurazioni semplici | Basso - ma dispendioso in termini di quote su larga scala |
| IMAP IDLE (long-poll) | Il tuo client invia IDLE al server; il server invia notifiche EXISTS quando arrivano nuove e-mail. Connessione mantenuta aperta fino a 29 minuti. | Sotto 1 anno | Solo server IMAP | Alto - una connessione TCP per casella di posta |
Raccomandazione di produzione: Utilizza i webhook come tuo meccanismo primario in tempo reale e implementa un fallback di polling delta-sync (ogni 5 minuti) per recuperare gli eventi persi durante i periodi di inattività. Con l'API di sincronizzazione email di Unipile, entrambi sono configurati una sola volta: l'unificato email.nuova il webhook si attiva indipendentemente dal fatto che l'account sia Gmail, Outlook o IMAP e un ciclo di riconciliazione in background gestisce automaticamente gli eventi persi.
Sicurezza e conformità per le API di sincronizzazione e-mail
L'accesso alle caselle di posta degli utenti crea significative obbligazioni di sicurezza e normative. Ecco cosa la tua implementazione dell'API di sincronizzazione delle e-mail deve affrontare prima di andare in produzione.
Richiedi solo gli ambiti necessari alla tua applicazione. Per la sincronizzazione di email in sola lettura, richiedi gmail.solodlettura invece di modifica gmail. Per Microsoft Graph, richiedi Posta.Leggi invece di Mail.ReadWrite. La verifica CASA di Google (richiesta per app con oltre 100 utenti) esamina attentamente gli ambiti richiesti: un sovraccarico degli ambiti ritarda l'approvazione.
I token di aggiornamento OAuth sono credenziali di lunga durata che concedono l'accesso completo alla casella di posta. Devono essere archiviati crittografati a riposo (AES-256 minimo) e mai registrati. Ruota periodicamente le chiavi di crittografia del tuo token. Il compromesso di un token di aggiornamento equivale al compromesso di una password per l'account email connesso.
Il contenuto delle email sincronizzato dagli utenti UE è considerato dato personale ai sensi del GDPR. Hai bisogno di una base giuridica per il trattamento (tipicamente il consenso esplicito dell'utente tramite OAuth), un accordo di trattamento dei dati con il tuo fornitore di API di sincronizzazione email e una chiara politica di conservazione dei dati. Se la tua infrastruttura ha sede negli Stati Uniti, assicurati di avere SCC o un meccanismo di trasferimento equivalente per i dati UE.
Qualsiasi applicazione che utilizzi gli ambiti OAuth di Gmail con più di 100 utenti deve completare il processo di Google CASA (Cloud Application Security Assessment). Questa è una revisione della sicurezza della tua applicazione, che include codice, infrastruttura e giustificazione dell'ambito OAuth. Il processo dura 4-8 settimane. Inizia presto: il mancato superamento di CASA significa perdere l'accesso a Gmail per tutti gli utenti fino al superamento dell'esame.
Verifica sempre la firma sui payload webhook in arrivo dalla tua API di sincronizzazione e-mail. Un webhook non firmato o verificato in modo errato può essere falsificato per inserire eventi e-mail fasulli nella tua applicazione. Unipile firma tutte le consegne webhook con HMAC-SHA256. Verifica la X-Unipile-Firma intestazione prima di elaborare qualsiasi evento.
Registra ogni azione che la tua applicazione esegue sui dati delle email sincronizzate: chi ha acceduto a quali messaggi, quando e cosa è stato fatto con i dati. I log di audit sono necessari per la conformità SOC 2 Type II e sono spesso la prima cosa che i clienti enterprise richiedono durante le revisioni di sicurezza. Conserva i log per almeno 90 giorni, idealmente 1 anno.
Errori comuni durante la creazione di un'API di sincronizzazione e-mail
Questi sono i bug e gli errori architetturali che riscontriamo più spesso nelle implementazioni di API di sincronizzazione e-mail. Tutti sono prevenibili con scelte progettuali corrette fin dall'inizio.
Quando un token di aggiornamento scade o viene revocato, un'implementazione ingenua genera un errore e interrompe la sincronizzazione, silenziosamente. L'utente non sa che la sua casella di posta ha smesso di sincronizzarsi finché non nota dati obsoleti. Correggere: implementa uno strato di rilevamento della revoca che cattura concessione_non_valida errori, contrassegna l'account collegato come richiedente una ri-autorizzazione e notifica l'utente tramite il sistema di notifiche del tuo prodotto.
Interrogare ogni 10 secondi su 200 account collegati consuma la quota per progetto di Gmail nel giro di poche ore. Microsoft Graph inizia a restituire 429 Troppe richieste. Il risultato sono errori di sincronizzazione silenziosi per tutti gli account, non solo per quelli che hanno innescato il throttling. Correggere: usa webhook come meccanismo primario con un fallback di polling di 5 minuti e implementa la limitazione della frequenza per account con backoff esponenziale su tutto 429 risposte.
Il MIME grezzo è voluminoso, difficile da interrogare e costoso da analizzare in lettura. Una singola email con allegati può essere di centinaia di kilobyte. Correggere: Analizza il formato MIME al momento dell'acquisizione: estrai separatamente il corpo HTML, il testo in chiaro (come alternativa), le intestazioni e i metadati degli allegati. Archivia i file binari degli allegati in un sistema di archiviazione a oggetti (S3 o equivalente), non nel database principale. Questo accorgimento da solo riduce i costi di archiviazione del 60-80% per le caselle di posta aziendali standard.
Gmail ID del thread funziona solo all'interno di Gmail. Se la tua app mostra una conversazione che si estende su un account Gmail e un account Outlook (ad esempio, una risposta inviata da una casella di posta diversa), gli ID di conversazione nativi sono inutili. Correggere: costruisci un motore di threading cross-provider basato su ID messaggio, In-Reply-To, e Riferimenti intestazioni. Normalizza le righe dell'oggetto (rimuovi i prefissi Re:/Fwd:) come riserva per le email prive di queste intestazioni.
Il sync Delta si affida a un cursore memorizzato: quello di Gmail idStoria, Microsoft Graph deltaLink, IMAP MODSEQ. Se il tuo worker di sincronizzazione si riavvia e il cursore è memorizzato solo in memoria, perdi la tua posizione nel flusso delle modifiche. La successiva sincronizzazione ricomincia da zero, duplicando tutti i messaggi storici o mancando il salto. Correggere: salva il cursore nel tuo database dopo ogni ciclo di sincronizzazione riuscito, in modo atomico con l'ultima batch di modifiche elaborate.
Per i casi d'uso del CRM, sono necessarie sia le email in entrata (ricevute) che quelle in uscita (inviate) per costruire una cronologia completa delle comunicazioni. L'etichetta INBOX di Gmail copre solo la posta ricevuta; è necessario anche SPEDITO. Microsoft Graph richiede l'interrogazione Elementi inviati cartella separatamente. IMAP richiede la selezione della Inviato cartella esplicitamente. Correggere: sincronizza tutte le cartelle pertinenti durante la configurazione dell'account, non solo la POSTA IN ARRIVO, e mappa i nomi delle cartelle specifici del provider a tipi normalizzati nel tuo modello dati.
Domande frequenti sulle API di sincronizzazione delle e-mail
Le domande più comuni che i sviluppatori pongono quando implementano per la prima volta un'API di sincronizzazione email.
idStoria cursore con il Elenco cronologia utenti endpoint. Microsoft Graph utilizza un deltaLink restituito da /messaggi/delta endpoint. L'IMAP utilizza il MODSEQ valore dall'estensione CONDSTORE. Un'API di sincronizzazione unificata per le email normalizza questi tre meccanismi distinti dietro un'interfaccia coerente.GET /email con il account_id recuperare messaggi sincronizzati e registrare un endpoint webhook per ricevere in tempo reale email.nuova eventi. Unipile gestisce automaticamente OAuth, aggiornamento dei token, sincronizzazione delta e consegna dei webhook.gmail.solodlettura. Se devi contrassegnare i messaggi come letti o spostarli, richiedi modifica gmail. Per Microsoft Graph, richiedi Posta.Leggi per accesso in sola lettura o Mail.ReadWrite per l'accesso completo. Richiedi sempre gli ambiti minimi di cui la tua applicazione ha effettivamente bisogno: la verifica CASA di Google (richiesta per app con oltre 100 utenti) esamina attentamente la giustificazione degli ambiti e un ambito eccessivo può ritardare la tua approvazione.401 Non autorizzato risposte, utilizzare il token di aggiornamento memorizzato per ottenere un nuovo token di accesso e ritentare la richiesta fallita in modo trasparente. Anche i token di aggiornamento possono essere revocati. Quando viene rilevata la revoca (concessione_non_valida (errore), contrassegnare l'account come da ri-autorizzare e notificare l'utente. Unipile gestisce automaticamente tutta la gestione del ciclo di vita dei token per gli account collegati.ESISTE notifiche quando arrivano nuovi messaggi. Questo permette una sincronizzazione della casella di posta quasi in tempo reale (con latenza inferiore a 1 secondo) senza richieste costanti. Le connessioni IDLE devono essere aggiornate ogni 29 minuti per evitare timeout del server. IDLE funziona con qualsiasi server IMAP che lo supporti, inclusa la maggior parte dei server di posta moderni, tra cui Exchange aziendali, Gmail via IMAP e Outlook via IMAP.
IT 
EN 
FR 
ES 
DE 
BR 
NL 
PL 
TR