LinkedIn
Instagram
WhatsApp
Telegrama
Google Agenda
Participe da comunidade do SlackO que é realmente uma conexão de servidor IMAP
Uma conexão de servidor IMAP é uma sessão TCP persistente entre um cliente de e-mail e um servidor de e-mail que utiliza o Protocolo de Acesso a Mensagens da Internet (IMAP) para sincronizar, recuperar e gerenciar mensagens de e-mail armazenadas remotamente - sem baixá-las ou excluí-las do servidor.
Diferente do POP3, que foi projetado para baixar mensagens localmente e opcionalmente excluí-las do servidor, O IMAP foi criado para sincronização. Toda leitura, marcação, movimentação ou exclusão que você executa localmente é refletida no servidor - e, portanto, em todos os dispositivos conectados à mesma caixa de correio. É por isso que o IMAP se tornou o protocolo padrão para clientes de e-mail modernos.
No nível de rede, uma conexão de servidor IMAP abre um socket TCP para um servidor de e-mail (tipicamente a porta 993 para SSL/TLS ou a porta 143 para STARTTLS), realiza um handshake TLS, autentica o usuário (via senha, senha de aplicativo ou OAuth 2.0 XOAUTH2), e então entra em uma máquina de estados: Não autenticado, Autenticado, Selecionado (dentro de uma pasta de caixa de correio), ou Sair. A maioria dos comandos úteis — FETCH, SEARCH, STORE, COPY, EXPUNGE — só funciona no estado “Selecionado”.
Para desenvolvedores que criam integrações de e-mail, uma conexão com um servidor IMAP é o bloco de construção de nível mais baixo. Você a estabelece, a autentica, SELECIONA uma caixa de correio e, em seguida, consulta ou usa o modo IDLE para novas mensagens. Este guia abrange todas as etapas: o host e a porta corretos para cada provedor, o método de autenticação correto em 2026 (o OAuth é cada vez mais obrigatório) e uma referência completa de solução de problemas para os modos de falha mais comuns.
Portas IMAP explicadas: 143, 993 e quando STARTTLS é aceitável
Existem exatamente duas portas IMAP em uso ativo: 993 (TLS implícito, o padrão moderno) e 143 (atualização STARTTLS ou texto simples, que a maioria dos servidores não permite mais texto simples). Conhecer a diferença é importante porque usar a porta errada é uma das causas mais comuns de falhas de conexão ao construir uma integração IMAP.
O cliente se conecta e inicia imediatamente um handshake TLS antes que qualquer dado IMAP seja trocado. Todo o tráfego é criptografado desde o primeiro byte. Essa é a configuração padrão correta para qualquer nova integração.
O cliente se conecta em texto puro, depois emite um STARTTLS comando para atualizar para TLS. A maioria dos servidores modernos exige essa atualização e rejeita totalmente as sessões em texto simples.
Recomendação para 2026: sempre use porta 993 com SSL_CONTEXT (TLS implícito). Se você está se conectando a um servidor IMAP corporativo que expõe apenas a porta 143, ative o STARTTLS e verifique o certificado do servidor. Nunca se conecte a um servidor IMAP via texto puro em produção - as credenciais viajam em texto claro e a maioria dos provedores agora recusa tais conexões completamente.
Um breve recado sobre RFC 9051 (IMAP4rev2), publicado em agosto de 2021 como o sucessor do RFC 3501. O IMAP4rev2 exige formalmente TLS para qualquer conexão que transporte credenciais, desaprova mecanismos de autenticação baseados em MD5 e remove o LISTA-EXTENDIDA incompatibilidades que causavam bugs sutis em clientes mais antigos. A maioria dos principais provedores de nuvem (Gmail, Outlook) é compatível com IMAP4rev2 na prática há anos, mesmo antes da finalização do RFC. Para fins práticos, direcione a porta 993 + TLS e você estará em conformidade com o RFC 9051 por padrão.
Configurações de servidor e porta - Gmail, Outlook, Yahoo, iCloud, Zoho, Fastmail, AOL, ProtonMail Bridge
A tabela abaixo lista as configurações corretas de conexão do servidor IMAP para os provedores de e-mail mais utilizados. Todos os valores foram verificados na documentação oficial de cada provedor a partir de maio de 2026. Use isso como sua referência rápida ao configurar um cliente IMAP ou construir um Integração com a API IMAP.
| Fornecedor | Host IMAP | Porto | Criptografia | OAuth 2.0 (XOAUTH2) | Anotações |
|---|---|---|---|---|---|
 Gmail |
imap.gmail.com | 993 | SSL/TLS | Sim (obrigatório para novos aplicativos) |
Senhas de aplicativo funcionam, mas OAuth é fortemente preferido. Ative o IMAP nas configurações do Gmail primeiro. |
 Outlook / Microsoft 365 |
