IMAP API em Python: imaplib, IMAPClient, Guia OAuth XOAUTH2 (2026)

Guia da API IMAP Python

IMAP API em Python: imaplib, IMAPClient & Guia OAuth XOAUTH2

Um guia completo para construir clientes de e-mail em Python com IMAP em 2026: do básico do imaplib da biblioteca padrão a padrões de produção do IMAPClient, autenticação OAuth XOAUTH2 para Gmail e Outlook, e quando uma API unificada de e-mail o salva totalmente da complexidade.

imap_cliente.py
import imaplib, email from email.cabeçalho import decodificar_cabeçalho # Conectar-se com OAuth XOAUTH2 correio = imaplib.IMAP4_SSL('imap.gmail.com') auth_str = build_xoauth2(usuário, token) correio.autenticar('XOAUTH2', lambda x: auth_str) # Buscar mensagens não lidas correio.selecionar('Caixa de entrada') _, ids = correio.pesquisa(Nenhum, 'INVISÍVEL') para uid em ids[0].dividir(): _, data = correio.fetch(uid, '(RFC822)') mensagem = email.mensagem_de_bytes(dado[0][1])
Buscando e-mails do Gmail, Outlook, IMAP...
Definição

O que é um cliente Python IMAP?

Um IMAP API Python Um cliente é qualquer programa Python que se comunica com um servidor de e-mail usando o protocolo IMAP4 (RFC 3501) para ler, pesquisar, organizar e sincronizar mensagens de e-mail. Ao contrário do SMTP, que apenas envia e-mails, o IMAP oferece ao seu aplicativo acesso bidirecional a uma caixa de correio remota: você pode buscar cabeçalhos, ler corpos, definir marcadores, mover mensagens entre pastas e ouvir por novas mensagens em tempo real usando o IMAP IDLE.

Definição rápida

IMAP (Protocolo de Acesso a Mensagens da Internet) é um protocolo padrão que permite que clientes recuperem e gerenciem e-mails armazenados em um servidor remoto. Um cliente IMAP em Python se conecta sobre a porta TLS 993, autentica-se (Basic ou OAuth XOAUTH2) e, em seguida, emite comandos IMAP para buscar, pesquisar, sinalizar e organizar mensagens. O Python oferece três níveis de abstração: a biblioteca padrão imaplib, o de nível superior IMAPClient wrapper e opções totalmente assíncronas como aioimaplib. Para uma visão geral completa da arquitetura e casos de uso do IMAP, consulte nosso Guia do desenvolvedor da API IMAP.

Sincronização de Email para SaaS

Sincronize caixas de entrada de usuários em seu CRM, ATS ou helpdesk. O Python IMAP permite consultar ou enviar (IDLE) novas mensagens para seu banco de dados sem gerenciar um servidor de e-mail completo.

Automação e Pipelines de IA

Extraia, classifique e roteie e-mails de entrada usando Python. Seu cliente IMAP alimenta uma fila de processamento: análise de faturas, criação de tickets, pontuação de leads ou sumarização por LLM.

Ferramental de Desenvolvimento

Teste a entrega de e-mails, crie ferramentas de caixa de entrada zerada ou audite a capacidade de entrega. O IMAP em Python oferece acesso programático à mesma caixa de correio que seus usuários veem. Confira nosso guia da API de e-mail para todo o ecossistema.

Comparação de Bibliotecas

As 3 opções de pilha IMAP em Python

A escolha da biblioteca Python IMAP correta depende do seu caso de uso: um script rápido, um serviço de produção ou um pipeline assíncrono. Veja como as principais opções se comparam antes de mergulharmos em exemplos de código para cada uma.

Biblioteca Tipo Suporte ao OAuth Assíncrono Auxiliares de Análise Melhor para
imaplib Stdlib (zero dependências) Manual Não Mínimo Scripts simples, sem dependências externas
IMAPClient Wrapper de terceiros Manual Não Bom Produção IMAP sem assíncrono
aioimaplib Biblioteca assíncrona Manual Sim Limitada Pipelines assíncronas e IDLE em escala
API da UnipileMelhor REST/SDK Unificado Incorporado Sim Completo Produção multi-provedor em escala
imaplib — Stdlib
OAuth:Configuração manual
Assíncrono:Não
Análise:Mínimo
Melhor para:Scripts simples, zero dependências
IMAPClient — Wrapper
OAuth:Configuração manual
Assíncrono:Não
Análise:Bons ajudantes
Melhor para:Produção IMAP, sem assíncrono
aioimaplib — Assíncrono
OAuth:Configuração manual
Assíncrono:Sim (asyncio)
Análise:Limitada
Melhor para:Pipelines asyncio, ociosas em escala
API da UnipileMelhor
OAuth:Incorporado
Assíncrono:Sim
Análise:JSON Estruturado Completo
Melhor para:Produção multi-provedor em escala

