LinkedIn
Instagram
WhatsApp
Telegramma
Calendario di Google
Partecipare alla comunità SlackCos'è effettivamente una connessione al server IMAP
Una connessione server IMAP è una sessione TCP persistente tra un client di posta elettronica e un server di posta che utilizza il protocollo IMAP (Internet Message Access Protocol) per sincronizzare, recuperare e gestire messaggi di posta elettronica memorizzati in remoto, senza scaricarli o eliminarli dal server.
A differenza del POP3, che è stato progettato per scaricare i messaggi localmente e opzionalmente eliminarli dal server, IMAP è stato creato per la sincronizzazione. Ogni lettura, contrassegno, spostamento o eliminazione che si esegue localmente viene riflessa sul server, e quindi su ogni dispositivo connesso alla stessa casella di posta. È per questo che IMAP è diventato il protocollo de facto per i client di posta elettronica moderni.
A livello di rete, una connessione a un server IMAP apre un socket TCP verso un server di posta (tipicamente la porta 993 per SSL/TLS o la porta 143 per STARTTLS), esegue un handshake TLS, autentica l'utente (tramite password, password dell'app o OAuth 2.0 XOAUTH2), quindi entra in una macchina a stati: Non autenticato, Autenticato, Selezionato (all'interno di una cartella della casella di posta), oppure Esci. La maggior parte dei comandi utili - FETCH, SEARCH, STORE, COPY, EXPUNGE - funzionano solo nello stato Selected.
Per gli sviluppatori che creano integrazioni di posta elettronica, una connessione al server IMAP è il blocco di costruzione di livello più basso. La si stabilisce, la si autentica, si SELEZIONA una casella di posta, quindi si interroga o si usa la modalità IDLE per i nuovi messaggi. Questa guida copre ogni passaggio: l'host e la porta corretti per ogni provider, il metodo di autenticazione corretto nel 2026 (OAuth è sempre più obbligatorio) e un riferimento completo per la risoluzione dei problemi per le modalità di errore più comuni.
Porte IMAP spiegate: 143, 993 e quando STARTTLS va bene
Ci sono esattamente due porte IMAP in uso attivo: 993 (TLS implicito, lo standard moderno) e 143 (Aggiornamento STARTTLS o testo normale, quest'ultimo non più consentito dalla maggior parte dei server). Conoscere la differenza è importante perché usare la porta sbagliata è una delle cause più comuni di errori di connessione quando si crea un'integrazione IMAP.
Il client si connette e avvia immediatamente una handshake TLS prima che venga scambiato qualsiasi dato IMAP. Tutto il traffico è crittografato fin dal primo byte. Questo è il comportamento predefinito corretto per qualsiasi nuova integrazione.
Il client si connette in testo normale, quindi emette un STARTTLS Comando per aggiornare a TLS. La maggior parte dei server moderni richiede questo aggiornamento e rifiuta completamente le sessioni in chiaro.
Raccomandazione 2026: usa sempre la porta 993 con SSL_CONTEXT (TLS implicito). Se stai costruendo contro un server IMAP aziendale che espone solo la porta 143, abilita STARTTLS e verifica il certificato del server. Non connetterti mai a un server IMAP in testo in chiaro in produzione: le credenziali viaggiano in chiaro e la maggior parte dei provider rifiuta tali connessioni del tutto.
Una breve nota su RFC 9051 (IMAP4rev2), pubblicato nell'agosto 2021 come successore di RFC 3501. IMAP4rev2 richiede formalmente TLS per qualsiasi connessione che trasporti credenziali, sconsiglia i meccanismi di autenticazione basati su MD5 e rimuove il ELENCO-ESTESO incompatibilità che causavano bug sottili nei client meno recenti. La maggior parte dei principali provider cloud (Gmail, Outlook) è stata di fatto compatibile con IMAP4rev2 per anni, anche prima che la RFC fosse finalizzata. Ai fini pratici, usa la porta 993 + TLS e sarai conforme alla RFC 9051 per impostazione predefinita.
Tabella impostazioni host e porta - Gmail, Outlook, Yahoo, iCloud, Zoho, Fastmail, AOL, ProtonMail Bridge
La tabella sottostante elenca le impostazioni corrette di connessione IMAP per i provider di posta elettronica più diffusi. Tutti i valori sono stati verificati sulla documentazione ufficiale di ogni provider a maggio 2026. Utilizza questo come riferimento rapido quando configuri un client IMAP o crei un Integrazione API IMAP.
| Fornitore | Host IMAP | Porto | Crittografia | OAuth 2.0 (XOAUTH2) | Appunti |
|---|---|---|---|---|---|
 Gmail |
imap.gmail.com | 993 | SSL/TLS | Sì (necessario per le nuove app) |
Le app password funzionano, ma OAuth è fortemente raccomandato. Abilita prima IMAP nelle impostazioni di Gmail. |
 Outlook / Microsoft 365 |
outlook.office365.com | 993 | SSL/TLS | Sì (Basic Auth deprecato Dicembre 2026) |
Basic Auth fine ciclo dicembre 2026 per tutti gli tenant. Esegui la migrazione a OAuth ora. |
Yahoo Mail |
imap.mail.yahoo.com | 993 | SSL/TLS | Sì |
È richiesta una password per le app se il 2FA è abilitato. OAuth tramite il portale sviluppatori di Yahoo. |
Posta di iCloud |
imap.mail.me.com | 993 | SSL/TLS | No (solo password specifica dell'app) |
Apple richiede una password specifica per l'app da appleid.apple.com. Nessun supporto OAuth XOAUTH2. |
Zoho Mail |
imap.zoho.com | 993 | SSL/TLS | Sì |
OAuth tramite API di Zoho Accounts. IMAP deve essere abilitato per ogni mailbox nelle impostazioni di Zoho Mail. |
Fastmail |
imap.fastmail.com | 993 | SSL/TLS | Sì (preferito JMAP) |
Fastmail supporta nativamente JMAP (più veloce di IMAP) ma IMAP è pienamente supportato. Password per le app disponibili. |
Posta AOL |
imap.aol.com | 993 | SSL/TLS | Sì |
Ora parte di Yahoo Inc. È richiesta una password per le app se è abilitata l'autenticazione a due fattori. OAuth tramite il portale sviluppatori di Yahoo. |
ProtonMail Bridge |
127.0.0.1 | 1143 | STARTTLS | No (autenticazione token bridge) |
ProtonMail Bridge viene eseguito in locale ed espone un server IMAP locale. Non adatto per integrazioni lato server. |
IMAP generico |
your-mail-server.com | 993 / 143 | SSL/TLS STARTTLS | Varia (controllare configurazione server) |
Dovecot, Postfix, Zimbra, Courier. Controlla la risposta CAPABILITY del tuo server per i meccanismi di autenticazione supportati. |
Gmail
Outlook / Microsoft 365
Nota su ProtonMail: l'architettura Bridge significa che le connessioni IMAP di ProtonMail sono utilizzabili solo per configurazioni desktop a utente singolo. Per integrazioni multi-account o lato server, ProtonMail è di fatto non supportato tramite IMAP standard. Per Gmail e Outlook su larga scala, consulta le nostre guide dedicate su OAuth per le API di posta elettronica e Microsoft Graph API Posta elettronica.
Passo dopo passo: apertura di una connessione raw al server IMAP
Di seguito sono riportati esempi minimali e funzionanti su come aprire una connessione a un server IMAP autenticato usando i moduli integrati di Python imaplib e Node.js con imapflow. Entrambi gli esempi si connettono a Gmail sulla porta 993 utilizzando l'autenticazione tramite password dell'app. Per OAuth XOAUTH2, consultare la sezione H2 #7 qui sotto.
import imaplib
import ssl
Impostazioni del server IMAP #
IMAP_HOST = "imap.gmail.com"
IMAP_PORTA = 993
NOME UTENTE = "you@gmail.com"
PASSWORD = "tua-password-app" La password dell'app #, non quella del tuo account
# Creazione del contesto SSL (verifica dei certificati)
contesto = sicurezza.crea_contesto_predefinito()
#: apri una connessione SSL sulla porta 993
con imaplib.IMAP4_SSL(IMAP_HOST, IMAP_PORT, contesto_ssl=contesto come imap:
# Autenticazione
imap.Accedi(NOME UTENTE, PASSWORD)
# Seleziona la posta in arrivo (restituisce il numero di messaggi)
stato, dati = imap.seleziona("Posta in arrivo")
print(La casella di posta ha {data[0].decode()} messaggi")
# Alla ricerca di messaggi nascosti
stato, msg_ids = imap.ricerca(Nessuno, "INVISIBILE")
print(Non visto: {msg_ids[0].decode()}")
# Disconnessione (la connessione si chiude al termine del blocco "with")// instaura imapflow
import { ImapFlow } from 'imapflow';
const client = new ImapFlow({
ospite: 'imap.gmail.com',
porto 993,
sicuro true, // SSL/TLS sulla porta 993
auth: {
Scusi. 'you@gmail.com',
pass 'la-tua-password-dell-app'
},
logger: falso
});
await cliente.connettere();
// Blocca la casella POSTA IN ARRIVO per accesso esclusivo
lascia bloccare = await cliente.getMailboxLock('POSTA IN ARRIVO');
tentare {
// Recupera le ultime 5 chat (solo intestazioni)
per await (lascia messaggio di cliente.fetch('1:5', busta: true })) {
console.log(msg.envelope.oggetto);
}
} finalmente {
lucchetto.rilascio();
}
await cliente.disconnettersi();L'esempio Python utilizza IMAP4_SSL - il wrapper SSL di livello superiore che gestisce automaticamente l'handshake TLS. Evita di usare IMAP4 + manuale starttls() per i cloud provider poiché aggiunge complessità senza alcun beneficio. Per Node.js, imapflow è la scelta moderna basata su Promise (la vecchia node-imap la libreria non è più mantenuta dal 2024 e non supporta XOAUTH2).
Entrambi gli esempi utilizzano password per app, che sono il tipo di credenziale più semplice per test rapidi. Per sistemi di produzione che gestiscono più utenti, avrai bisogno di OAuth 2.0, consulta la sezione XOAUTH2 di seguito. Per una soluzione completa pronta per la produzione senza gestire connessioni IMAP grezze, consulta Guida per sviluppatori API IMAP.
Salta il boilerplate IMAP. Unipile ti consente di leggere, inviare e sincronizzare Gmail, Outlook e IMAP in una singola REST API, senza necessità di gestione delle connessioni.
Salta il codice boilerplate di IMAP - Costruiscilo con UnipileAutenticazione: password, password dell'app e OAuth 2.0 (XOAUTH2)
Una connessione al server IMAP richiede l'autenticazione dopo l'handshake TLS. Esistono tre metodi di autenticazione in uso oggi, ciascuno con un diverso profilo di sicurezza, livello di complessità e compatibilità con i provider cloud nel 2026.
Il meccanismo originale IMAP AUTH PLAIN / LOGIN. Inviate l'indirizzo email dell'account e la password dell'account direttamente al server IMAP. Semplice da implementare ma sempre più bloccato dai provider cloud per motivi di sicurezza.
Deprecato per il cloudUn token di 16 caratteri generato dal provider (Gmail, Yahoo, iCloud) che sostituisce la password reale dell'account. Funziona con lo stesso comando IMAP LOGIN dell'autenticazione di base, ma è limitato in ambito e può essere revocato in modo indipendente. Richiesto quando è abilitato il 2FA.
Accettabile per uso personaleL'utente autorizza la tua app tramite una schermata di consenso. La tua app riceve un token di accesso (di breve durata, tipicamente 1 ora) che codifichi in base64 e passi al comando IMAP AUTHENTICATE XOAUTH2. I token vengono aggiornati con un token di aggiornamento di lunga durata. L'unico metodo valido per app di produzione multiutente.
Richiesto per la produzioneQuando usare quale: Utilizza password per app durante lo sviluppo locale e per strumenti personali. Usa OAuth 2.0 XOAUTH2 per qualsiasi integrazione multi-utente: è l'unico metodo che scala, perché non memorizzi mai le password degli utenti e ogni token può essere revocato senza cambiare la password dell'utente. Per Gmail, Google ha progressivamente limitato l'autenticazione di base per "app meno sicure" dal 2022. Per Microsoft/Outlook, l'obsolescenza dell'autenticazione di base è prevista per dicembre 2026 in tutti gli tenant (vedi la sezione successiva).
Per un approfondimento sui flussi OAuth – inclusi lo scambio di token, la logica di refresh e gli scope – consulta la nostra guida su OAuth per le API di posta elettronica. Per la configurazione di OAuth specifica per Microsoft, vedere Microsoft Graph OAuth per Outlook.
Il problema del 2026: deprecazione di Microsoft Basic Auth (dicembre 2026)
Se la tua integrazione IMAP si connette agli account Microsoft 365 o Outlook utilizzando direttamente nome utente e password, sei in countdown. Microsoft ha annunciato la data di fine vita definitiva per l'autenticazione di base su IMAP, POP3 e SMTP per tutti gli tenant.
Secondo Microsoft Learn e il Annuncio di Microsoft Community Hub, Exchange Online disabiliterà completamente l'autenticazione di base per IMAP, POP3 e SMTP nel dicembre 2026 su tutti gli inquilini, inclusi quelli con esenzioni esistenti. Qualsiasi client IMAP o integrazione lato server che utilizzi ancora l'autenticazione username/password smetterà di funzionare. Non sono disponibili ulteriori estensioni.
Azioni da intraprendere per migrare prima della scadenza
Cerca nel tuo codebase le connessioni IMAP che utilizzano accesso(nomeutente, password) o AUTENTICAZIONE PLAIN. Controlla i log di accesso di Microsoft Entra ID (precedentemente Azure AD) per l'attività di autenticazione di base IMAP.
Crea una registrazione di un'app su portal.azure.com con IMAP.AccessAsUser.All (delegato) o IMAP.AccessoComeApp (applicazione) permesso. Vedi Microsoft Graph OAuth per Outlook per una guida passo passo.
Utilizza MSAL (Microsoft Authentication Library) per acquisire i token di accesso. Implementa la logica di rinnovo dei token: i token di Microsoft scadono dopo 1 ora ed è necessario un flusso di refresh token per mantenere sessioni IMAP a lunga durata senza autenticazione utente ripetuta.
Sostituisci l'IMAP ACCESSO comando con AUTENTICAZIONE XOAUTH2 utilizzando una stringa token codificata in base64. Vedi l'esempio di codice completo nella sezione XOAUTH2 qui sotto.
Microsoft fornisce un modo per disabilitare Basic Auth in anticipo su base per tenant - utilizza questo per testare il tuo flusso OAuth prima del blocco forzato di dicembre 2026, in modo da non dover risolvere problemi di produzione sotto pressione.
Se gestisci connessioni IMAP per più utenti di Microsoft 365 - uno scenario comune per strumenti di CRM, ATS o automazione delle vendite - la complessità della migrazione aumenta rapidamente. Devi gestire i flussi di consenso OAuth per ogni utente, archiviare e aggiornare i token in modo sicuro e affrontare le policy di accesso condizionale che potrebbero bloccare la tua app in alcuni tenant. Questo è uno dei motivi principali per cui gli sviluppatori scelgono un'API IMAP gestita invece di mantenere collegamenti diretti da soli.
La scadenza per l'autenticazione di base di Microsoft si avvicina. Crea oggi stesso un flusso OAuth a prova di futuro con l'API unificata per email di Unipile: gestiamo per te il refresh dei token, l'autenticazione multi-tenant e XOAUTH2.
Costruisci un flusso OAuth a prova di futuroCollegamento tramite OAuth XOAUTH2
XOAUTH2 è il meccanismo SASL che consente di autenticare una connessione al server IMAP utilizzando un token di accesso OAuth 2.0 anziché una password. Il token viene ottenuto tramite il flusso standard di codice di autorizzazione OAuth (o credenziali client per account di servizio), codificato in base64 in un formato specifico e passato al AUTENTICAZIONE XOAUTH2 Comando IMAP.
Gmail (Google)Microsoft 365import imaplib, base64, json
from google.oauth2.credenziali import Credenziali
from google.auth.transport.requests import Richiesta
# Carica le credenziali OAuth ottenute in precedenza
# (dal flusso google-auth-oauthlib)
crediti = Credenziali(
gettone=TOKEN_DI_ACCESSO,
token_di_aggiornamento=REFRESH_TOKEN,
uri_del_token="https://oauth2.googleapis.com/token",
ID cliente=CLIENT_ID,
segreto del cliente=SEGRETO_CLIENTE,
ambiti=["https://mail.google.com/"]
)
# Aggiorna il token se è scaduto
se creds.scadute:
credenziali.ricaricare(Richiesta())
# Crea stringa XOAUTH2: "user={email}\x01auth=Bearer {token}\x01\x01""
indirizzo email utente = "user@gmail.com"
auth_string = f"utente={user_email}\x01auth=Bearer {creds.token}\x01\x01"
auth_b64 = base64.b64encode(stringa_auth.codificare()).decode()
#: apri una connessione IMAP ed esegui l'autenticazione
con imaplib.IMAP4_SSL("imap.gmail.com", 993) come imap:
imap.autenticare("XOAUTH2", lambda _: auth_b64)
imap.seleziona("Posta in arrivo")
print(""Connesso tramite XOAUTH2"")import imaplib, base64
from msal import ApplicazioneClientaRiservata
# Acquisizione del token tramite MSAL (flusso con credenziali client per account di servizio)
# Per l'accesso delegato dall'utente, utilizzare invece il flusso con codice di autenticazione
app = ApplicazioneClientaRiservata(
ID cliente=CLIENT_ID,
autorità=https://login.microsoftonline.com/{TENANT_ID}",
credenziali_del_client=SEGRETO_CLIENT
)
risultato = app.acquisisci_token_per_client(
ambiti=["https://outlook.office365.com/.default"]
)
token_accesso = risultato["token_di_accesso"]
# Crea stringa XOAUTH2
indirizzo email utente = "user@company.com"
auth_string = f"user={user_email}\x01auth=Bearer {access_token}\x01\x01"
auth_b64 = base64.b64encode(stringa_auth.codificare()).decode()
#: Connettiti a Outlook tramite IMAP
con imaplib.IMAP4_SSL("outlook.office365.com", 993) come imap:
imap.autenticare("XOAUTH2", lambda _: auth_b64)
imap.seleziona("Posta in arrivo")
print("Connesso tramite XOAUTH2 a Outlook")Differenze chiave tra Gmail e Microsoft XOAUTH2: Gmail richiede il https://mail.google.com/ ambito (accesso completo a Gmail). Microsoft richiede IMAP.AccessAsUser.All (delegato) o IMAP.AccessoComeApp (applicazione). Il formato della stringa XOAUTH2 in base64 è identico per entrambi i provider: email=email\x01auth=Bearer {token}\x01\x01.
Un dettaglio implementativo cruciale: i token scadono dopo 3600 secondi. Una sessione IMAP IDLE di lunga durata (vedi la sezione successiva) riceverà un errore di autenticazione quando il token scade a metà sessione. È necessario gestire questo AUTENTICAZIONE FALLITA errore, aggiornare il token utilizzando il token di aggiornamento, quindi ristabilire la connessione IMAP. Questo ciclo di tentativi non è banale ed è una delle ragioni principali per cui i team scelgono un'API gestita come Guida API email unificata invece delle connessioni IMAP grezze.
Per una guida completa alla configurazione di OAuth per Microsoft, comprese le considerazioni sulle policy di accesso condizionale, consulta la nostra Microsoft Graph OAuth per Outlook guida.
OAuth XOAUTH2 in 10 righe. XOAUTH2 è un meccanismo di autenticazione basato su token per i servizi che utilizzano OAuth 2.0. Permette di autenticarsi a un server di posta elettronica (come Gmail, Office 365) senza fornire la password dell'utente. Invece della password, viene utilizzato un token di accesso OAuth 2.0. Il client ottiene questo token tramite un flusso OAuth 2.0 (ad esempio, Authorization Code Grant). Il client invia il token di accesso al server di posta elettronica nell'header di autenticazione. La sintassi tipica nell'header `Authorization` è: `Authorization: XOAUTH2 `. La stringa codificata contiene l'email dell'utente, il tipo di autenticazione (XOAUTH2) e il token di accesso. Questo aumenta la sicurezza poiché il token può avere una scadenza e revocabile. È un metodo moderno e consigliato per l'accesso programmatico alle caselle di posta. Unipile gestisce automaticamente l'acquisizione, il refresh e la riautenticazione IMAP dei token. Tu ti concentri sulla lettura delle email, non sulla gestione della connessione.
Ecco come creare OAuth XOAUTH2 in 10 righe con Unipile: 1. `const token = await page.evaluate(() => {` 2. ` const credentials = acquireUnipileAuthCredentials();` 3. ` return credentials.accessToken;` 4. `});` 5. `const oauth2 = {` 6. ` xoauth2: {` 7. ` user: 'your_email@example.com',` 8. ` accessToken: token` 9. ` }` 10. `};`IDLE, polling e notifiche push: mantenere viva la connessione IMAP
Una volta stabilita una connessione autenticata al server IMAP, la sfida successiva è rilevare nuovi messaggi in modo efficiente senza sovraccaricare il server con richieste continue. Esistono tre schemi attualmente in uso, ognuno con latenza, complessità e requisiti infrastrutturali diversi.
| Metodo | Come funziona | Latenza | Infrastrutture | Il migliore per | Valutazione |
|---|---|---|---|---|---|
| IMAP IDLE (RFC 2177) | Il client invia il comando IDLE; il server invia notifiche EXISTS/RECENT sulla connessione TCP aperta quando arriva una nuova email. Il client deve inviare DONE + reinviare IDLE ogni 29 minuti (timeout del server). | ~1-5 secondi | 1 connessione TCP persistente per casella di posta. Richiede un thread dedicato o un ciclo asincrono. | Strumenti per utente singolo, client desktop, monitoraggio a bassa latenza | Bene |
| Sondaggio (NOOP / CHECK) | Il client si riconnette periodicamente, invia SELECT + SEARCH UNSEEN per cercare nuovi messaggi, quindi si disconnette. Semplice e stateless. | Uguale all'intervallo di polling (tipicamente 1-15 minuti) | Senza stato. Funziona dietro NAT/firewall. Nessuna connessione persistente. | Elaborazione batch, latenza elevata accettabile, ambienti in cui le connessioni persistenti sono bloccate | Accettabile |
| Provider push (Gmail Pub/Sub, webhook di MS Graph) | Il provider invia una notifica HTTP al tuo endpoint webhook quando arriva una nuova e-mail. Nessuna connessione IMAP necessaria a riposo. Gmail utilizza Google Cloud Pub/Sub; Microsoft utilizza le notifiche di modifica di MS Graph. | Quasi in tempo reale(tipicamente inferiore a 1 secondo) | Richiede un endpoint HTTPS pubblico e una sottoscrizione Pub/Sub. Nessuna connessione IMAP persistente a riposo. | Sistemi di produzione multi-account su larga scala, architetture serverless | Il migliore su larga scala |
IDLE è la scelta giusta per integrazioni semplici dove si controlla un piccolo numero di account. I principali intoppi: è necessario riconnettersi prima del timeout di inattività di 29 minuti (Gmail lo applica rigorosamente) e sono necessarie connessioni IMAP separate per ogni casella di posta, il che diventa costoso con centinaia o migliaia di account.
Notifiche push del provider sono l'architettura corretta per sistemi multiaccount in produzione. L'integrazione Pub/Sub di Gmail e i webhook di sottoscrizione di Microsoft Graph offrono entrambi notifiche quasi in tempo reale senza richiedere una connessione IMAP persistente per ogni account. Il compromesso: è comunque necessario aprire una connessione IMAP per recuperare il corpo del messaggio effettivo quando si viene notificati, il che significa che il codice della connessione IMAP è ancora necessario, solo che non viene mantenuto aperto continuamente. Per leggere messaggi di posta elettronica tramite API, consultare la nostra guida su leggere email tramite API e invio di email tramite API.
Matrice di risoluzione dei problemi: timeout, errori di handshake, errori di autenticazione, limiti di velocità
Di seguito è riportato un riferimento strutturato per gli errori di connessione più comuni del server IMAP. Abbina il sintomo (messaggio di errore o comportamento osservabile) alla causa probabile e alla correzione consigliata.
| Sintomo / Errore | Categoria | Causa probabile | Risolvi |
|---|---|---|---|
| Connessione rifiutata sulla porta 993 | Connessione | Host sbagliato, IMAP disabilitato nelle impostazioni del provider o firewall che blocca il traffico in uscita sulla porta 993 | Verifica l'host dalla tabella sopra. Abilita IMAP nelle impostazioni del provider (Gmail: Impostazioni > Inoltro e POP/IMAP). Controlla firewall/proxy per TCP 993 in uscita. |
| Timeout nella negoziazione SSL / CERTIFICATE_VERIFY_FAILED | TLS | Certificato scaduto o autofirmato, bundle CA obsoleto, porta errata (143 invece di 993) | Utilizzo ssl.create_default_context() (Python) - non passare ssl._create_unverified_context() in produzione. Aggiorna il tuo pacchetto di CA (pip install certifi). Conferma che ti stai connettendo alla porta 993. |
| AUTENTICAZIONEFALLITA / [AUTENTICAZIONEFALLITA] Credenziali non valide | Autorizzazione | Password errata, password dell'app non generata, 2FA abilitato ma password dell'app non utilizzata, Basic Auth bloccato dal provider | Genera una password specifica per l'app dalle impostazioni di sicurezza del provider. Se utilizzi Gmail, assicurati che "Accesso ad app meno sicure" non sia il metodo utilizzato: usa la password per le app o OAuth. Per Microsoft, verifica se l'autenticazione di base è disabilitata per il tenant. |
| AUTENTICAZIONE XOAUTH2 - token_non_valido | OAuth | Token di accesso scaduto (i token durano 3600s), stringa XOAUTH2 base64 malformata, ambito errato | Aggiornare il token di accesso prima di connettersi. Verificare il formato della stringa XOAUTH2: email=email\x01auth=Bearer {token}\x01\x01. Verifica ambito: Gmail necessita https://mail.google.com/; Outlook necessita IMAP.AccessAsUser.All. |
| imaplib.error: comando AUTHENTICATE illegale nello stato AUTH | Stato | Tentativo di autenticazione quando si è già in stato autenticato, o dopo un tentativo di autenticazione fallito senza reimpostare | Chiudere e riaprire la connessione IMAP prima di ritentare l'autenticazione. Non ritentare mai l'autenticazione sulla stessa connessione dopo un errore. |
| La connessione IMAP cade dopo 29 minuti di IDLE | INATTIVO | Timeout IDLE imposto dal server (predefinito: 30 minuti per RFC 2177). Gmail imposta 29 minuti. | Problema FATTO tra i 25 e i 27 minuti, quindi immediatamente riemettere INATTIVO. Usa un thread in background o un'attività asincrona con un timer di heartbeat di 25 minuti. |
| [FUORI QUOTA] o Troppe connessioni simultanee | Limite di utilizzo | Hai superato il limite di connessione imposto dal provider. Gmail consente 15 connessioni IMAP simultanee per account; Outlook varia a seconda del piano. | Usa il connection pooling. Per Gmail: max 15 connessioni simultanee per account. Chiudi esplicitamente le connessioni inattive (ESCIanziché abbandonare la connessione TCP. Implementa il ritardo esponenziale sugli errori di connessione. |
| NO [ALLARME] Per favore, effettua l'accesso tramite il tuo browser web | Autorizzazione | Sfida di sicurezza di Google attivata (schema di accesso insolito, nuovo IP, richiesta captcha) | Accedi tramite browser dalla stessa rete per risolvere la sfida di sicurezza. Considera il passaggio a OAuth: l'accesso con password dell'app da IP sconosciuti attiva queste sfide più spesso di OAuth. |
| Arrivederci Logout Automatico; inattivo per troppo tempo | Connessione | Connessione IMAP nello stato Autenticato (casella di posta non selezionata) è rimasta inattiva troppo a lungo | Dopo l'autenticazione, SELEZIONA immediatamente una casella di posta o emetti IDLE. Implementa la logica di riconnessione quando ricevi BYE. |
| FETCH restituisce corpo vuoto / parti nulle | Protocollo | Messaggio cancellato tra SEARCH e FETCH, o mancata corrispondenza UID dopo nuova scansione della cartella | Sempre UID recupera (senza numeri di sequenza) per operazioni in più fasi. Gestisci Nessuno gestire i valori di ritorno di FETCH in modo grazioso. Ristampare SEARCH dopo una riconnessione per ottenere UID freschi. |
ssl.create_default_context() (Python) - non passare ssl._create_unverified_context() in produzione. Aggiorna il tuo pacchetto di CA (pip install certifi). Conferma che ti stai connettendo alla porta 993.
email=email\x01auth=Bearer {token}\x01\x01. Verifica ambito: Gmail necessita https://mail.google.com/; Outlook necessita IMAP.AccessAsUser.All.
FATTO tra i 25 e i 27 minuti, quindi immediatamente riemettere INATTIVO. Usa un thread in background o un'attività asincrona con un timer di heartbeat di 25 minuti.
ESCIanziché abbandonare la connessione TCP. Implementa il ritardo esponenziale sugli errori di connessione.
UID recupera (senza numeri di sequenza) per operazioni in più fasi. Gestisci Nessuno gestire i valori di ritorno di FETCH in modo grazioso. Ristampare SEARCH dopo una riconnessione per ottenere UID freschi.
Smetti di correggere gli errori IMAP. Unipile espone oggetti email puliti tramite REST - nessuna state machine IMAP, nessuna logica di refresh dei token, nessun pooling di connessioni da gestire.
Smetti di fare il debug dell'IMAP - Inizia a costruirePerché l'IMAP a livello di produzione su larga scala è più difficile di quanto sembri
Aprire una singola connessione al server IMAP a una casella di posta Gmail richiede 15 righe di Python. Scalare questo a centinaia o migliaia di utenti in un prodotto SaaS di produzione è un problema di ingegneria fondamentalmente diverso. Di seguito è riportata un'analisi onesta di dove le connessioni IMAP grezze creano complessità non ovvie.
I token di accesso scadono ogni 3600 secondi. Per 1.000 account collegati, è necessaria un'attività in background che aggiorni proattivamente i token prima della scadenza, gestisca la rotazione dei token di aggiornamento (Google li ruota in determinate condizioni) e gestisca il caso in cui un utente revochi l'accesso, cosa che si scopre solo al prossimo utilizzo del token.
Ogni sessione IMAP attiva conserva lo stato: casella di posta selezionata corrente, ultimo UID visto, timer IDLE. Se il tuo server si riavvia, perdi tutto questo stato e devi risincronizzare da zero, potenzialmente recuperando migliaia di messaggi che hai già elaborato. Hai bisogno di un archivio di stato persistente per account.
Iscriviti alle notifiche per modifiche ai dati.
I token di aggiornamento OAuth sono credenziali di lunga durata che garantiscono l'accesso completo alle e-mail. Devono essere crittografati a riposo utilizzando una chiave supportata da KMS, controllati a livello di infrastruttura e ruotati in caso di qualsiasi indicazione di una violazione. Questa è una superficie di attacco di sicurezza significativa che richiede un'infrastruttura di gestione delle chiavi adeguata.
Gmail limita le connessioni IMAP simultanee a 15 per account. Se la tua applicazione apre più connessioni del consentito, riceverà errori OVERQUOTA. Allo stesso tempo, i provider impongono anche limiti di banda sui dati totali trasferiti. Hai bisogno di connection pooling, request throttling e tracciamento del rate per account.
Etichette Gmail vs. cartelle IMAP, la denominazione non standard delle cartelle di Outlook per Inviati/Eliminati, i server IMAP che restituiscono risposte CAPABILITY non corrispondenti a quanto supportano realmente e i server che interrompono silenziosamente le connessioni durante le operazioni FETCH su allegati di grandi dimensioni. Ogni provider ha un insieme unico di stranezze che emergono solo in produzione.
Questo non è un argomento contro la creazione di un'integrazione IMAP personalizzata: per uno strumento a fornitore singolo e utente singolo, l'IMAP grezzo è perfettamente ragionevole. Ma per qualsiasi prodotto che necessiti di leggere e sincronizzare email da più provider e più account utente, il costo operativo di mantenimento di un livello IMAP personalizzato supera in genere il costo dell'utilizzo di un'API di posta elettronica dedicata. Il Guida API email unificata descrive in dettaglio i compromessi architettonici.
Sincronizzazione delle email di produzione senza l'overhead dell'IMAP. Unipile gestisce il connection pooling, il refresh dei token, il retry degli errori e la normalizzazione multi-provider: tu devi solo chiamare l'API.
Costruire su larga scala senza l'overhead di IMAPCostruire un'integrazione IMAP senza gestire la connessione: Unipile
Se hai letto fin qui, hai un quadro chiaro di cosa ci vuole per mantenere le connessioni IMAP grezze in produzione: cicli di refresh dei token OAuth, gestione dello stato per account, pooling delle connessioni, logica di retry e peculiarità specifiche del provider per Gmail, Outlook e server IMAP. Unipile astrae questo intero livello e ti fornisce un'unica API REST per leggere, inviare e sincronizzare le email su tutti e tre, con una guida rapida di 5 minuti e meno di 10 righe di codice per operazione.
Unipile gestisce l'intero flusso OAuth per Gmail e Microsoft 365: acquisizione, refresh e rotazione dei token. Non tocchi mai direttamente un token di refresh.
Un'API, uno schema di risposta. Leggi le email da una casella di posta Gmail e da un server aziendale IMAP con la stessa chiamata GET /emails. Nessun parsing specifico del provider.
Ricevi notifiche HTTP quando arrivano nuove email. Nessuna connessione IMAP persistente da gestire, nessun timeout IDLE di 29 minuti da gestire, nessun thread dedicato per account.
Collega account utente tramite il flusso OAuth ospitato di Unipile. Ogni account collegato ottiene il proprio account_id. Scala da 1 a 10.000 account collegati senza modificare il codice della tua integrazione.
Credenziali crittografate a riposo con chiavi supportate da KMS. Unipile è certificata SOC 2 Type II e valutata CASA Tier 2. Nessuna password IMAP o token OAuth archiviata nel tuo database.
import richieste
BASE_URL = "https://api7.unipile.com:13047/api/v1"
INTÈSTAZIONI = {"X-API-KEY": "la-tua-chiave-api-unipile"}
# Fase 1: Elenca tutti gli account collegati
conti = richieste.ottenere(
f"{BASE_URL}/conti", intestazioni=INTÈSTAZIONI
).json()
account_id = conti["articoli"][0]["id"]
# Fase 2: Leggi le e-mail nella posta in arrivo
e-mail = richieste.ottenere(
f"{BASE_URL}/emails",
intestazioni=INTESTAZIONI,
parametri={"account_id": id_account, "limite": 10}
).json()
per e-mail in email"articoli"]:
print(email["soggetto", email["dal_partecipante"])
# Nessuna connessione IMAP, nessun aggiornamento del token,
#: nessun contesto SSL, nessuna macchina a stati.
Domande frequenti
Domande comuni sulla connessione al server IMAP, porte, autenticazione e migrazione OAuth.
Una connessione server IMAP è una sessione TCP persistente tra un client di posta elettronica e un server di posta che utilizza il protocollo Internet Message Access Protocol per sincronizzare, recuperare e gestire messaggi di posta elettronica memorizzati sul server, senza scaricarli o eliminarli localmente. A differenza di POP3, IMAP mantiene i messaggi sul server e sincronizza lo stato (letto, contrassegnato, spostato) su tutti i dispositivi connessi. Per gli sviluppatori, è il protocollo fondamentale per la creazione di integrazioni di posta elettronica che funzionano su Gmail, Outlook e qualsiasi standard. API IMAP.
Utilizzo porta 993 per IMAP su SSL/TLS (TLS implicito). Questo è lo standard moderno ed è richiesto da tutti i principali provider cloud, inclusi Gmail e Outlook. La porta 143 è per gli aggiornamenti STARTTLS ed è appropriata solo per server di posta auto-ospitati. Non connettersi mai a un server di posta cloud sulla porta 143 in produzione, la maggior parte ora rifiuta del tutto tali connessioni. In caso di dubbi, scegli sempre la porta 993 con ssl=Vero.
Sì, senza eccezioni. SSL/TLS è obbligatorio per qualsiasi connessione al server IMAP che trasmette credenziali. I moderni server di posta rifiutano del tutto le connessioni in chiaro. RFC 9051 (IMAP4rev2) richiede formalmente TLS per tutte le sessioni autenticate. Utilizzare sempre porta 993 con TLS implicito per i provider cloud. Se ci si connette a un server self-hosted sulla porta 143, è necessario eseguire l'aggiornamento a TLS utilizzando il comando STARTTLS e verificare il certificato del server - non utilizzare mai ssl._create_unverified_context() in produzione.
L'indirizzo del server IMAP per Gmail è imap.gmail.com on porta 993 con SSL/TLS. Prima di connetterti, devi abilitare l'accesso IMAP nelle Impostazioni di Gmail alla voce "Inoltro e POP/IMAP". L'autenticazione richiede una password per le app (se è abilitata l'autenticazione a due fattori) o OAuth 2.0 XOAUTH2 con l'ambito https://mail.google.com/. Google ha limitato l'autenticazione di base per le nuove app e raccomanda vivamente OAuth per qualsiasi accesso programmatico IMAP.
L'indirizzo del server IMAP sia per gli account Outlook.com personali che per gli account aziendali Microsoft 365 è outlook.office365.com on porta 993 con SSL/TLS. Si noti che Microsoft sta terminando il supporto per l'autenticazione di base (nome utente/password) per IMAP in Dicembre 2026. Tutte le integrazioni devono migrare a OAuth 2.0 XOAUTH2 prima di tale scadenza. Vedi il nostro Microsoft Graph OAuth per Outlook Guida ai passaggi per la migrazione.
È necessario un codice di accesso specifico per l'app se l'account dispone dell'autenticazione a due fattori abilitata e si utilizza l'autenticazione di base per IMAP. I codici di accesso per le app sono token di 16 caratteri generati dalle impostazioni di sicurezza del provider (pagina di sicurezza dell'account Google per Gmail, ID Apple per iCloud) che sostituiscono la password reale senza concedere l'accesso completo all'account. Per le applicazioni multiutente di produzione, OAuth 2.0 è fortemente preferito password dell'app - è più sicuro, non richiede la memorizzazione di alcuna credenziale utente nella tua applicazione ed è l'unico metodo che rimarrà valido dopo la disattivazione dell'autenticazione di base di Microsoft a dicembre 2026.
Sì, per i servizi Microsoft. Microsoft ha confermato la fine definitiva del supporto per l'autenticazione di base su IMAP, POP3 e SMTP in Exchange Online in Dicembre 2026, interessando tutti gli inquilini, inclusi quelli con esenzioni esistenti. Qualsiasi integrazione che utilizzi l'autenticazione nome utente/password contro Outlook o Microsoft 365 IMAP smetterà di funzionare dopo tale data. Google ha già limitato l'accesso all'autenticazione di base (Basic Auth) per Gmail e richiede password per le app o OAuth per qualsiasi accesso programmatico dal 2022. Se la tua integrazione IMAP si collega ad account Microsoft, devi migrare a OAuth 2.0 XOAUTH2 entro dicembre 2026.
Per connettersi a un server IMAP con OAuth 2.0, si utilizza il meccanismo SASL XOAUTH2. Dopo aver ottenuto un token di accesso tramite il flusso standard di codice di autorizzazione OAuth, codificare la stringa email=email\x01auth=Bearer {token}\x01\x01 come base64, quindi passalo a AUTENTICAZIONE XOAUTH2 IMAP comando. Per Gmail, lo scope richiesto è https://mail.google.com/. Per Microsoft 365, utilizza MSAL per acquisire un token con il IMAP.AccessAsUser.All Le token di accesso scadono dopo 3600 secondi e devono essere rinnovate prima di riconnettersi - implementare un controllo di rinnovo della token prima di ogni nuova sessione IMAP. Vedere i campioni di codice completi nella sezione XOAUTH2 sopra.
IT 
EN 
FR 
ES 
DE 
BR 
NL 
PL 
TR