IMAP API in Python: imaplib, IMAPClient, XOAUTH2 OAuth Guide (2026)

Guida API IMAP Python

API IMAP in Pitone: imaplib, IMAPClient e Guida OAuth XOAUTH2

Una guida completa alla creazione di client email IMAP in Python nel 2026: dalle basi di stdlib imaplib ai pattern di produzione di IMAPClient, l'autenticazione OAuth XOAUTH2 per Gmail e Outlook, e quando un'API di email unificata ti salva del tutto dalla complessità.

imap_client.py
import imaplib, email from email.intestazione import decodifica_intestazione #: Connessione tramite OAuth XOAUTH2 posta elettronica = imaplib.IMAP4_SSL('imap.gmail.com') auth_str = build_xoauth2(utente, token) posta.autenticare('XOAUTH2', lambda x: auth_str) # Recupera i messaggi non letti posta.seleziona('POSTA IN ARRIVO') _, ids = posta.ricerca(Nessuno, 'INVISIBILE') per uid in id[0].spaccare(): _, data = posta.fetch(uid, '(RFC822)') messaggio = email.messaggio_da_byte(dati[0][1])
Recupero email da Gmail, Outlook, IMAP...
Definizione

Che cos'è un client Python IMAP?

Un API IMAP Python Un client è qualsiasi programma Python che comunica con un server di posta utilizzando il protocollo IMAP4 (RFC 3501) per leggere, cercare, organizzare e sincronizzare i messaggi di posta elettronica. A differenza di SMTP che invia solo posta, IMAP offre alla tua applicazione un accesso bidirezionale a una casella di posta remota: puoi recuperare le intestazioni, leggere i corpi dei messaggi, impostare le bandierine, spostare i messaggi tra cartelle e ascoltare i nuovi arrivi in tempo reale utilizzando IMAP IDLE.

Definizione rapida

IMAP (Internet Message Access Protocol) è un protocollo standard che consente ai client di recuperare e gestire le e-mail archiviate su un server remoto. Un client IMAP Python si connette tramite la porta TLS 993, si autentica (Basic o OAuth XOAUTH2), quindi emette comandi IMAP per recuperare, cercare, contrassegnare e organizzare i messaggi. Python offre tre livelli di astrazione: la libreria standard imaplib, i più alti IMAPClient wrapper, e opzioni completamente asincrone come aioimaplib. Per una panoramica completa sull'architettura IMAP e sugli scenari di utilizzo, consulta la nostra Guida per sviluppatori API IMAP.

Sincronizzazione email per SaaS

Sincronizza le caselle di posta degli utenti nel tuo CRM, ATS o helpdesk. Python IMAP ti consente di interrogare o inviare (IDLE) nuovi messaggi nel tuo database senza dover gestire un server di posta completo.

Automazione e pipeline AI

Estrai, classifica e instrada le email in entrata usando Python. Il tuo client IMAP alimenta una coda di elaborazione: analisi fatture, creazione ticket, punteggio lead o riassunto LLM.

Strumenti per sviluppatori

Testa la consegna delle email, crea strumenti per l'inbox zero o effettua audit di deliverability. Python IMAP ti offre accesso programmatico alla stessa casella di posta che vedono i tuoi utenti. Dai un'occhiata al nostro guida API email per l'intero ecosistema.

Confronto librerie

Le 3 opzioni dello stack IMAP di Python

La scelta della giusta libreria IMAP Python dipende dal tuo caso d'uso: uno script veloce, un servizio di produzione o una pipeline asincrona. Ecco un confronto delle opzioni principali prima di immergerci negli esempi di codice per ciascuna.

Biblioteca Tipo Supporto OAuth Asincrono Assistenti di Parsing Il migliore per
imaplib Stdlib (zero dipendenze) Manuale No Minimo Script semplici, nessun dipendenza esterna
IMAPClient Wrapper di terze parti Manuale No Bene Produzione IMAP senza asincrono
aioimaplib Libreria asincrona Manuale Limitato Pipeline asyncio e IDLE su larga scala
API UnipileIl meglio REST/SDK unificato Incorporato Completo Produzione multi-fornitore su larga scala
imaplib — Stdlib
OAuth:Impostazione manuale
Asincrono:No
Analisi:Minimo
Ideale per:Script semplici, zero dipendenze
IMAPClient — Invulucro
OAuth:Impostazione manuale
Asincrono:No
Analisi:Buoni aiutanti
Ideale per:Produzione IMAP, no asincrono
aioimaplib Asincrono
OAuth:Impostazione manuale
Asincrono:Sì (asyncio)
Analisi:Limitato
Ideale per:pipeline asyncio, IDLE su larga scala
API UnipileIl meglio
OAuth:Incorporato
Asincrono:
Analisi:JSON completo strutturato
Ideale per:Produzione multi-fornitore su larga scala