Evite a complexidade do IMAP. Unipile abstrai imaplib, OAuth e a lógica multi-provedor em uma única API REST. Uma integração para Gmail, Outlook e qualquer servidor IMAP.

Comece a construir grátis
Tutorial de Código

Guia de início rápido: Conectando-se ao IMAP com imaplib

A biblioteca padrão do Python vem com imaplib - nenhuma instalação necessária. Aqui está um guia completo, desde a conexão até a busca do corpo, com comentários sinceros sobre os pontos problemáticos.

1
Conectar e autenticar

Uso imaplib.IMAP4_SSL na porta 993 para uma conexão criptografada. Para Gmail e Outlook, consulte os endereços de servidor em nosso Guia de conexão com o servidor IMAP. A Autenticação Básica (senha) funciona para servidores IMAP que ainda a permitem - mas Gmail e Outlook agora exigem OAuth XOAUTH2 (abordado na Seção 5).

connect.py
import imaplib #: Conectar-se ao Gmail via IMAP (porta TLS 993) correio = imaplib.IMAP4_SSL('imap.gmail.com', 993) # Autenticação básica (apenas senha de aplicativo — OAuth recomendado) correio.login('user@gmail.com', 'senha-do-aplicativo') # Listar todas as caixas de correio status, caixas de correio = correio.list() para caixa em caixas de correio: printcaixa.decodificar('utf-8')) correio.Sair()
2
Selecione uma pasta e pesquise por mensagens

O select() chamada abre uma caixa de correio e retorna a contagem de mensagens. buscar() retorna uma string de bytes separada por espaço de IDs de mensagem - não UIDs. Você precisa decodificar e dividir manualmente.

search.py
# Selecione a Caixa de entrada (ou qualquer pasta) status, contagem = correio.selecionar('Caixa de entrada') print(Mensagens: {count[0].decode()}') # Pesquisar mensagens NÃO VISIBIS status, msg_ids = correio.pesquisa(Nenhum, 'INVISÍVEL') identificadores = msg_ids[0].dividir() print(Contagem não lida: {len(ids)}') # Pesquisar por remetente _, de_ids = correio.pesquisa(Nenhum, 'DE', 'boss@company.com') # Pesquisa por intervalo de datas _, recente = correio.pesquisa(Nenhum, 'DESDE', '01-Jan-2026')
3
Buscar cabeçalhos e analisar o corpo

É aqui que imaplib fica confuso. A resposta bruta é uma lista de tuplas contendo bytes. Você deve indexar dados[0][1] para acessar a mensagem bruta, depois passá-la para o e-mail módulo para análise. Cabeçalhos são codificados em RFC 2047 e requerem decodificar_cabeçalho().

fetch_body.py
import e-mail from email.cabeçalho import decodificar_cabeçalho def decodificar_str(valor): "Decodificar valor de cabeçalho codificado RFC 2047." peças = decodificar_cabeçalho(valor) decodificado = [] para parte, enc em peças se isinstanceparte, bytes): decodificado.anexar(parte.decodificarEnc */} ou 'utf-8', erros='substituir')) senão: decodificado.anexar(parte) return ' '.participar(decodificado) para uid em ids[-5:]: #: últimas 5 mensagens _, data = correio.fetch(uid, '(RFC822)') cru = dados[0][1] O incômodo da desembalagem de tuplas # mensagem = email.mensagem_de_bytescru assunto = decodificar_str(msg)'Assunto'] ou '') remetente = decodificar_str(msg)'De'] ou '') #: Análise de partes MIME para corpo de texto simples se msg.é_multipart(): para parte em msg.andar(): se parte.obter_tipo_de_conteudo() == 'text/plain': corpo = parte.obter_payload(descodificar=Verdadeiro).decodificar('utf-8', erros='substituir') print(De: {sender} | Assunto: {subject}')