outlook.office365.com | 993 | SSL/TLS | Sim (Autenticação Básica obsoleta em Dezembro de 2026) |
Autenticação Básica fim de vida Dezembro de 2026 para todos os inquilinos. Migre para OAuth agora. |
Yahoo Mail |
imap.mail.yahoo.com | 993 | SSL/TLS | Sim |
Senha do aplicativo necessária se 2FA estiver ativado. OAuth via portal do desenvolvedor do Yahoo. |
iCloud Mail |
imap.mail.me.com | 993 | SSL/TLS | Não (somente senha de aplicativo) |
A Apple exige uma senha específica do aplicativo de appleid.apple.com. Sem suporte OAuth XOAUTH2. |
Zoho Mail |
imap.zoho.com | 993 | SSL/TLS | Sim |
OAuth via API de Contas Zoho. O IMAP deve ser ativado por caixa de correio nas configurações do Zoho Mail. |
Fastmail |
imap.fastmail.com | 993 | SSL/TLS | Sim (JMAP preferencial) |
Fastmail oferece suporte nativo ao JMAP (mais rápido que o IMAP), mas o IMAP tem suporte completo. Senhas de aplicativo disponíveis. |
AOL Mail |
imap.aol.com | 993 | SSL/TLS | Sim |
Agora parte da Yahoo Inc. Senha de aplicativo necessária se 2FA estiver habilitado. OAuth via portal do desenvolvedor do Yahoo. |
ProtonMail Bridge |
127.0.0.1 | 1143 | STARTTLS | Não (autenticação de token de ponte) |
O ProtonMail Bridge roda localmente e expõe um servidor IMAP local. Não é adequado para integrações do lado do servidor. |
IMAP Genérico |
seu-servidor-de-email.com | 993 / 143 | SSL/TLS STARTTLS | Varia (verifique a configuração do servidor) |
Dovecot, Postfix, Zimbra, Courier. Verifique a resposta CAPABILITY do seu servidor para os mecanismos de autenticação suportados. |
Gmail
Outlook / Microsoft 365
Observação sobre o ProtonMail: a arquitetura Bridge significa que as conexões IMAP do ProtonMail são viáveis apenas para configurações de desktop de um único usuário. Para integrações multi-conta ou do lado do servidor, o ProtonMail é efetivamente não suportado via IMAP padrão. Para Gmail e Outlook em escala, consulte nossos guias dedicados sobre OAuth para APIs de e-mail e API de Email do Microsoft Graph.
Passo a passo: abrindo uma conexão bruta com um servidor IMAP
Abaixo estão exemplos mínimos e funcionais de como abrir uma conexão autenticada em um servidor IMAP usando o módulo nativo do Python imaplib e Node.js com imapflow. Ambos os exemplos se conectam ao Gmail na porta 993 usando autenticação por senha de aplicativo. Para OAuth XOAUTH2, consulte H2 #7 abaixo.
import imaplib
import ssl
Configurações do servidor IMAP #
IMAP_HOST = "imap.gmail.com"
IMAP_PORTA = 993
NOME DE USUÁRIO = "you@gmail.com"
SENHA = "senha-do-seu-aplicativo" Senha do aplicativo #, não a senha da sua conta
# Criar contexto SSL (verificar certificados)
contexto = ssl.criar_contexto_padrao()
# Abrir conexão SSL na porta 993
com imaplib.IMAP4_SSL(IMAP_HOST, IMAP_PORT, ssl_context=contexto como imap:
# Autenticar
imap.login(NOME DE USUÁRIO, SENHA)
# Selecionar caixa de entrada (retorna o número de mensagens)
status, data = imap.selecionar("Caixa de entrada")
print(Caixa de entrada tem {data[0].decode()} mensagens")
#: Pesquisar mensagens ocultas
status, msg_ids = imap.pesquisa(Nenhum, "Invisível")
print(Invisível: {msg_ids[0].decode()}")
# Sair (a conexão é encerrada ao final do bloco 'with')// npm install imapflow
import { ImapFlow } from 'imapflow';
const client = new ImapFlow({
anfitrião 'imap.gmail.com',
português 993,
seguro: true, // SSL/TLS na porta 993
autenticação: {
usuário: 'you@gmail.com',
passa: 'sua-senha-de-aplicativo'
},
registrador: falso
});
await cliente.conectar();
// Bloqueia a caixa de correio INBOX para acesso exclusivo
deixar trava = await cliente.getMailboxLock('Caixa de entrada');
tentar {
// Busca as últimas 5 mensagens (somente cabeçalhos)
para await (deixar mensagem de cliente.fetch('1:5', { envelope: true })) {
console.log(msg.envelope.assunto);
}
} finalmente {
trava.soltar();
}
await cliente.Sair();O exemplo Python usa IMAP4_SSL - o wrapper SSL de nível superior que lida com o handshake TLS automaticamente. Evite usar IMAP4 + manual starttls() para provedores de nuvem, pois adiciona complexidade sem benefício. Para Node.js, imapflow é a escolha moderna baseada em Promise (a mais antiga node-imap A biblioteca está descontinuada a partir de 2024 e não suporta XOAUTH2.
Ambos os exemplos usam senhas de aplicativo, que são o tipo de credencial mais simples para testes rápidos. Para sistemas de produção que lidam com vários usuários, você precisará do OAuth 2.0 - consulte a seção XOAUTH2 abaixo. Para uma solução completa pronta para produção sem o gerenciamento de conexões IMAP brutas, consulte o Guia do desenvolvedor da API IMAP.
Pular o boilerplate do IMAP. Unipile oferece leitura, envio e sincronização entre Gmail, Outlook e IMAP em uma única API REST - sem necessidade de gerenciamento de conexão.
Pule o boilerplate do IMAP - Construa com a UnipileAutenticação: senha, senha de aplicativo e OAuth 2.0 (XOAUTH2)
Uma conexão de servidor IMAP requer que você se autentique após o handshake TLS. Existem três métodos de autenticação em uso hoje - cada um com um perfil de segurança, nível de complexidade e compatibilidade diferentes com provedores de nuvem em 2026.
O mecanismo original IMAP AUTH PLAIN / LOGIN. Você envia o endereço de e-mail da conta e a senha da conta diretamente para o servidor IMAP. Simples de implementar, mas cada vez mais bloqueado por provedores de nuvem por motivos de segurança.
Descontinuado para nuvemUm token de 16 caracteres gerado pelo provedor (Gmail, Yahoo, iCloud) que substitui a senha real da conta. Funciona com o mesmo comando IMAP LOGIN que a Autenticação Básica, mas tem escopo definido e pode ser revogado independentemente. Necessário quando a 2FA está ativada.
Aceitável para uso pessoalO usuário autoriza seu aplicativo através de uma tela de consentimento. Seu aplicativo recebe um token de acesso (curta duração, tipicamente 1 hora) que você codifica em base64 e passa para o comando IMAP AUTHENTICATE XOAUTH2. Tokens são atualizados com um token de atualização de longa duração. O único método viável para aplicativos de produção com vários usuários.
Requerido para produçãoQuando usar qual: Use senhas de aplicativo durante o desenvolvimento local e para ferramentas pessoais. Use OAuth 2.0 XOAUTH2 para qualquer integração multiusuário — é o único método que escala, pois você nunca armazena senhas de usuário e cada token pode ser revogado sem alterar a senha do usuário. Para o Gmail, o Google tem restringido progressivamente a autenticação básica para "aplicativos menos seguros" desde 2022. Para Microsoft/Outlook, a depreciação da autenticação básica está agendada para dezembro de 2026 em todos os tenants (veja a próxima seção).
Para um mergulho profundo nos fluxos OAuth - incluindo troca de tokens, lógica de renovação e escopos - consulte nosso guia em OAuth para APIs de e-mail. Para configuração do OAuth específica da Microsoft, consulte Microsoft Graph OAuth para Outlook.
O problema de 2026: Depreciação do Microsoft Basic Auth (Dezembro de 2026)
Se sua integração IMAP se conecta a contas Microsoft 365 ou Outlook usando nome de usuário e senha diretamente, você está em contagem regressiva. A Microsoft anunciou a data final de fim de vida para a Autenticação Básica em IMAP, POP3 e SMTP para todos os tenants.
De acordo com Microsoft Learn e o Anúncio do Microsoft Community Hub, O Exchange Online desativará completamente a Autenticação Básica para IMAP, POP3 e SMTP em dezembro de 2026. em todos os locatários - incluindo aqueles com isenções existentes. Qualquer cliente IMAP ou integração do lado do servidor que ainda use autenticação de nome de usuário/senha deixará de funcionar. Não há mais nenhuma extensão disponível.
Passos de ação para migrar antes do prazo
Procure em sua base de código por conexões IMAP que usam login(nome de utilizador, palavra-passe) ou AUTENTICAÇÃO PLAIN. Verifique os logs de entrada do Microsoft Entra ID (anteriormente Azure AD) para atividade de Autenticação Básica IMAP.
Crie um registro de aplicativo no portal.azure.com com o IMAP.AcessarComoUsuario.Todos (delegado) ou IMAP.AcessarComoAplicativo (aplicativo) permissão. Ver Microsoft Graph OAuth para Outlook para um guia passo a passo.
Use a MSAL (Microsoft Authentication Library) para adquirir tokens de acesso. Implemente a lógica de atualização de tokens - tokens da Microsoft expiram após 1 hora e você precisa de um fluxo de token de atualização para manter sessões IMAP de longa duração sem reautenticação do usuário.
Substitua o IMAP ENTRAR comando com AUTENTICAR XOAUTH2 usando uma string de token codificada em base64. Veja o exemplo de código completo na seção XOAUTH2 abaixo.
A Microsoft oferece uma maneira de desabilitar a autenticação básica antecipadamente em uma base por locatário - use isso para testar seu fluxo OAuth antes do corte forçado em dezembro de 2026, para que você não esteja depurando problemas de produção sob pressão de prazo.
Se você gerencia conexões IMAP para vários usuários do Microsoft 365 – um cenário comum para ferramentas de CRM, ATS ou automação de vendas – a complexidade da migração aumenta rapidamente. Você precisa lidar com fluxos de consentimento OAuth para cada usuário, armazenar e atualizar tokens com segurança, e lidar com políticas de acesso condicional que podem bloquear seu aplicativo em alguns tenants. Essa é uma das principais razões pelas quais os desenvolvedores escolhem uma API IMAP gerenciada em vez de manter conexões brutas por conta própria.
Prazo final para a Autenticação Básica da Microsoft se aproximando. Construa um fluxo OAuth à prova de futuro hoje com a API de e-mail unificada da Unipile - nós cuidamos da atualização de tokens, autenticação multi-tenant e XOAUTH2 para você.
Crie um fluxo OAuth à prova de futuroConectando via OAuth XOAUTH2
XOAUTH2 é o mecanismo SASL que permite autenticar uma conexão de servidor IMAP usando um token de acesso OAuth 2.0 em vez de uma senha. O token é obtido através do fluxo padrão de código de autorização OAuth (ou credenciais de cliente para contas de serviço), codificado em base64 em um formato específico e passado para o AUTENTICAR XOAUTH2 Comando IMAP.
Gmail (Google)Microsoft 365import imaplib, base64, json
from google.oauth2.credentials import Credenciais
from google.auth.transport.requests import Solicitação
# Carregar credenciais OAuth obtidas anteriormente
# (do fluxo do google-auth-oauthlib)
credenciais = Credenciais
token=ACCESS_TOKEN,
token_de_atualização=REFRESH_TOKEN,
token_uri="https://oauth2.googleapis.com/token",
id_cliente=CLIENT_ID,
segredo_do_cliente=CHAVE_SECRETA_DO_CLIENTE,
escopos=["https://mail.google.com/"]
)
# Atualizar o token caso tenha expirado
se creds.vencidas:
creds.atualizar(Solicitação())
# Construir string XOAUTH2: "user={email}\x01auth=Bearer {token}\x01\x01""
email_do_usuario = "user@gmail.com"
string_autenticacao = f"usuário={user_email}\x01auth=Bearer {creds.token}\x01\x01"
auth_b64 = base64.b64encode(auth_string.codificar()).decode()
# Abrir conexão IMAP e autenticar
com imaplib.IMAP4_SSL("imap.gmail.com", 993) como imap:
imap.autenticar("XOAUTH2", lambda _: auth_b64)
imap.selecionar("Caixa de entrada")
print("Conectado via XOAUTH2")import imaplib, base64
from msal import ConfidentialClientApplication
# Obter token via MSAL (fluxo de credenciais do cliente para contas de serviço)
# Para acesso delegado pelo usuário, utilize o fluxo de código de autenticação
aplicativo = ConfidentialClientApplication(
id_cliente=CLIENT_ID,
autoridade=https://login.microsoftonline.com/{TENANT_ID}",
credencial_cliente=CHAVE_SECRETA_DO_CLIENTE
)
resultado = aplicativo.adquirir_token_para_cliente(
escopos=["https://outlook.office365.com/.default"]
)
token_de_acesso = resultado["token_de_acesso"]
#: Construir a string XOAUTH2
email_do_usuario = "user@company.com"
string_autenticacao = f"usuário={user_email}\x01autenticação=Bearer {access_token}\x01\x01"
auth_b64 = base64.b64encode(auth_string.codificar()).decode()
#: Conectar ao Outlook via IMAP
com imaplib.IMAP4_SSL("outlook.office365.com", 993) como imap:
imap.autenticar("XOAUTH2", lambda _: auth_b64)
imap.selecionar("Caixa de entrada")
print("Conectado via XOAUTH2 ao Outlook")Principais diferenças entre Gmail e Microsoft XOAUTH2: O Gmail requer o https://mail.google.com/ escopo (acesso completo ao Gmail). A Microsoft exige IMAP.AcessarComoUsuario.Todos (delegado) ou IMAP.AcessarComoAplicativo (aplicativo). O formato da string XOAUTH2 base64 é idêntico para ambos os provedores: usuário={email}\x01auth=Bearer {token}\x01\x01.
Um detalhe crucial na implementação: os tokens expiram após 3600 segundos. Uma sessão IMAP IDLE de longa duração (veja a próxima seção) receberá um erro de autenticação quando o token expirar no meio da sessão. Você precisa capturar o AUTENTICAÇÃO FALHOU erro, atualize o token usando seu token de atualização e, em seguida, restabeleça a conexão IMAP. Este loop de retentativas não é trivial e é uma das principais razões pelas quais as equipes escolhem uma API gerenciada como Guia da API unificada de e-mail em vez de conexões IMAP brutas.
Para um guia completo de configuração do OAuth para a Microsoft, incluindo considerações sobre políticas de acesso condicional, consulte nosso Microsoft Graph OAuth para Outlook guia.
OAuth XOAUTH2 em 10 linhas. XOAUTH2 é um mecanismo de autenticação para OAuth 2.0. Ele permite que um cliente se autentique usando um token de acesso. O cliente envia um comando AUTH com o mecanismo "XOAUTH2". O token de acesso é enviado como um token de autenticação. O servidor valida o token de acesso e, se válido, autoriza a conexão. Evita o envio de credenciais de usuário diretamente. É comumente usado em clientes de e-mail. Simplifica o processo de autenticação para aplicações. Baseado em pares de chave-valor no campo de autenticação. Garante uma forma segura e padronizada de acesso. O Unipile lida com aquisição de tokens, atualização e reautenticação IMAP automaticamente. Você foca na leitura de e-mails, não no gerenciamento de conexões.
Crie o OAuth XOAUTH2 em 10 linhas com Unipile: 1. Importe as bibliotecas necessárias: `requests`, `json`, `base64`. 2. Defina suas credenciais: `client_id`, `client_secret`, `refresh_token`. 3. Crie uma URL para o token do Google: `url = "https://oauth2.googleapis.com/token"`. 4. Prepare os dados do corpo da requisição: `data = {"grant_type": "refresh_token", ...}`. 5. Faça a requisição POST para obter o token de acesso: `response = requests.post(url, data=data)`. 6. Verifique se a requisição foi bem-sucedida: `if response.status_code == 200:`. 7. Extraia o `access_token` da resposta. 8. Formate a string de autenticação XOAUTH2: `auth_string = "user=%s\1auth=Bearer %s\1\1" % (email, access_token)`. 9. Codifique a string em base64: `encoded_auth = base64.b64encode(auth_string.encode()).decode()`. 10. Use `encoded_auth` no cabeçalho `Authorization` de suas requisições IMAP/SMTP.IDLE, polling e notificações push: mantendo a conexão IMAP ativa
Uma vez que você tenha uma conexão autenticada com o servidor IMAP, o próximo desafio é detectar novas mensagens de forma eficiente, sem sobrecarregar o servidor com solicitações constantes. Existem três padrões em uso hoje - cada um com diferentes latências, complexidade e requisitos de infraestrutura.
| Método | Como funciona | Latência | Infraestrutura | Melhor para | Avaliação |
|---|---|---|---|---|---|
| IMAP IDLE (RFC 2177) | Problemas do cliente com o comando IDLE; o servidor envia notificações EXISTS/RECENT pela conexão TCP aberta quando um novo e-mail chega. O cliente deve enviar DONE + reenviar IDLE a cada 29 minutos (tempo limite do servidor). | ~1-5 segundos | 1 conexão TCP persistente por caixa de correio. Requer uma thread dedicada ou um loop assíncrono. | Ferramentas para usuário único, clientes desktop, monitoramento de baixa latência | Bom |
| Enquete (NOOP / CHECK) | O cliente reconecta periodicamente, emite SELECT + SEARCH UNSEEN para procurar novas mensagens, depois desconecta. Simples e sem estado. | Igual ao intervalo de votação (tipicamente 1-15 min) | Sem estado. Funciona atrás de NAT/firewalls. Sem conexão persistente. | Processamento em lote, alta latência aceitável, ambientes onde conexões persistentes são bloqueadas | Aceitável |
| Provedor de push (Gmail Pub/Sub, webhooks do MS Graph) | O provedor envia notificações HTTP para seu endpoint de webhook quando um novo e-mail chega. Nenhuma conexão IMAP é necessária em repouso. O Gmail usa Google Cloud Pub/Sub; o Microsoft usa notificações de alteração do MS Graph. | Tempo quase real ((normalmente <1 segundo) | Requer um endpoint HTTPS público e uma assinatura Pub/Sub. Nenhuma conexão IMAP persistente em repouso. | Sistemas de produção multiconkta em larga escala, arquiteturas serverless | Melhor em escala |
O IDLE é a escolha certa para integrações simples onde você controla um pequeno número de contas. Os principais problemas: você deve se reconectar antes do tempo limite de 29 minutos de IDLE (o Gmail impõe isso rigorosamente) e você precisa de conexões IMAP separadas para cada caixa de correio - o que se torna caro em centenas ou milhares de contas.
Notificações push do provedor são a arquitetura correta para sistemas multi-conta de produção. A integração Pub/Sub do Gmail e os webhooks de assinatura do Microsoft Graph entregam notificações em tempo quase real sem exigir uma conexão IMAP persistente para cada conta. A troca: você ainda precisa abrir uma conexão IMAP para buscar o corpo real da mensagem quando notificado, o que significa que seu código de conexão IMAP ainda é necessário - apenas não mantido aberto continuamente. Para ler mensagens de e-mail via API, consulte nosso guia sobre lendo e-mails via API e enviando emails via API.
Matriz de solução de problemas: timeouts, falhas de handshake, erros de autenticação, limites de taxa
Abaixo está uma referência estruturada para os erros de conexão de servidor IMAP mais comuns. Combine o sintoma (mensagem de erro ou comportamento observável) com a causa provável e a correção recomendada.
| Sintoma / Erro | Categoria | Causa Provável | Consertar |
|---|---|---|---|
| Conexão recusada na porta 993 | Conexão | Host incorreto, IMAP desativado nas configurações do provedor ou firewall bloqueando a porta 993 de saída | Verifique o host da tabela acima. Habilite o IMAP nas configurações do provedor (Gmail: Configurações > Encaminhamento e POP/IMAP). Verifique o firewall/proxy para TCP de saída 993. |
| Tempo limite de handshake SSL / CERTIFICATE_VERIFY_FAILED | TLS | Certificado expirado ou autoassinado, pacote de CA desatualizado, porta errada (143 em vez de 993) | Uso ssl.create_default_context() (Python) - Não passe ssl._create_unverified_context() em produção. Atualize seu pacote de CA (pip install certifiAguarde um momento. |
| FALHA NA AUTENTICAÇÃO / [FALHA NA AUTENTICAÇÃO] Credenciais inválidas | Autenticação | Senha errada, senha do aplicativo não gerada, 2FA ativado mas senha do aplicativo não utilizada, autenticação básica bloqueada pelo provedor | Gere uma senha de aplicativo nas configurações de segurança do provedor. Se estiver usando Gmail, certifique-se de que o "Acesso a app menos seguro" não seja o método - use senha de aplicativo ou OAuth. Para Microsoft, verifique se a autenticação básica está desabilitada para o tenant. |
| AUTENTICAR XOAUTH2 - token_invalido | OAuth | Token de acesso expirou (tokens duram 3600s), string XOAUTH2 base64 malformada, escopo incorreto | Atualize o token de acesso antes de conectar. Verifique o formato da string XOAUTH2: usuário={email}\x01auth=Bearer {token}\x01\x01. Verificação de escopo: Gmail precisa https://mail.google.com/; Outlook precisa IMAP.AcessarComoUsuario.Todos. |
| imaplib.error: comando AUTHENTICATE ilegal no estado AUTH | Estado | Tentando autenticar quando já se está no estado de Autenticado, ou após uma tentativa de autenticação falha sem redefinição | Feche e reabra a conexão IMAP antes de tentar novamente a autenticação. Nunca tente autenticação novamente na mesma conexão após uma falha. |
| Conexão IMAP cai após 29 minutos em IDLE | IDLE | Tempo limite de ociosidade imposto pelo servidor (padrão: 30 minutos por RFC 2177). O Gmail impõe 29 minutos. | Problema FEITO entre 25-27 minutos, em seguida, reemita imediatamente IDLE. Use uma thread em segundo plano ou uma tarefa assíncrona com um timer de pulso de 25 minutos. |
| [SOBRECARGA] ou Conexões simultâneas demais | Limite de Taxa | Limite de conexão imposto pelo provedor excedido. O Gmail permite 15 conexões IMAP simultâneas por conta; o Outlook varia de acordo com o plano. | Use pool de conexão. Para o Gmail: no máximo 15 conexões simultâneas por conta. Feche explicitamente as conexões ociosas.SAIR) em vez de descartar o TCP. Implemente backoff exponencial em erros de conexão. |
| NO [ALERTA] Por favor, faça login através do seu navegador web | Autenticação | Desafio de segurança do Google acionado (padrão de acesso incomum, IP novo, captcha necessário) | Faça login pelo navegador na mesma rede para limpar o desafio de segurança. Considere mudar para OAuth - o acesso por senha de aplicativo de IPs desconhecidos dispara esses desafios com mais frequência do que o OAuth. |
| TCHAU. Logout automático; ocioso por muito tempo | Conexão | Conexão IMAP em estado Autenticado (caixa de correio não selecionada) ficou inativa por muito tempo | Após a autenticação, selecione imediatamente uma caixa de correio ou emita IDLE. Implemente a lógica de reconexão ao receber BYE. |
| FETCH retorna corpo vazio / partes nulas | Protocolo | Mensagem foi expurgada entre SEARCH e FETCH, ou houve incompatibilidade de UID após nova digitalização da pasta | Sempre use BUSCAR UID (sem números de sequência) para operações multi-etapas. Lidar com Nenhum retornar valores do FETCH graciosamente. Reemitir SEARCH após uma reconexão para obter UIDs recentes. |
ssl.create_default_context() (Python) - Não passe ssl._create_unverified_context() em produção. Atualize seu pacote de CA (pip install certifiAguarde um momento.
usuário={email}\x01auth=Bearer {token}\x01\x01. Verificação de escopo: Gmail precisa https://mail.google.com/; Outlook precisa IMAP.AcessarComoUsuario.Todos.
FEITO entre 25-27 minutos, em seguida, reemita imediatamente IDLE. Use uma thread em segundo plano ou uma tarefa assíncrona com um timer de pulso de 25 minutos.
SAIR) em vez de descartar o TCP. Implemente backoff exponencial em erros de conexão.
BUSCAR UID (sem números de sequência) para operações multi-etapas. Lidar com Nenhum retornar valores do FETCH graciosamente. Reemitir SEARCH após uma reconexão para obter UIDs recentes.
Pare de depurar erros do IMAP. Unipile apresenta objetos de e-mail limpos via REST - sem máquina de estados IMAP, sem lógica de atualização de token, sem gerenciamento de pool de conexões.
Pare de depurar IMAP - Comece a construirPor que o IMAP em escala de produção é mais difícil do que parece
Abrir uma única conexão de servidor IMAP a uma caixa de entrada do Gmail são 15 linhas de Python. Escalar isso para centenas ou milhares de usuários em um produto SaaS de produção é um problema de engenharia fundamentalmente diferente. Aqui está uma análise honesta de onde as conexões IMAP brutas criam complexidade não óbvia.
Tokens de acesso expiram a cada 3600 segundos. Para 1.000 contas vinculadas, você precisa de um job em segundo plano que atualize proativamente os tokens antes da expiração, lide com a rotação de tokens de atualização (o Google os rotaciona sob certas condições) e gerencie o caso em que um usuário revoga o acesso – o que você só descobre no próximo uso do token.
Cada sessão IMAP ativa mantém um estado: caixa de correio selecionada atual, último UID visto, timer IDLE. Se o seu servidor for reiniciado, você perde todo esse estado e precisa sincronizar do zero - potencialmente buscando milhares de mensagens que você já processou. Você precisa de um armazenamento de estado persistente por conta.
Falhas transitórias (instabilidade na rede, erros 500 no servidor, respostas de limite de taxa) exigem lógica de retentativa com backoff exponencial e jitter. Loops de retentativa ingênuos sobrecarregam os provedores e resultam em banimentos temporários de IP. Você precisa de uma fila de tarefas adequada com atrasos configuráveis de retentativa e tratamento de dead-letter para contas com falha permanente.
Tokens de atualização do OAuth são credenciais de longa duração que concedem acesso completo a emails. Eles devem ser criptografados em repouso usando uma chave com suporte de KMS, controlados por acesso no nível da infraestrutura e rotacionados se houver qualquer indicação de violação. Esta é uma área de superfície de segurança significativa que requer infraestrutura adequada de gerenciamento de chaves.
O Gmail limita as conexões IMAP simultâneas a 15 por conta. Se sua aplicação abrir mais conexões do que o permitido, ela receberá erros OVERQUOTA. Ao mesmo tempo, os provedores também impõem cotas de largura de banda ao total de dados transferidos. Você precisa de pool de conexões, limitação de requisições e rastreamento de taxa por conta.
Rótulos do Gmail vs. pastas IMAP, a nomenclatura não padrão de pastas de Enviados/Excluídos do Outlook, servidores IMAP que retornam respostas CAPABILITY que não correspondem ao que eles realmente suportam e servidores que desconectam silenciosamente durante operações FETCH em anexos grandes. Cada provedor tem um conjunto exclusivo de peculiaridades que só aparecem em produção.
Isso não é um argumento contra a construção de uma integração IMAP personalizada - para uma ferramenta de provedor único e usuário único, o IMAP bruto é perfeitamente razoável. Mas para qualquer produto que precise ler e sincronizar e-mails entre vários provedores e várias contas de usuário, o overhead operacional de manter uma camada IMAP personalizada geralmente excede o custo de usar uma API de e-mail dedicada. Guia da API unificada de e-mail cobre os trade-offs arquitetônicos em detalhes.
Sincronização de e-mail de produção sem a sobrecarga do IMAP. Unipile cuida de pool de conexões, atualização de token, novas tentativas de erro e normalização de múltiplos provedores - você só precisa chamar a API.
Construa em escala sem a sobrecarga do IMAPConstruindo uma integração IMAP sem gerenciar a conexão: Unipile
Se você leu até aqui, tem uma visão clara do que é preciso para manter conexões IMAP brutas em produção: loops de atualização de token OAuth, gerenciamento de estado por conta, pooling de conexões, lógica de repetição e peculiaridades específicas do provedor para Gmail, Outlook e servidores IMAP. O Unipile abstrai toda essa camada e oferece uma única API REST para ler, enviar e sincronizar e-mails entre os três, com um quickstart de 5 minutos e menos de 10 linhas de código por operação.
Unipile gerencia todo o fluxo OAuth para Gmail e Microsoft 365: aquisição, atualização e rotação de tokens. Você nunca mexe diretamente em um token de atualização.
Uma API, um esquema de resposta. Leia e-mails de uma caixa de entrada do Gmail e de um servidor corporativo IMAP com a mesma chamada GET /emails. Sem análise específica do provedor.
Receba notificações HTTP quando novos e-mails chegarem. Sem conexão IMAP persistente para gerenciar, sem timeout IDLE de 29 minutos para lidar, sem thread dedicado por conta.
Vincule contas de usuário através do fluxo OAuth hospedado da Unipile. Cada conta vinculada recebe seu próprio account_id. Adapte de 1 a 10.000 contas vinculadas sem alterar seu código de integração.
Credenciais criptografadas em repouso com chaves suportadas pelo KMS. A Unipile possui certificação SOC 2 Tipo II e avaliação CASA Nível 2. Nenhuma senha IMAP ou tokens OAuth armazenados em seu banco de dados.
import solicitações
URL_BASE = "https://api7.unipile.com:13047/api/v1"
CABEÇALHOS = {"X-API-KEY": "sua-chave-de-api-da-unipile"}
# Etapa 1: Liste todas as contas vinculadas
contas = pedidos.obter(
f"{URL_BASE}/accounts", cabeçalhos=CABEÇALHOS
).json()
account_id = contas["itens"][0]["identificador"]
# Etapa 2: Ler os e-mails da caixa de entrada
e-mails = pedidos.obter(
f"{BASE_URL}/emails",
cabeçalhos=TÍTULOS,
parâmetros={"id_da_conta"id_da_conta, "limite": 10}
).json()
para e-mail em emails["itens"]:
print(email"assunto"], e-mail["de_participante"])
# Sem conexão IMAP, sem atualização do token,
# sem contexto SSL, sem máquina de estados.
Perguntas frequentes
Perguntas frequentes sobre conexões com servidores IMAP, portas, autenticação e migração para OAuth.
Uma conexão de servidor IMAP é uma sessão TCP persistente entre um cliente de e-mail e um servidor de e-mail que usa o Protocolo de Acesso a Mensagens da Internet para sincronizar, recuperar e gerenciar mensagens de e-mail armazenadas no servidor - sem baixá-las ou excluí-las localmente. Diferente do POP3, o IMAP mantém as mensagens no servidor e sincroniza o estado (lido, marcado, movido) entre todos os dispositivos conectados. Para desenvolvedores, é o protocolo fundamental para a criação de integrações de e-mail que funcionam em Gmail, Outlook e qualquer padrão API IMAP.
Uso porta 993 para IMAP sobre SSL/TLS (TLS implícito). Este é o padrão moderno e é exigido por todos os principais provedores de nuvem, incluindo Gmail e Outlook. A porta 143 é para atualizações STARTTLS e é apropriada apenas para servidores de e-mail auto-hospedados. Nunca se conecte a um servidor de e-mail em nuvem na porta 143 em produção - a maioria agora recusa totalmente tais conexões. Se você não tiver certeza, sempre opte pela porta 993 com ssl=True.
Sim, sem exceção. SSL/TLS é obrigatório para qualquer conexão de servidor IMAP que transmita credenciais. Servidores de e-mail modernos recusam completamente conexões em texto plano. O RFC 9051 (IMAP4rev2) exige formalmente TLS para todas as sessões autenticadas. Sempre use porta 993 com TLS implícito para provedores de nuvem. Se estiver se conectando a um servidor auto-hospedado na porta 143, você deve atualizar para TLS usando o comando STARTTLS e verificar o certificado do servidor - nunca use ssl._create_unverified_context() em produção.
O endereço do servidor IMAP para Gmail é imap.gmail.com on porta 993 com SSL/TLS. Antes de se conectar, você deve habilitar o acesso IMAP nas Configurações do Gmail em "Encaminhamento e POP/IMAP". A autenticação requer uma senha específica do aplicativo (se a 2FA estiver habilitada) ou OAuth 2.0 XOAUTH2 com o escopo https://mail.google.com/. O Google restringiu a autenticação básica para novos aplicativos e recomenda enfaticamente o OAuth para qualquer acesso programático ao IMAP.
O endereço do servidor IMAP para contas pessoais do Outlook.com e contas corporativas do Microsoft 365 é outlook.office365.com on porta 993 com SSL/TLS. Observe que a Microsoft está encerrando o suporte autenticação básica (nome de usuário/senha) para IMAP em Dezembro de 2026. Todas as integrações devem migrar para OAuth 2.0 XOAUTH2 antes desse prazo. Veja nosso Microsoft Graph OAuth para Outlook Guia de passos para migração.
Você precisa de uma senha específica para o aplicativo se sua conta tiver a autenticação de dois fatores ativada e você estiver usando autenticação básica para IMAP. Senhas de aplicativo são tokens de 16 caracteres gerados nas configurações de segurança do seu provedor (página de segurança da Conta Google para Gmail, ID Apple para iCloud) que substituem sua senha real sem conceder acesso total à conta. Para aplicativos multusuário em produção, OAuth 2.0 é fortemente preferido senhas de aplicativo - é mais seguro, não requer o armazenamento de nenhuma credencial do usuário em seu aplicativo e é o único método que permanecerá válido após a descontinuação da autenticação básica da Microsoft em dezembro de 2026.
Sim, para serviços da Microsoft. A Microsoft confirmou o fim definitivo da autenticação básica em IMAP, POP3 e SMTP no Exchange Online em Dezembro de 2026, afetando todos os inquilinos, incluindo aqueles com isenções existentes. Qualquer integração que use autenticação de nome de usuário/senha contra Outlook ou Microsoft 365 IMAP deixará de funcionar após essa data. O Google já restringiu o acesso à Autenticação Básica para o Gmail e exige senhas de aplicativo ou OAuth para qualquer acesso programático desde 2022. Se sua integração IMAP se conecta a contas Microsoft, você deve migrar para OAuth 2.0 XOAUTH2 antes de dezembro de 2026.
Para se conectar a um servidor IMAP com OAuth 2.0, você usa o mecanismo SASL XOAUTH2. Após obter um token de acesso através do fluxo padrão de código de autorização OAuth, codifique a string usuário={email}\x01auth=Bearer {token}\x01\x01 como base64, em seguida, passe-o para o AUTENTICAR XOAUTH2 Comando IMAP. Para o Gmail, o escopo necessário é https://mail.google.com/. Para o Microsoft 365, use o MSAL para adquirir um token com o IMAP.AcessarComoUsuario.Todos tokens de acesso expiram após 3600 segundos e devem ser atualizados antes de reconectar - implemente uma verificação de atualização de token antes de cada nova sessão IMAP. Veja as amostras de código completas na seção XOAUTH2 acima.
BR 
EN 
FR 
ES 
DE 
IT 
NL 
PL 
TR