Evita la complessità dell'IMAP. Unipile astrae la logica di imaplib, OAuth e multi-provider in una singola API REST. Un'unica integrazione per Gmail, Outlook e qualsiasi server IMAP.

Inizia a costruire gratis
Tutorial di codice

Guida rapida: Connettersi a IMAP con imaplib

La libreria standard di Python include imaplib - nessuna installazione necessaria. Ecco una guida completa dalla connessione al recupero del corpo, con commenti onesti sui punti dolenti.

1
Connettersi e autenticarsi

Utilizzo imaplib.IMAP4_SSL sulla porta 993 per una connessione crittografata. Per Gmail e Outlook, vedere gli indirizzi del server nel nostro Guida alla connessione del server IMAP. L'autenticazione di base (password) funziona per i server IMAP che la consentono ancora, ma Gmail e Outlook ora richiedono OAuth XOAUTH2 (trattato nella Sezione 5).

connect.py
import imaplib #: connessione a Gmail tramite IMAP (porta TLS 993) posta elettronica = imaplib.IMAP4_SSL('imap.gmail.com', 993) # Autenticazione di base (solo password dell'app - si preferisce OAuth) posta.Accedi('user@gmail.com', 'password dell'app') # Elenca tutte le caselle di posta stato, cassette postali = posta.list() per scatola in cassette postali printscatola.decodifica('utf-8')) posta.disconnettersi()
2
Seleziona una cartella e cerca messaggi

Il seleziona() la chiamata apre una casella di posta e restituisce il conteggio dei messaggi. cerca() restituisce una stringa di byte separata da spazi di ID dei messaggi, non UID. È necessario decodificare e dividere manualmente.

search.py
# Seleziona "Posta in arrivo" (o qualsiasi altra cartella) stato, conteggio = posta.seleziona('POSTA IN ARRIVO') print(Messaggi: {count[0].decode()}') # Cerca messaggi NON VISIBILI stato, msg_ids = posta.ricerca(Nessuno, 'INVISIBILE') ids = msg_ids[0].spaccare() print(Conteggio non letto: {len(ids)}') # Ricerca per mittente _, da_id = posta.ricerca(Nessuno, 'Da', 'boss@company.com') # Ricerca per intervallo di date _, recente = posta.ricerca(Nessuno, 'da', '01-gen-2026')
3
Recupera le intestazioni ed esegui il parsing del corpo

Qui è dove imaplib si sporca. La risposta grezza è una lista di tuple contenenti byte. Devi indicizzare dati[0][1] per raggiungere il messaggio grezzo, quindi passalo al e-mail modulo per il parsing. Gli header sono codificati secondo RFC 2047 e richiedono decodifica_intestazione().

fetch_body.py
import e-mail from email.intestazione import decodifica_intestazione def decodifica_stringa(valore): "Decodifica il valore dell'intestazione codificato secondo RFC 2047." parti = decodifica_intestazionevalore decodificato = [] per parte, cifra in parti: se isinstanceparte, byte): decodificato.aggiungi(parte.decodifica(incorporare o 'utf-8', errori='sostituire')) altro: decodificato.aggiungi(parte) return ' '.unire(decodificato) per uid in ids[-5:]: #: ultimi 5 messaggi _, data = posta.fetch(uid, '(RFC822)') grezzo = dati[0][1] Il tormento dello unpacking delle tuple # messaggio = email.messaggio_da_byte(grezzo) soggetto = decodifica_stringa(messaggio'Oggetto'] o '') mittente = decodifica_stringa(messaggio'Da'] o '') # Walk: parti MIME per il corpo del testo in chiaro se messaggio.è_multi_parte(): per parte in messaggio.cammina(): se parte.Ottieni_tipo_di_contenuto() == 'testo/normale': corpo = parte.ottieni_payload(decodifica=Vero).decodifica('utf-8', errori='sostituire') print(Da: {sender} | Oggetto: {subject}')