Os pontos problemáticos do imaplib: respostas de bytes brutos exigem indexação de tupla cuidadosa (dados[0][1]), cabeçalhos são codificados em RFC 2047 e precisam ser decodificar_cabeçalho(), corpos MIME multipart exigem um conjunto completo Andar(), e não há utilitários embutidos para UIDs versus números de sequência. Para cargas de trabalho de produção, considere o IMAPClient (Seção 4) ou um API IMAP unificada em vez disso.

Biblioteca de Produção

Indo Além: IMAPClient para Produção

Assim que você entra em produção com o imaplib, você percebe rapidamente sua análise de resposta frágil, tratamento inconsistente de UID e ausência de auxiliares para tarefas comuns. IMAPClient é um wrapper Pythonico que suaviza essas arestas, ao mesmo tempo em que se mantém próximo à especificação IMAP.

Por que o imaplib falha em produção
Respostas são tuplas de bytes brutos — indexação frágil de tuplas dados[0][1]
No UID-based fetching por padrão (use uid() manualmente)
Sem análise de MIME integrada ou auxiliar para extração do corpo
O IDLE requer gerenciamento manual de soquetes
A decodificação de cabeçalhos RFC 2047 é o seu problema
O que o IMAPClient te oferece
Respostas de dicionário estruturadas - sem desempacotamento de tuplas necessário
Modo UID por padrão (use_uid=True)
Faxineira buscar(), fetch(), mover(), copiar() API
Suporte embutido ao IDLE com ocioso() / idle_check()
Funciona com qualquer servidor IMAP - Gmail, Outlook, IMAP personalizado
imapclient_exemplo.py
from imapclient import IMAPClient import pprint # Conecta-se com o IMAPClient (use_uid=True por padrão) servidor = IMAPClient('imap.gmail.com', ssl=Verdadeiro, use_uid=Verdadeiro) servidor.login('user@gmail.com', 'senha-do-aplicativo') # Selecionar e pesquisar servidor.selecionar_pasta('Caixa de entrada') messages = servidor.pesquisa(['INVISÍVEL']) print({len(messages)} mensagens não lidas') # Fetch - retorna um dicionário estruturado, não bytes brutos response = servidor.fetch(mensagens[:10], ['ENVELOPE', 'BODY[]', 'BANDEIRAS']) para uid, data em resposta.itens(): envelope = dados[ENVELOPE'] print(UID {uid}: {envelope.subject}') # Mover mensagens para a pasta servidor.mover(mensagens[:5], 'Arquivo') # EM ESPERA - aguarda novas mensagens (até 29 minutos no Gmail) servidor.ocioso() respostas = servidor.verificação de ociosidade(tempo limite=60) print('Resposta ociosa:', respostas) servidor.ocioso_concluido() servidor.Sair()

Mesmo o IMAPClient requer gerenciamento manual de tokens OAuth e tratamento de múltiplos provedores. O Unipile abstrai tudo isso - renovação do OAuth, peculiaridades do provedor, reconexões de IDLE - por trás de uma única API REST. Veja nosso completo guia da API de e-mail.

Construa com Unipile
OAuth XOAUTH2

OAuth XOAUTH2 em Python: Gmail e Microsoft 365

A autenticação básica de senha está morta para os principais provedores. O Gmail a bloqueou para contas padrão desde maio de 2022. O Microsoft 365 descontinuou a autenticação básica para IMAP em setembro de 2024. O XOAUTH2 (um mecanismo SASL do OAuth 2.0) é agora a única forma em nível de produção de autenticar um cliente IMAP Python. Para a explicação completa do fluxo OAuth, veja nosso Guia da API de e-mail OAuth.

Como o XOAUTH2 funciona

XOAUTH2 é um mecanismo de autenticação SASL que codifica um token OAuth Bearer em uma string base64 com o formato: usuário={email}\x01auth=Bearer {token}\x01\x01. Esta string é passada para imaplib.IMAP4_SSL.authenticate('XOAUTH2', callback). O callback retorna a string codificada em base64. Você é responsável por obter e renovar o token de acesso OAuth por meio dos endpoints de identidade do Google ou da Microsoft antes de fazer a conexão IMAP. Para os escopos do Gmail necessários, consulte nosso Guia de escopos da API do Gmail.

Gmail Gmail
Perspectivas Microsoft 365
gmail_xoauth2.py
import imaplib, base64, json from google.oauth2.credentials import Credenciais from google.auth.transport.requests import Solicitação def construir_string_xoauth2(email_do_usuário, token_de_acesso): "Construir string SASL XOAUTH2 para autenticação IMAP." string_autenticacao = f'user={user_email}\x01auth=Bearer {access_token}\x01\x01' return base64.b64encode(auth_string.codificar('ascii')) def obter_token_válido(dicionario_de_credenciais): "Atualizar token se expirado usando a biblioteca google-auth." credenciais = Credenciais.from_authorized_user_info(dicionario_credenciais) se creds.expirado e creds.refresh_token: creds.atualizar(Solicitação()) return creds.token # Escopo IMAP necessário do Gmail: https://mail.google.com/ email_do_usuario = 'user@gmail.com' token_de_acesso = obter_token_válido(dicionario_credenciais) correio = imaplib.IMAP4_SSL('imap.gmail.com') string_autenticacao = construir_string_xoauth2(e_mail_do_usuário, token_de_acesso) correio.autenticar('XOAUTH2', lambda x: auth_string) # Agora use normalmente correio.selecionar('Caixa de entrada') _, ids = correio.pesquisa(Nenhum, 'TODOS') print(Total de mensagens: {len(ids[0].split())}')
Requisito de escopo do Gmail: O token de acesso deve ser obtido com o https://mail.google.com/ escopo (não gmail.somente leitura sozinho - esse escopo não concede acesso IMAP). Veja nossa Guia de escopos da API do Gmail para uma análise completa. Você também precisa ativar o IMAP nas configurações do Gmail e usar um ID de cliente Google Cloud OAuth 2.0 com a URI de redirecionamento correta.
outlook_xoauth2.py
import imaplib, base64 import msal def construir_string_xoauth2(email_do_usuário, token_de_acesso): string_autenticacao = f'user={user_email}\x01auth=Bearer {access_token}\x01\x01' return base64.b64encode(auth_string.codificar('ascii')) # MSAL - Biblioteca de autenticação da Microsoft para Python ID_DO_CLIENTE = 'seu-id-de-cliente-do-aplicativo-azure' ID_DO_INQUILINO = 'seu-id-de-inquilino' # Scope para acesso IMAP (Outlook / Microsoft 365) ESCOPO = ['https://outlook.office365.com/IMAP.AccessAsUser.All'] aplicativo = msal.PublicClientApplication(CLIENT_ID, autoridade=https://login.microsoftonline.com/{TENANT_ID}') # Obter token (de forma interativa ou por meio de um token de atualização) resultado = aplicativo.adquirir_token_por_codigo_autorizacao(código, escopos=ESCOPO, uri_redirecionamento=uri_redirecionamento) token_de_acesso = resultado['token_de_acesso'] #: Conecte-se ao Outlook via IMAP com XOAUTH2 email_do_usuario = 'user@outlook.com' correio = imaplib.IMAP4_SSL('outlook.office365.com') string_autenticacao = construir_string_xoauth2(e_mail_do_usuário, token_de_acesso) correio.autenticar('XOAUTH2', lambda x: auth_string) correio.selecionar('Caixa de entrada')
Observação IMAP do Microsoft 365: Desde setembro de 2024, a Microsoft desabilitou a Autenticação Básica para IMAP em todos os tenants do Microsoft 365. Você deve usar XOAUTH2. Registre um aplicativo no Azure AD, habilite a permissão "IMAP.AccessAsUser.All" e use o MSAL para aquisição de token. Para o Microsoft Graph como uma alternativa ao IMAP, consulte nosso Guia de e-mail OAuth do Microsoft Graph.

OAuth XOAUTH2 tem mais de 50 linhas por provedor. Unipile gerencia a atualização de tokens, o handshake XOAUTH2 e particularidades específicas do provedor para que seu código Python se concentre na lógica de negócios, não na infraestrutura de autenticação.

Construa seu fluxo OAuth
Matriz de Fornecedores

Verificação da Realidade Multi-Provedor