I punti dolenti di imaplib: le risposte in byte grezzi richiedono un'attenta indicizzazione delle tuple (dati[0][1]), le intestazioni sono codificate RFC 2047 e devono decodifica_intestazione(), i corpi MIME multipart richiedono un completo camminare(), e non ci sono helper integrati per UID rispetto ai numeri di sequenza. Per carichi di lavoro di produzione, considera IMAPClient (Sezione 4) o un API IMAP unificata invece.

Libreria di produzione

Approfondimento: IMAPClient per la Produzione

Una volta che entri in produzione con imaplib, noti rapidamente l'analisi delle risposte fragile, la gestione incoerente degli UID e l'assenza di helper per attività comuni. IMAPClient è un wrapper pythonico che smussa questi spigoli vivi, rimanendo fedele alle specifiche IMAP.

Perché imaplib si interrompe in produzione
Le risposte sono tuple di byte grezzi — indicizzazione fragile delle tuple dati[0][1]
Nessun recupero basato su UID per impostazione predefinita (usa uid() (involucro manualmente)
Nessun helper integrato per l'analisi MIME o l'estrazione del corpo
IDLE richiede la gestione manuale dei socket
La decodifica dell'intestazione RFC 2047 è il tuo problema
Cosa ti offre IMAPClient
Risposte dizionario strutturate - nessun disimballaggio di tuple richiesto
Modalità UID per impostazione predefinita (use_uid=Vero)
Pulitore cerca(), fetch(), sposta(), copia() API
Supporto IDLE integrato con inattivo() / idle_check()
Funziona con qualsiasi server IMAP - Gmail, Outlook, IMAP personalizzato
imapclient_example.py
from imapclient import IMAPClient import stampa elegante #: connessione tramite IMAPClient (impostazione predefinita: use_uid=True) server = IMAPClient('imap.gmail.com', ssl=Vero, use_uid=Vero) server.Accedi('user@gmail.com', 'password dell'app') # Seleziona e cerca server.seleziona_cartella('POSTA IN ARRIVO') messages = server.ricerca(['INVISIBILE']) print({len(messages)} messaggi non letti') # Fetch - restituisce un dizionario strutturato, non byte grezzi response = server.fetch(messaggi[:10], ['Busta', 'CORPO[]', 'BANDIERE']) per uid, data in risposta.articoli(): busta = dati[Invio'] print(UID {uid}: {envelope.oggetto}') # Sposta i messaggi nella cartella server.spostare(messaggi[:5], 'Archivio') # INATTIVO - in attesa di nuovi messaggi (fino a 29 minuti su Gmail) server.inattivo() risposte = server.controllo_inattivo(scadenza=60) print('Risposta IDLE:', risposte) server.idle_done() server.disconnettersi()

Anche IMAPClient richiede la gestione manuale dei token OAuth e la gestione multi-provider. Unipile astrae tutto questo - refresh OAuth, particolarità dei provider, riconnessioni IDLE - dietro una singola API REST. Vedi il nostro completo guida API email.

Costruiscilo con Unipile
OAuth XOAUTH2

OAuth XOAUTH2 in Python: Gmail e Microsoft 365

L'autenticazione di base tramite password è morta per i principali provider. Gmail l'ha bloccata per gli account standard da maggio 2022. Microsoft 365 ha deprecato l'autenticazione di base per IMAP a settembre 2024. XOAUTH2 (un meccanismo SASL OAuth 2.0) è ora l'unico modo di livello di produzione per autenticare un client IMAP Python. Per la spiegazione completa del flusso OAuth, consulta il nostro Guida API email OAuth.

Come funziona XOAUTH2

XOAUTH2 è un meccanismo di autenticazione SASL che codifica un token OAuth Bearer in una stringa base64 con il formato: email=email\x01auth=Bearer {token}\x01\x01. Questa stringa viene passata a imaplib.IMAP4_SSL.authenticate('XOAUTH2', callback). Il callback restituisce la stringa codificata in base64. La responsabilità di ottenere e rinnovare il token di accesso OAuth tramite gli endpoint di identità di Google o Microsoft prima di effettuare la connessione IMAP è tua. Per gli ambiti Gmail richiesti, consulta il nostro Guida agli scope dell'API di Gmail.

Gmail Gmail
Prospettiva Microsoft 365
gmail_xoauth2.py
import imaplib, base64, json from google.oauth2.credenziali import Credenziali from google.auth.transport.requests import Richiesta def build_xoauth2_string(email_utente, token_di_accesso): "Crea una stringa SASL XOAUTH2 per l'autenticazione IMAP." auth_string = f'utente={user_email}\x01auth=Bearer {access_token}\x01\x01' return base64.b64encode(stringa_auth.codificare('ascii')) def ottieni_token_valido(credenziali_dict): "Aggiorna il token se scaduto usando la libreria google-auth." crediti = Credenziali.dalle_informazioni_utente_autorizzato(creds_dict) se credenziali.scaduto e creds.refresh_token: credenziali.ricaricare(Richiesta()) return creds.token # Ambito IMAP richiesto per Gmail: https://mail.google.com/ indirizzo email utente = 'user@gmail.com' token_accesso = ottieni_token_valido(creds_dict) posta elettronica = imaplib.IMAP4_SSL('imap.gmail.com') auth_string = build_xoauth2_string(email_utente, token_accesso) posta.autenticare('XOAUTH2', lambda x: auth_string) # Ora utilizzalo normalmente posta.seleziona('POSTA IN ARRIVO') _, ids = posta.ricerca(Nessuno, 'TUTTO') print(Messaggi totali: {len(ids[0].split())}')
Requisito scope Gmail: Il token di accesso deve essere ottenuto con il https://mail.google.com/ ambito (non gmail.solodlettura solo - tale ambito non concede l'accesso IMAP). Consulta la nostra Guida agli scope dell'API di Gmail per una ripartizione completa. Devi inoltre abilitare l'IMAP nelle impostazioni di Gmail e utilizzare un ID client OAuth 2.0 di Google Cloud con l'URI di reindirizzamento corretto.
outlook_xoauth2.py
import imaplib, base64 import msal def build_xoauth2_string(email_utente, token_di_accesso): auth_string = f'utente={user_email}\x01auth=Bearer {access_token}\x01\x01' return base64.b64encode(stringa_auth.codificare('ascii')) # MSAL - Libreria di autenticazione Microsoft per Python ID_CLIENTE = 'il-tuo-id-client-app-azure' ID_INQUILINO = 'id-del-tuo-inquilino' Configurazione # per l'accesso IMAP (Outlook / Microsoft 365) Ambito = ['https://outlook.office365.com/IMAP.AccessAsUser.All'] app = msal.PublicClientApplication(ID_CLIENTE, autorità=f'https://login.microsoftonline.com/{TENANT_ID}') # Ottieni token (in modo interattivo o tramite token di aggiornamento) risultato = app.acquisisci_token_con_codice_autorizzazione(codice, ambiti=SCOPE, uri\_reindirizzamento=redirect_uri) token_accesso = risultato['access_token'] #: connessione a Outlook tramite IMAP con XOAUTH2 indirizzo email utente = 'user@outlook.com' posta elettronica = imaplib.IMAP4_SSL('outlook.office365.com') auth_string = build_xoauth2_string(email_utente, token_accesso) posta.autenticare('XOAUTH2', lambda x: auth_string) posta.seleziona('POSTA IN ARRIVO')
Microsoft 365 IMAP nota: Da settembre 2024, Microsoft ha disabilitato l'autenticazione di base per IMAP su tutti i tenant di Microsoft 365. Devi utilizzare XOAUTH2. Registra un'applicazione Azure AD, abilita l'autorizzazione "IMAP.AccessAsUser.All" e utilizza MSAL per l'acquisizione del token. Per Microsoft Graph come alternativa a IMAP, consulta il nostro Guida OAuth di Microsoft Graph per l'email.

OAuth XOAUTH2 sono oltre 50 righe per provider. Unipile gestisce il rinnovo dei token, la stretta di mano XOAUTH2 e le peculiarità specifiche del provider in modo che il tuo codice Python si concentri sulla logica di business, non sugli aspetti tecnici dell'autenticazione.

Crea il tuo flusso OAuth
Matrice Fornitore

Controllo della realtà multi-fornitore

Ogni provider ha le sue bizzarrie di autenticazione, indirizzi server e limiti di frequenza. Ecco cosa deve gestire il tuo client IMAP Python per ciascuno di essi. Per i nomi host server e i dettagli della porta TLS, consulta la nostra dedicata Guida alla connessione del server IMAP.

Logo di Gmail
Gmail
imap.gmail.com:993
Auth:XOAUTH2 richiesto
Ambito:https://mail.google.com/
INATTIVO:Supportato (massimo 29 min)
Manie:Le etichette di Gmail corrispondono alle cartelle IMAP. Abilita IMAP nelle impostazioni.
Richiede un progetto Google Cloud con client OAuth 2.0. Vedi Guida agli scope di Gmail per dettagli sull'ambito.
Logo di Outlook
Outlook / Microsoft 365
outlook.office365.com:993
Auth:XOAUTH2 richiesto
Ambito:IMAP.AccessAsUser.All
INATTIVO:Supportato
Manie:Autenticazione di base disabilitata a settembre 2024. È necessaria un'app Azure AD con consenso dell'amministratore per M365.
Per un'alternativa basata su REST all'IMAP, vedi Guida OAuth di Microsoft Graph per l'email.
Logo IMAP
IMAP generico
il-tuo-server:993
Auth:Login/password OK
INATTIVO:Varia a seconda del server
Manie:Nomi delle cartelle specifici del server, le CAPACITÀ variano, alcuni mancano di IDLE.
Esempi:Fastmail, ProtonMail Bridge, Postfix/Dovecot self-hosted
Copre quasi tutti i server IMAP4rev1. Vedi Guida all'API IMAP per l'elenco completo.
Yahoo Mail
imap.mail.yahoo.com:993
Auth:È necessaria una password per l'app (nessun XOAUTH2 per terze parti)
INATTIVO:Supportato
Yahoo ha interrotto il supporto per XOAUTH2 nelle app di terze parti. Genera una password specifica per l'app nelle impostazioni di Sicurezza dell'account Yahoo.
Posta di iCloud
imap.mail.me.com:993
Auth:È necessaria una password per l'app
INATTIVO:Supportato
L'autenticazione a due fattori deve essere abilitata sull'ID Apple. Genera una password per ID Apple specifica per l'app su appleid.apple.com.

Supportare più provider significa mantenere flussi di autenticazione separati, configurazioni del server e soluzioni per le particolarità. Unipile normalizza Gmail, Outlook e qualsiasi server IMAP in un'unica API. Leggi la nostra Confronto fornitori API email per contesto.

Crea email multi-provider
Alternativa API unificata

Quando saltare completamente IMAP: Approccio API unificata

Dopo aver esplorato imaplib, IMAPClient e XOAUTH2, una verità diventa chiara: l'IMAP grezzo in Python richiede centinaia di righe di codice ripetitivo per ogni provider supportato. Unipile è un API IMAP unificata che astrae tutto questo in un'unica interfaccia REST. Colleghi account utente (Gmail, Outlook o qualsiasi server IMAP) con OAuth e Unipile gestisce ogni dettaglio del protocollo per tuo conto.

Con imaplib grezzo (oltre 50 righe per provider)
raw_imap.py
# 1. Ottenere il token OAuth (oltre 50 righe) # 2. Creare la stringa XOAUTH2 # 3. Connettersi + autenticarsi # 4. Seleziona cartella # 5. Ricerca messaggi # 6. Recupera i byte grezzi # 7. Analisi dei dati della tupla [0][1] # 8. Decodifica delle intestazioni RFC 2047 # 9. Esercizi di camminata con parti MIME # 10. Accessori per manici # 11. Gestione dei timeout di inattività # 12. Riconnessione in caso di errore # 13. Ripetere l'operazione per Outlook... # 14. Ripetere l'operazione per i server IMAP...
Con l'API REST di Unipile (5 righe)
unipile_email.py
import richieste # Recupera le e-mail da qualsiasi account collegato r = richieste.ottenere( '/api/v1/emails', intestazioni={'X-API-KEY': api_key}, parametri={'ID account': id_account ) e-mail = r.json()['oggetti'] # funziona con Gmail, Outlook e qualsiasi client IMAP
OAuth gestito per te

Unipile gestisce l'acquisizione, il rinnovo e la scadenza dei token XOAUTH2 per Gmail e Outlook. Nessuna configurazione MSAL o google-auth necessaria nel tuo codice.

Risposte JSON normalizzate

Nessun byte grezzo, nessun disimballaggio di tuple, nessuna decodifica RFC 2047. Ogni email torna come un JSON pulito e strutturato con intestazioni, corpo e allegati analizzati.

Webhook in tempo reale

Invece di gestire sessioni IDLE e riconnessioni, Unipile invia nuovi eventi email al tuo endpoint webhook. Nessun polling, nessuna gestione di socket.

Multi-provider di default

Un unico endpoint API serve Gmail, Outlook e qualsiasi server IMAP. Aggiungi nuovi provider collegando account: non sono necessarie modifiche al codice da parte tua.

Invia anche e-mail

Unipile copre l'intero ciclo di vita delle email. Leggi, cerca, sposta, segnala e invia - tutto dalla stessa API. Vedi la nostra Guida all'invio di email in Python dal lato mittente.

Account collegati per utente

Ciascuno dei tuoi utenti collega il proprio account tramite OAuth. Unipile agisce come intermediario tecnico indipendente per conto di ciascun utente autenticato, non come un pool di credenziali condiviso.

Errori di produzione

Errori comuni nella produzione

Dopo aver fatto funzionare un client IMAP Python in locale, la produzione rivela casi limite che possono causare perdite di dati silenziose, interruzioni di connessione o codifica dei caratteri errata. Ecco i problemi più comuni e come risolverli.

2026 Breaking Change: Fine vita di Microsoft Basic Auth IMAP

Microsoft ha completato la rimozione dell'autenticazione di base per IMAP su tutti gli tenant di Microsoft 365 in Settembre 2024. Qualsiasi codice Python che utilizzi posta.login(utente, password) contro outlook.office365.com riceverà ora Autenticazione fallita. La migrazione a XOAUTH2 (Sezione 5) è obbligatoria per tutte le integrazioni Microsoft 365 / Outlook IMAP. Le distribuzioni Exchange on-premises potrebbero ancora supportare l'autenticazione di base a seconda della configurazione del server.

01
Timeout IMAP IDLE (29 minuti su Gmail)

Gmail interrompe silenziosamente le connessioni IDLE dopo circa 29 minuti. Se il tuo codice non rinnova la sessione IDLE, i nuovi messaggi smettono di arrivare senza che venga generata alcuna eccezione.

Correggere: Imposta un timer per idle_done() ogni 25 minuti, poi chiama immediatamente inattivo() ancora. Usa seleziona_cartella('INBOX', readonly=False) per ricontrollare il conteggio dei messaggi alla riconnessione.
02
Errori di decodifica charset RFC 2047

Gli header delle email come Soggetto e Da usano la codifica RFC 2047 (Buon giorno. Chiamando str(msg['Oggetto']) direttamente su un valore di byte restituisce spazzatura o genera un errore Errore di decodifica Unicode.

Correggere: Sempre email.header.decode_header() e gestisci esplicitamente la codifica di ciascuna parte. Passa errori='sostituisci'' a .decode() per evitare crash su intestazioni malformate.
03
Analisi degli allegati da messaggi multipart

Gli allegati si trovano in parti MIME nidificate. Chiamando get_payload() su un messaggio multipart restituisce un elenco di parti, non il contenuto. Le immagini inline sono Content-Disposition: inline e avere un ID contenuto.

Correggere: Percorrere tutte le parti con msg.cammina(), controlla get_content_disposition() per allegato, e chiama get_payload(decode=True) sulla allegata parti per ottenere byte decodificati.
04
Connection pooling e thread safety

imaplib.IMAP4_SSL le istanze NON sono thread-safe. Utilizzare una connessione su più thread causa risposte confuse. Creare una nuova connessione per ogni richiesta è costoso e soggetto a limitazioni di frequenza.

Correggere: Utilizzare un pool di connessioni (una connessione per thread di lavoro) o una libreria asincrona come aioimaplib. Implementa sempre il backoff esponenziale per i tentativi di riconnessione dopo IMAP4.abort eccezioni.
05
Limiti di frequenza ed esaurimento delle quote

Gmail limita le connessioni IMAP a 15 connessioni simultanee per account e impone quote di larghezza di banda (2.500 MB/giorno tramite IMAP). Il recupero di interi corpi RFC822 su larga scala raggiungerà rapidamente questi limiti.

Correggere: Recupera prima le intestazioni (RFC822.HEADER), quindi recupera i corpi selettivamente. Usa BODY.PEEK[] invece di RFC822 per evitare la marcatura automatica come letta. Implementare il backoff esponenziale su [SUPERAMENTO DELLA QUOTA] risposte.
06
Scadenza del token OAuth a metà sessione

I token di accesso di Google e Microsoft scadono dopo 3.600 secondi (1 ora). Se la tua sessione IMAP è ancora aperta allo scadere del token, il comando successivo alla scadenza fallirà silenziosamente o restituirà NO.

Correggere: Tieni traccia del scade il timestamp. Prima di ogni operazione batch, verifica che il token non sia scaduto da più di 5 minuti e aggiornalo in modo proattivo. Archivia i token di aggiornamento in modo sicuro. Esattamente questo è ciò che Unipile gestisce automaticamente.

Evitare tutte le 6 insidie richiede un'infrastruttura significativa. Unipile gestisce riconnessioni IDLE, aggiornamento del token, limitazione della frequenza e normalizzazione multi-provider, in modo da poterti concentrare sulla logica del tuo prodotto. Parte del nostro completo guida API email.

Costruire senza le insidie
FAQ

Domande frequenti

Domande comuni sui client IMAP Python, imaplib, IMAPClient, autenticazione XOAUTH2 e quando utilizzare invece un'API di posta unificata.

01
Qual è la migliore libreria Python per IMAP?
Per script semplici, imaplib dalla libreria standard è sufficiente con zero dipendenze. Per uso in produzione, IMAPClient fornisce un'API più pulita con risposte strutturate e supporto IDLE integrato. Per carichi di lavoro asincroni su larga scala, aioimaplib si integra con asyncio. Se hai bisogno di supporto multi-provider (Gmail, Outlook e server IMAP personalizzati) con OAuth gestito automaticamente, un unificato API IMAP come Unipile rimuove la maggior parte della complessità.
02
imaplib può leggere le email di Gmail in Python?
Sì. Collegati a imap.gmail.com sulla porta 993 utilizzando imaplib.IMAP4_SSL. Tuttavia, Gmail non accetta più l'accesso con nome utente/password semplice per app di terze parti. Devi usare OAuth XOAUTH2 autenticazione con un token di accesso ottenuto da Google utilizzando il https://mail.google.com/ ambito. Consulta il nostro Guida agli scope dell'API di Gmail per la ripartizione completa dell'ambito. Le password per le app funzionano ancora per gli account personali con verifica in due passaggi abilitata, ma OAuth è richiesto per le applicazioni.
03
Cos'è XOAUTH2 in Python?
XOAUTH2 è un meccanismo SASL (Simple Authentication and Security Layer) utilizzato per autenticare le connessioni IMAP con un token Bearer OAuth 2.0 anziché con una password. In Python, si codifica la stringa email=email\x01auth=Bearer {token}\x01\x01 in base64, poi passalo a imaplib.IMAP4_SSL.authenticate('XOAUTH2', callback). Ciò sostituisce l'autenticazione di base obsoleta per Gmail e Microsoft 365. Esempi di implementazione completi sono nella Sezione 5 di questa guida. Vedere anche il nostro Guida API email OAuth.
04
Come uso OAuth con imaplib?
Per utilizzare OAuth con imaplib: 1) Ottieni un token di accesso dal provider (Google OAuth 2.0 o Microsoft MSAL). 2) Crea la stringa XOAUTH2: base64(f'user={email}\x01auth=Bearer {token}\x01\x01'). 3) Chiama mail.autentica('XOAUTH2', lambda x: auth_string). Per Gmail, usa il autenticazione google libreria per gestire il rinnovo dei token. Per Outlook/Microsoft 365, usa msal Libreria Python. Entrambi richiedono la registrazione di un'applicazione OAuth nella Google Cloud Console o in Azure AD. Il codice completo di imap per Python con OAuth si trova nella Sezione 5 sopra.
05
imaplib contro IMAPClient - quale dovrei usare?
Utilizzo imaplib quando hai bisogno di zero dipendenze esterne o solo di uno script semplice e una tantum. Usa IMAPClient per il codice di produzione: restituisce dizionari strutturati anziché tuple di byte grezze, utilizza UID per impostazione predefinita, fornisce più pulito cerca()/fetch()/sposta() metodi, e include il supporto integrato di IDLE. Entrambi richiedono la gestione autonoma dei token OAuth. Nessuno dei due è asincrono: per pipeline basate su asyncio, considera aioimaplib. Installa IMAPClient con pip install imapclient.
06
Come leggere le email di Outlook con Python IMAP?
Collegarsi a outlook.office365.com sulla porta 993 utilizzando imaplib.IMAP4_SSL. Dal settembre 2024, Basic Auth è disabilitato per Microsoft 365: devi usare XOAUTH2. Registra un'applicazione Azure AD, richiedi l IMAP.AccessAsUser.All autorizzazione, ottieni un token di accesso utilizzando il msal Libreria Python, quindi autenticati con posta.autentica('XOAUTH2', ...). Per gli account Outlook.com personali, viene applicato lo stesso flusso OAuth. Per i dettagli del server e la configurazione TLS, vedere il nostro Guida alla connessione del server IMAP.
07
L'IMAP funziona con Microsoft 365?
Sì, Microsoft 365 supporta l'IMAP su outlook.office365.com:993. Tuttavia, da settembre 2024, Microsoft ha disabilitato completamente l'autenticazione di base per IMAP sui tenant di Microsoft 365. Devi utilizzare OAuth 2.0 con il meccanismo SASL XOAUTH2. Il tuo amministratore di Azure AD potrebbe anche dover abilitare l'accesso IMAP nell'Exchange admin center. Un'alternativa è utilizzare API Microsoft Graph (REST) che evita completamente IMAP e fornisce metadati più ricchi.
08
Come gestire IMAP IDLE in Python?
IMAP IDLE consente al server di inviare notifiche quando arrivano nuovi messaggi. Con IMAPClient: chiama server.inattivo() per entrare in modalità IDLE, quindi server.idle_check(timeout=60) aspettare eventi. Gmail si disconnette silenziosamente dopo circa 29 minuti, allora dovrai rinnovare: chiama server.idle_done() ogni 25 minuti, poi server.inattivo() Ancora. Con imaplib grezzo, IDLE richiede una gestione manuale a livello di socket - considerevolmente più complessa. Per le email in tempo reale in produzione, un approccio basato su webhook (come quello offerto da Unipile) è più affidabile che mantenere sessioni IDLE.
09
Posso usare IMAP asincrono in Python?
Sì. Il aioimaplib La libreria fornisce un client IMAP4 compatibile con asyncio per Python. Supporta i comandi standard IMAP e IDLE in un contesto asincrono, rendendolo adatto per pipeline ad alta concorrenza in cui si gestiscono molte caselle di posta contemporaneamente. Tuttavia, aioimaplib ha una community più piccola rispetto a imaplib o IMAPClient, e il supporto OAuth richiede ancora un'implementazione manuale di XOAUTH2. Per i team che danno priorità alla velocità di sviluppo rispetto al controllo granulare, un'API unificata basata su REST offre messaggi di posta elettronica in tempo reale tramite webhook senza gestione di socket asincroni.
10
Come si confronta Unipile con imaplib per l'integrazione delle e-mail?
imaplib è una libreria standard di Python di basso livello che richiede 50-200 righe per provider: gestione dei token OAuth, costruzione XOAUTH2, parsing di byte grezzi, decodifica di intestazioni RFC 2047, scansione del corpo MIME, cicli di riconnessione IDLE. Unipile è un'unica API REST che astrae tutto ciò in un'unica chiamata HTTP con risposte JSON normalizzate, OAuth integrato per Gmail e Outlook, consegna webhook per nuove email e supporto multi-provider. Il compromesso: Unipile è un servizio gestito con prezzi propri, mentre imaplib è gratuito ma richiede un significativo investimento in infrastruttura. Vedi il nostro completo Guida all'API IMAP e confronto tra fornitori.

Hai ancora domande sull'API IMAP in Python? Il nostro team può aiutarti a scegliere l'approccio giusto per il tuo caso d'uso: IMAP grezzo o API unificata.

Parlare con un esperto
it_ITIT