Cada provedor tem suas próprias peculiaridades de autenticação, endereços de servidor e limites de taxa. Veja o que seu cliente IMAP Python precisa lidar para cada um. Para nomes de host de servidor e detalhes de porta TLS, consulte nossa seção dedicada Guia de conexão com o servidor IMAP.

Logo do Gmail
Gmail
imap.gmail.com:993
Autenticação:XOAUTH2 necessário
Escopo:https://mail.google.com/
IDLE:Com suporte (29 min máx)
PeculiaridadesOs rótulos do Gmail correspondem a pastas IMAP. Ative o IMAP nas configurações.
Requer projeto Google Cloud com cliente OAuth 2.0. Veja Guia de escopos do Gmail para detalhes do escopo.
Logo do Outlook
Outlook / Microsoft 365
outlook.office365.com:993
Autenticação:XOAUTH2 necessário
Escopo:IMAP.AcessarComoUsuario.Todos
IDLE:Com suporte
PeculiaridadesAutenticação básica desabilitada em setembro de 2024. Azure AD app + consentimento do administrador necessário para M365.
Para uma alternativa baseada em REST ao IMAP, veja Guia de e-mail OAuth do Microsoft Graph.
Logotipo IMAP
IMAP Genérico
seu-servidor:993
Autenticação:Login/senha OK
IDLE:Varia por servidor
PeculiaridadesNomenclatura de pastas específica do servidor, AS CAPACIDADES variam, algumas não incluem IDLE.
Exemplos:Fastmail, ProtonMail Bridge, Postfix/Dovecot auto-hospedado
Cobre virtualmente qualquer servidor IMAP4rev1. Veja Guia da API IMAP para lista completa.
Yahoo Mail
imap.mail.yahoo.com:993
Autenticação:Senha de aplicativo necessária (sem XOAUTH2 para terceiros)
IDLE:Com suporte
O Yahoo desativou o suporte ao XOAUTH2 para aplicativos de terceiros. Gere uma senha específica do aplicativo nas configurações de segurança da sua conta Yahoo.
iCloud Mail
imap.mail.me.com:993
Autenticação:Senha de aplicativo necessária
IDLE:Com suporte
A Autenticação de Dois Fatores deve estar ativada no ID Apple. Gere uma senha de aplicativo em appleid.apple.com.

Apoiar múltiplos provedores significa manter fluxos de autenticação, configurações de servidor e contornos para peculiaridades separadamente. Unipile normaliza Gmail, Outlook e qualquer servidor IMAP em uma única API. Leia nosso comparativo de provedores de API de email para contexto.

Criar e-mail multi-provedor
Alternativa de API unificada

Quando pular o IMAP completamente: Abordagem de API unificada

Após percorrer imaplib, IMAPClient e XOAUTH2, uma verdade se torna clara: o IMAP bruto em Python requer centenas de linhas de código boilerplate para cada provedor que você suporta. Unipile é uma API IMAP unificada que abstrai tudo isso em uma única interface REST. Você vincula contas de usuário (Gmail, Outlook ou qualquer servidor IMAP) com OAuth, e o Unipile cuida de todos os detalhes de protocolo em seu nome.

Com imaplib puro (mais de 50 linhas por provedor)
raw_imap.py
# 1. Obter token OAuth (mais de 50 linhas) # 2. Gerar a string XOAUTH2 # 3. Conectar-se + autenticar-se # 4. Selecionar pasta # 5. Pesquisar mensagens # 6. Obter bytes brutos # 7. Analisar os dados da tupla [0][1] # 8. Decodificar cabeçalhos RFC 2047 # 9. Análise das partes MIME # 10. Acessórios para alças # 11. Gerenciar tempos limite de inatividade # 12. Reconectar em caso de erro # 13. Repita para o Outlook... # 14. Repita o procedimento para servidores IMAP...
Com a API REST da Unipile (5 linhas)
unipile_email.py
import solicitações #: Recuperar e-mails de qualquer conta vinculada r = pedidos.obter( 'https://api6.unipile.com/api/v1/emails', cabeçalhos={'X-API-KEY': chave_api}, parâmetros={'id_da_conta': id_da_conta} ) e-mails = r.json()['itens'] O # funciona com o Gmail, o Outlook e qualquer cliente IMAP
OAuth tratado para você

Unipile gerencia a aquisição, atualização e expiração de tokens XOAUTH2 para Gmail e Outlook. Nenhuma configuração MSAL ou google-auth é necessária no seu código.

Respostas JSON normalizadas

Sem bytes brutos, sem desempacotamento de tuplas, sem decodificação RFC 2047. Cada e-mail retorna como um JSON estruturado limpo com cabeçalhos, corpo e anexos analisados.

Webhooks em tempo real

Em vez de gerenciar sessões ociosas e reconexões, o Unipile envia novos eventos de e-mail para o seu endpoint de webhook. Sem polling, sem gerenciamento de socket.

Multifornecedor por padrão

Um endpoint de API atende Gmail, Outlook e qualquer servidor IMAP. Adicione novos provedores vinculando contas - sem necessidade de alterações de código da sua parte.

Envie e-mails também

Unipile cobre todo o ciclo de vida do e-mail. Leia, pesquise, mova, marque e envie – tudo da mesma API. Veja nosso Guia de envio de e-mail em Python para o lado do remetente.

Contas vinculadas por usuário

Cada um dos seus usuários vincula sua própria conta via OAuth. A Unipile atua como um intermediário técnico independente em nome de cada usuário autenticado – não um pool de credenciais compartilhado.

Armadilhas de Produção

Armadilhas Comuns na Produção

Após colocar um cliente IMAP em Python para funcionar localmente, a produção revela casos extremos que podem causar perda silenciosa de dados, interrupções de conexão ou codificação de caracteres corrompida. Aqui estão os problemas mais comuns e como resolvê-los.

2026 Mudança Significativa: Fim da Autenticação Básica IMAP da Microsoft

Microsoft concluiu a remoção da Autenticação Básica para IMAP em todos os tenants do Microsoft 365 em Setembro de 2024. Qualquer código Python usando mail.login(usuario, senha) contra outlook.office365.com receberá agora AUTENTICAÇÃO falhou. A migração para o XOAUTH2 (Seção 5) é obrigatória para todas as integrações IMAP do Microsoft 365 / Outlook. As implantações locais do Exchange podem continuar a suportar a autenticação básica, dependendo da configuração do servidor.

01
Tempo limite do IMAP IDLE (29 minutos no Gmail)

O Gmail encerra silenciosamente as conexões IDLE após aproximadamente 29 minutos. Se o seu código não renovar a sessão IDLE, as novas mensagens deixarão de chegar sem que seja gerada qualquer exceção.

Correção: Definir um cronômetro para idle_done() a cada 25 minutos, e ligue imediatamente ocioso() novamente. Use selecionar_pasta('INBOX', readonly=False) para revalidar a contagem de mensagens na reconexão.
02
Erros de decodificação de charset RFC 2047

Cabeçalhos de e-mail como Assunto e De utilizam a codificação RFC 2047 (Você está com um código de cabeçalho de e-mail inválido ou incompleto. Ele começa com "=?UTF-8?B?..." mas não tem o final apropriado. Se você puder fornecer o cabeçalho completo ou o texto que você espera que ele represente, posso te ajudar a traduzi-lo.. Chamando str(msg['Assunto']) diretamente em um valor de bytes retorna lixo ou levanta UnicodeDecodeError.

Correção: Sempre use email.header.decode_header() e trate explicitamente a codificação de cada parte. Passe erros='substituir' para .decode() para evitar travamentos em cabeçalhos malformados.
03
Análise de anexos de mensagens multipartes

Anexos vivem em partes MIME aninhadas. Chamando get_payload() em uma mensagem multipart retorna uma lista de partes, não o conteúdo. Imagens inline são Content-Disposition: inline e tenha uma ID do Conteúdo.

Correção: Atravesse todas as partes com msg.andar(), verificar get_content_disposition() para anexo, e ligar get_payload(decode=True) nas partes de anexo para obter bytes decodificados.
04
Pooling de conexões e segurança de threads

imaplib.IMAP4_SSL instâncias NÃO são thread-safe. O uso de uma conexão em várias threads causa respostas confusas. Criar uma nova conexão por solicitação é caro e limitado em taxa.

Correção: Use um pool de conexões (uma conexão por thread de trabalho) ou uma biblioteca assíncrona como aioimaplib. Sempre implemente backoff exponencial para tentativas de reconexão após IMAP4.abort exceções.
05
Limites de taxa e esgotamento de cotas

O Gmail limita as conexões IMAP a 15 conexões simultâneas por conta e impõe cotas de banda (2.500 MB/dia via IMAP). Fazer o download de corpos RFC822 inteiros em escala atingirá esses limites rapidamente.

Correção: Buscar cabeçalhos primeiro (RFC822.CABECALHO), então busque corpos seletivamente. Use BODY.PEEK[] em vez de RFC822 para evitar a marcação automática como lida. Implementar novo exponencial em [ESTOURO DE COTA] respostas.
06
Expiração do token OAuth no meio da sessão

Tokens de acesso do Google e da Microsoft expiram após 3.600 segundos (1 hora). Se sua sessão IMAP ainda estiver aberta quando o token expirar, o próximo comando após a expiração falhará silenciosamente ou retornará NÃO.

Correção: Rastrear expira_em timestamp. Antes de cada operação em lote, verifique se o token está dentro de 5 minutos da expiração e atualize proativamente. Armazene tokens de atualização de forma segura. É exatamente isso que Unipile lida automaticamente.

Evitar todas as 6 armadilhas requer infraestrutura significativa. Unipile lida com reconexões em modo ocioso, renovação de token, limitação de taxa e normalização de múltiplos provedores - assim você pode focar na lógica do seu produto. Parte da nossa completa guia da API de e-mail.

Construa sem as armadilhas
PERGUNTAS FREQUENTES

Perguntas frequentes

Perguntas comuns sobre clientes IMAP em Python, imaplib, IMAPClient, autenticação XOAUTH2 e quando usar uma API de e-mail unificada em vez disso.

01
Qual é a melhor biblioteca Python para IMAP?
Para scripts simples, imaplib da biblioteca padrão é suficiente, sem dependências. Para uso em produção, IMAPClient fornece uma API mais limpa com respostas estruturadas e suporte a IDLE integrado. Para cargas de trabalho assíncronas em escala, aioimaplib integra com asyncio. Se você precisar de suporte multi-provedor (Gmail, Outlook e servidores IMAP personalizados) com OAuth tratado automaticamente, um unificado API IMAP como o Unipile remove a maior parte da complexidade.
02
O imaplib pode ler e-mails do Gmail em Python?
Sim. Conectar a imap.gmail.com na porta 993 usando imaplib.IMAP4_SSL. No entanto, o Gmail não aceita mais login com nome de usuário/senha simples para aplicativos de terceiros. Você deve usar OAuth XOAUTH2 autenticação com um token de acesso obtido do Google usando o https://mail.google.com/ escopo. Veja nosso Guia de escopos da API do Gmail Para o detalhamento completo do escopo. Senhas de aplicativo ainda funcionam para contas pessoais com verificação em duas etapas ativada, mas o OAuth é necessário para aplicativos.
03
O que é XOAUTH2 em Python?
XOAUTH2 é um mecanismo SASL (Simple Authentication and Security Layer) usado para autenticar conexões IMAP com um token do tipo Bearer do OAuth 2.0 em vez de uma senha. Em Python, você codifica a string usuário={email}\x01auth=Bearer {token}\x01\x01 em base64, em seguida, passe para imaplib.IMAP4_SSL.authenticate('XOAUTH2', callback). Isso substitui o login Basic Auth obsoleto para Gmail e Microsoft 365. Exemplos de implementação completos estão na Seção 5 deste guia. Veja também nosso Guia da API de e-mail OAuth.
04
Como usar OAuth com imaplib?
Para usar OAuth com imaplib: 1) Obtenha um token de acesso do provedor (Google OAuth 2.0 ou Microsoft MSAL). 2) Construa a string XOAUTH2: base64(f'user={email}\x01auth=Bearer {token}\x01\x01'). 3) Chamar mail.authenticate('XOAUTH2', lambda x: auth_string). Para o Gmail, use o google-auth biblioteca para gerenciar a atualização de tokens. Para Outlook/Microsoft 365, use a msal Biblioteca Python. Ambos exigem o registro de um aplicativo OAuth no Google Cloud Console ou no Azure AD. O código completo de IMAP com OAuth em Python está na Seção 5 acima.
05
imaplib vs IMAPClient - qual devo usar?
Uso imaplib quando você precisa de zero dependências externas ou apenas um script simples de uso único. Use IMAPClient para código de produção: ele retorna dicionários estruturados em vez de tuplas de bytes brutos, usa UIDs por padrão, fornece mais limpo buscar()/fetch()/mover() métodos, e inclui suporte integrado ao IDLE. Ambos exigem que você gerencie o OAuth token por conta própria. Nenhum deles é assíncrono; para pipelines baseados em asyncio, considere aioimaplib. Instalar IMAPClient com pip install imapclient.
06
Como ler emails do Outlook com Python IMAP?
Conectar-se a outlook.office365.com na porta 993 usando imaplib.IMAP4_SSL. Desde setembro de 2024, o Basic Auth está desabilitado para o Microsoft 365 - você deve usar o XOAUTH2. Registre um aplicativo no Azure AD, solicite o IMAP.AcessarComoUsuario.Todos permissão, obter um token de acesso usando o msal Biblioteca Python, depois autenticar com mail.authenticate('XOAUTH2', ...). Para contas pessoais do Outlook.com, o mesmo fluxo OAuth se aplica. Para detalhes do servidor e configuração TLS, consulte nosso Guia de conexão com o servidor IMAP.
07
O IMAP funciona com o Microsoft 365?
Sim, o Microsoft 365 suporta IMAP em outlook.office365.com:993. No entanto, desde setembro de 2024, a Microsoft desabilitou completamente a Autenticação Básica para IMAP em tenants do Microsoft 365. Você deve usar o OAuth 2.0 com o mecanismo XOAUTH2 SASL. Seu administrador do Azure AD também pode precisar habilitar o acesso IMAP no centro de administração do Exchange. Uma alternativa é usar o API do Microsoft Graph (REST) que evita completamente o IMAP e fornece metadados mais ricos.
08
Como lidar com IMAP IDLE em Python?
IMAP IDLE permite que o servidor envie notificações quando novas mensagens chegam. Com IMAPClient: chame server.idle() para entrar no modo IDLE, então server.idle_check(timeout=60) para esperar por eventos. O Gmail desconecta silenciosamente após ~29 minutos, então você deve renovar: ligue server.idle_done() a cada 25 minutos, então server.idle() Novamente. Com imaplib puro, o IDLE exige gerenciamento manual em nível de socket – consideravelmente mais complexo. Para e-mail em tempo real de produção, uma abordagem baseada em webhook (como a que a Unipile oferece) é mais confiável do que manter sessões IDLE.
09
Posso usar IMAP assíncrono em Python?
Sim. O aioimaplib A biblioteca fornece um cliente IMAP4 compatível com asyncio para Python. Ela suporta comandos IMAP padrão e IDLE em um contexto assíncrono, tornando-a adequada para pipelines de alta concorrência onde você gerencia muitas caixas de correio simultaneamente. No entanto, aioimaplib tem uma comunidade menor do que imaplib ou IMAPClient, e o suporte ao OAuth ainda exige implementação manual do XOAUTH2. Para equipes que priorizam a velocidade do desenvolvedor em vez do controle granular, uma API unificada baseada em REST entrega e-mail em tempo real via webhooks sem gerenciamento de socket assíncrono.
10
Como o Unipile se compara ao imaplib para integração de e-mail?
imaplib é uma biblioteca padrão Python de baixo nível que requer 50-200 linhas por provedor: gerenciamento de tokens OAuth, construção de XOAUTH2, análise de bytes brutos, decodificação de cabeçalhos RFC 2047, percurso do corpo MIME, loops de reconexão IDLE. Unipile é uma API REST unificada que abstrai tudo isso em uma única chamada HTTP com respostas JSON normalizadas, OAuth integrado para Gmail e Outlook, entrega de webhooks para novos e-mails e suporte a vários provedores. O compromisso: Unipile é um serviço gerenciado com sua própria precificação, enquanto imaplib é gratuito, mas requer um investimento significativo em infraestrutura. Veja nosso completo Guia da API IMAP e comparação de provedores.

Ainda tem perguntas sobre a API IMAP em Python? Nossa equipe pode te ajudar a escolher a abordagem certa para o seu caso de uso – IMAP bruto ou API unificada.

Fale com um especialista
pt_BRBR