LinkedIn
Instagram
WhatsApp
Telegrama
Calendario de Google
Únase a la comunidad SlackQué es realmente una conexión a un servidor IMAP
Una conexión de servidor IMAP es una sesión TCP persistente entre un cliente de correo electrónico y un servidor de correo que utiliza el Protocolo de acceso a mensajes de Internet (IMAP) para sincronizar, recuperar y administrar mensajes de correo electrónico almacenados de forma remota, sin descargarlos ni eliminarlos del servidor.
A diferencia de POP3, que fue diseñado para descargar mensajes localmente y opcionalmente eliminarlos del servidor, IMAP fue creado para la sincronización. Cada lectura, marcado, movimiento o eliminación que realizas localmente se refleja en el servidor y, por lo tanto, en todos los dispositivos conectados al mismo buzón. Por eso IMAP se convirtió en el protocolo de facto para los clientes de correo electrónico modernos.
A nivel de red, una conexión de servidor IMAP abre un socket TCP a un servidor de correo (típicamente el puerto 993 para SSL/TLS o el puerto 143 para STARTTLS), realiza un handshake TLS, autentica al usuario (mediante contraseña, contraseña de aplicación u OAuth 2.0 XOAUTH2), y luego ingresa a una máquina de estados: No autenticado, Autenticado, Seleccionado (dentro de una carpeta de buzón), o Cerrar sesión. La mayoría de los comandos útiles (FETCH, SEARCH, STORE, COPY, EXPUNGE) solo funcionan en el estado Seleccionado.
Para los desarrolladores que crean integraciones de correo electrónico, una conexión de servidor IMAP es el bloque de construcción de nivel más bajo. La estableces, la autenticas, SELECCIONAS un buzón y luego encuestas o usas IDLE para los mensajes nuevos. Esta guía cubre cada paso: el host y puerto correctos para cada proveedor, el método de autenticación correcto en 2026 (OAuth es cada vez más obligatorio) y una referencia completa de solución de problemas para los modos de falla más comunes.
Puertos IMAP explicados: 143, 993 y cuándo STARTTLS está OK
Hay exactamente dos puertos IMAP en uso activo: 993 (TLS implícito, el estándar moderno) y 143 (actualización STARTTLS o texto plano, que la mayoría de los servidores ya no permiten texto plano). Conocer la diferencia es importante porque usar el puerto incorrecto es una de las causas más comunes de fallos de conexión al crear una integración IMAP.
El cliente se conecta e inicia inmediatamente un handshake TLS antes de intercambiar cualquier dato IMAP. Todo el tráfico está cifrado desde el primer byte. Esta es la configuración predeterminada correcta para cualquier integración nueva.
El cliente se conecta en texto plano, luego emite un STARTTLS comando para actualizar a TLS. La mayoría de los servidores modernos requieren esta actualización y rechazan por completo las sesiones de texto plano.
2026 recomendación: siempre usar puerto 993 con SSL_CONTEXT (TLS implícito). Si estás compilando contra un servidor IMAP corporativo que solo expone el puerto 143, habilita STARTTLS y verifica el certificado del servidor. Nunca te conectes a un servidor IMAP a través de texto plano en producción: las credenciales viajan en texto plano y la mayoría de los proveedores ahora rechazan tales conexiones directamente.
Una breve nota sobre RFC 9051 (IMAP4rev2), publicado en agosto de 2021 como sucesor de RFC 3501. IMAP4rev2 requiere formalmente TLS para cualquier conexión que transporte credenciales, deprecia los mecanismos de autenticación basados en MD5 y elimina el LISTA-EXTENDIDA incompatibilidades que causaron errores sutiles en clientes más antiguos. La mayoría de los principales proveedores de servicios en la nube (Gmail, Outlook) han sido compatibles con IMAP4rev2 en la práctica durante años, incluso antes de que se finalizara el RFC. Para fines prácticos, apunte al puerto 993 + TLS y cumplirá con RFC 9051 por defecto.
Tabla de configuración de host y puerto - Gmail, Outlook, Yahoo, iCloud, Zoho, Fastmail, AOL, ProtonMail Bridge
La tabla a continuación enumera la configuración correcta del servidor IMAP para los proveedores de correo electrónico más utilizados. Todos los valores han sido verificados con la documentación oficial de cada proveedor a partir de mayo de 2026. Utilice esto como su referencia rápida al configurar un cliente IMAP o al crear una Integración de API IMAP.
| Proveedor | Host IMAP | Puerto | Cifrado | OAuth 2.0 (XOAUTH2) | Notas |
|---|---|---|---|---|---|
 Gmail |
imap.gmail.com | 993 | SSL/TLS | Sí (requerido para aplicaciones nuevas) |
Las contraseñas de aplicación funcionan, pero se prefiere OAuth. Habilita IMAP en la configuración de Gmail primero. |
 Outlook / Microsoft 365 |
outlook.office365.com | 993 | SSL/TLS | Sí (Basic Auth obsoleto en dic. de 2026) |
Autenticación básica fin de vida útil diciembre de 2026 para todos los inquilinos. Migra a OAuth ahora. |
Yahoo Mail |
imap.mail.yahoo.com | 993 | SSL/TLS | Sí |
Se requiere una contraseña de aplicación si la autenticación de dos factores está activada. OAuth a través del portal de desarrolladores de Yahoo. |
iCloud Correo |
imap.mail.me.com | 993 | SSL/TLS | No (solo contraseña de aplicación) |
Apple requiere una contraseña específica de la aplicación desde appleid.apple.com. No hay soporte OAuth XOAUTH2. |
Zoho Mail |
imap.zoho.com | 993 | SSL/TLS | Sí |
OAuth a través de Zoho Accounts API. IMAP debe estar habilitado por buzón en la configuración de Zoho Mail. |
Fastmail |
imap.fastmail.com | 993 | SSL/TLS | Sí (preferible JMAP) |
Fastmail soporta JMAP de forma nativa (más rápido que IMAP) pero IMAP está totalmente soportado. Contraseñas de aplicación disponibles. |
AOL Mail |
imap.aol.com | 993 | SSL/TLS | Sí |
Ahora parte de Yahoo Inc. Se requiere contraseña de aplicación si la autenticación de dos factores (2FA) está habilitada. OAuth a través del portal de desarrolladores de Yahoo. |
ProtonMail Bridge |
127.0.0.1 | 1143 | STARTTLS | No (autorización de token de puente) |
ProtonMail Bridge se ejecuta localmente y expone un servidor IMAP local. No es adecuado para integraciones del lado del servidor. |
IMAP genérico |
tu-servidor-de-correo.com | 993 / 143 | SSL/TLS STARTTLS | Varía (comprobar configuración del servidor) |
Dovecot, Postfix, Zimbra, Courier. Consulta la respuesta CAPABILITY de tu servidor para ver los mecanismos de autenticación compatibles. |
Gmail
Outlook / Microsoft 365
Nota sobre ProtonMail: la arquitectura Bridge significa que las conexiones IMAP de ProtonMail solo son viables para configuraciones de escritorio de un solo usuario. Para integraciones multicuenta o del lado del servidor, ProtonMail no tiene soporte efectivo a través de IMAP estándar. Para Gmail y Outlook a escala, consulte nuestras guías dedicadas sobre OAuth para APIs de correo electrónico y Microsoft Graph API Correo electrónico.
Paso a paso: abrir una conexión de servidor IMAP sin procesar
A continuación se presentan ejemplos mínimos y funcionales de cómo abrir una conexión a un servidor IMAP autenticado usando la biblioteca integrada de Python imaplib y Node.js con imapflow. Ambos ejemplos se conectan a Gmail en el puerto 993 mediante autenticación con contraseña de aplicación. Para obtener información sobre OAuth XOAUTH2, consulta la sección H2 #7 más abajo.
import imaplib
import ssl
Configuración del servidor IMAP de #
IMAP_HOST = "imap.gmail.com"
IMAP_PUERTO = 993
NOMBRE DE USUARIO = "you@gmail.com"
CONTRASEÑA = "tu-contraseña-de-aplicación" La contraseña de la aplicación #, no la contraseña de tu cuenta
# Crear contexto SSL (verificar certificados)
contexto = ssl.crear_contexto_predeterminado()
#: Abre una conexión SSL en el puerto 993
con imaplib.IMAP4_SSL(IMAP_HOST, IMAP_PORT, ssl_context=contexto como imap:
# Autenticación
imap.ingresar(NOMBRE DE USUARIO, CONTRASEÑA)
# Seleccionar bandeja de entrada (muestra el número de mensajes)
estado, datos = imap.elegir("Bandeja de entrada")
print(La bandeja de entrada tiene {data[0].decode()} mensajes")
#: En busca de mensajes ocultos
estado, ids_mensajes = imap.busque en(Ninguno, "INÉDITO")
print(No visto: {msg_ids[0].decode()}")
# Cerrar sesión (la conexión se cierra al final del bloque 'with')npm install imapflow
import { ImapFlow } from 'imapflow';
const client = new ImapFlow({
anfitrión 'imap.gmail.com',
puerto 993,
seguro true, // SSL/TLS en el puerto 993
autenticación: {
usuario: 'you@gmail.com',
pasar 'tu-contraseña-de-aplicación'
},
registrador falso
});
await cliente.conectar();
// Bloquear el buzón de BZDN para acceso exclusivo
dejar cerradura = await cliente.BloquearBuzon('BANDEJA DE ENTRADA');
intentar {
// Recuperar los últimos 5 mensajes (solo encabezados)
para await (dejar msj de cliente.fetch('1:5', { sobre: true })) {
consola.log(msg.envelope.asunto);
}
} finalmente {
candado.liberar();
}
await cliente.cerrar sesión();El ejemplo de Python utiliza IMAP4_SSL - el wrapper SSL de nivel superior que maneja el handshake TLS automáticamente. Evita usar IMAP4 + manual starttls() para proveedores de nube, ya que agrega complejidad sin beneficio. Para Node.js, imapflow es la opción moderna, basada en Promises (la antigua node-imap la biblioteca no se mantiene activamente a partir de 2024 y no admite XOAUTH2).
Ambos ejemplos utilizan contraseñas de aplicación, que son el tipo de credencial más sencillo para pruebas rápidas. Para sistemas de producción que manejan varios usuarios, necesitará OAuth 2.0; consulte la sección XOAUTH2 a continuación. Para una solución completa lista para producción sin gestionar conexiones IMAP en bruto, consulte Guía del desarrollador de la API IMAP.
Omite el preámbulo de IMAP. Unipile te permite leer, enviar y sincronizar entre Gmail, Outlook e IMAP en una única API REST, sin necesidad de gestión de conexiones.
Omite lo básico de IMAP: créalo con UnipileAutenticación: contraseña, contraseña de aplicación y OAuth 2.0 (XOAUTH2)
Una conexión al servidor IMAP requiere que te autentiques después del handshake TLS. Hay tres métodos de autenticación en uso hoy en día, cada uno con un perfil de seguridad, nivel de complejidad y compatibilidad diferentes con los proveedores de la nube en 2026.
El mecanismo original IMAP AUTH PLAIN / LOGIN. Envía la dirección de correo electrónico de la cuenta y la contraseña de la cuenta directamente al servidor IMAP. Fácil de implementar pero cada vez más bloqueado por los proveedores en la nube por motivos de seguridad.
Obsoleto para la nubeUn token de 16 caracteres generado por el proveedor (Gmail, Yahoo, iCloud) que sustituye la contraseña real de la cuenta. Funciona con el mismo comando IMAP LOGIN que Basic Auth, pero tiene un alcance limitado y se puede revocar de forma independiente. Se requiere cuando la autenticación de dos factores (2FA) está habilitada.
Aceptable para uso personalEl usuario autoriza tu aplicación a través de una pantalla de consentimiento. Tu aplicación recibe un token de acceso (de corta duración, típicamente 1 hora) que codificas en base64 y pasas al comando IMAP AUTHENTICATE XOAUTH2. Los tokens se actualizan con un token de actualización de larga duración. El único método viable para aplicaciones de producción multiusuario.
Requerido para producciónCuándo usar cada uno: utilice contraseñas de aplicaciones durante el desarrollo local y para herramientas personales. Utilice OAuth 2.0 XOAUTH2 para cualquier integración multiusuario: es el único método que escala, ya que nunca almacena contraseñas de usuario, y cada token se puede revocar sin cambiar la contraseña del usuario. Para Gmail, Google ha estado restringiendo progresivamente la autenticación básica para "aplicaciones menos seguras" desde 2022. Para Microsoft/Outlook, la depreciación de la autenticación básica está programada para diciembre de 2026 en todos los inquilinos (consulte la siguiente sección).
Para una inmersión profunda en los flujos de OAuth-incluyendo el intercambio de tokens, la lógica de actualización y los alcances-consulta nuestra guía en OAuth para APIs de correo electrónico. Para la configuración de OAuth específica de Microsoft, consulta Microsoft Graph OAuth para Outlook.
El problema de 2026: Desaprobación de la autenticación básica de Microsoft (diciembre de 2026)
Si su integración IMAP se conecta a cuentas de Microsoft 365 u Outlook utilizando un nombre de usuario y contraseña directamente, está en cuenta regresiva. Microsoft ha anunciado la fecha final de fin de vida útil para la autenticación básica en IMAP, POP3 y SMTP para todos los inquilinos.
Según Microsoft Learn y el Anuncio de Microsoft Community Hub, Exchange Online deshabilitará por completo la autenticación básica para IMAP, POP3 y SMTP en diciembre de 2026 en todos los inquilinos, incluidos aquellos con exenciones existentes. Cualquier cliente IMAP o integración del lado del servidor que todavía utilice la autenticación de nombre de usuario/contraseña dejará de funcionar. No hay ninguna extensión adicional disponible.
Pasos a seguir para migrar antes de la fecha límite
Buscar en su base de código las conexiones IMAP que utilizan iniciar_sesion(nombre_usuario, contraseña) o AUTENTICACIÓN PLANA. Revisa los registros de inicio de sesión de Microsoft Entra ID (anteriormente Azure AD) en busca de actividad de autenticación básica IMAP.
Crea un registro de aplicación en portal.azure.com con IMAP.AccesoComoUsuario.Todos (delegado) o IMAP.AccesoComoAplicación (aplicación) permiso. Ver Microsoft Graph OAuth para Outlook para un recorrido paso a paso.
Utilice MSAL (Microsoft Authentication Library) para adquirir tokens de acceso. Implemente la lógica de actualización de tokens: los tokens de Microsoft caducan después de 1 hora y necesita un flujo de token de actualización para mantener sesiones IMAP de larga duración sin la reautenticación del usuario.
Reemplazar el IMAP INICIAR SESIÓN comando con AUTENTICAR XOAUTH2 usando una cadena de token codificada en base64. Vea la muestra de código completa en la sección XOAUTH2 a continuación.
Microsoft ofrece una forma de deshabilitar la autenticación básica anticipadamente en cada inquilino. Utiliza esto para probar tu flujo de OAuth antes de la fecha límite forzada de diciembre de 2026, para que no estés depurando problemas de producción bajo presión.
Si gestiona conexiones IMAP para varios usuarios de Microsoft 365, un escenario común para herramientas de CRM, ATS o automatización de ventas, la complejidad de la migración se multiplica rápidamente. Necesita manejar flujos de consentimiento de OAuth para cada usuario, almacenar y actualizar tokens de forma segura, y lidiar con políticas de acceso condicional que pueden bloquear su aplicación en algunos inquilinos. Esta es una de las razones fundamentales por las que los desarrolladores eligen una API IMAP administrada en lugar de mantener conexiones directas por sí mismos.
La fecha límite para la autenticación básica de Microsoft se acerca. Construye hoy un flujo OAuth a prueba de futuro con la API unificada de correo electrónico de Unipile: nos encargamos del refresco de tokens, la autenticación multi-inquilino y XOAUTH2 por ti.
Diseñar un flujo de OAuth a prueba de futuroConexión mediante OAuth XOAUTH2
XOAUTH2 es el mecanismo SASL que permite autenticar una conexión a un servidor IMAP utilizando un token de acceso OAuth 2.0 en lugar de una contraseña. El token se obtiene a través del flujo estándar de código de autorización OAuth (o credenciales de cliente para cuentas de servicio), se codifica en base64 en un formato específico y se pasa al AUTENTICAR XOAUTH2 Comando IMAP.
Gmail (Google)Microsoft 365import imaplib, base64, json
from google.oauth2.credenciales import Credenciales
from google.auth.transport.requests import Solicitud
#: Cargar las credenciales OAuth obtenidas anteriormente
# (del flujo de google-auth-oauthlib)
acreditaciones = Credenciales
ficha=TOKEN_DE_ACCESO,
token de actualización=REFRESH_TOKEN,
token_uri="https://oauth2.googleapis.com/token",
client_id=ID_DEL_CLIENTE,
secreto_cliente=SECRETO_DEL_CLIENTE,
ámbitos=["https://mail.google.com/"]
)
#: Token de actualización si ha caducado
si créditos.expirados:
créditos.actualizar(Solicitud())
# Generar cadena XOAUTH2: "user={email}\x01auth=Bearer {token}\x01\x01"
correo_electronico_del_usuario = "user@gmail.com"
cadena_autenticación = f"user={user_email}\x01auth=Bearer {creds.token}\x01\x01"
auth_b64 = base64.b64encode(cadena_autenticacion.codificar()).decodificar()
#: Abrir conexión IMAP y autenticarse
con imaplib.IMAP4_SSL("imap.gmail.com", 993) como imap:
imap.autenticar("XOAUTH2", lambda _: auth_base64)
imap.elegir("Bandeja de entrada")
print("Conectado vía XOAUTH2")import imaplib, base64
from msal import ConfidentialClientApplication
# Obtener un token mediante MSAL (flujo de credenciales de cliente para cuentas de servicio)
#: Para el acceso delegado por el usuario, utilice en su lugar el flujo de código de autenticación
aplicación = ConfidentialClientApplication(
client_id=ID_DEL_CLIENTE,
autoridad=https://login.microsoftonline.com/{TENANT_ID}",
credencial_cliente=SECRETO_CLIENTE
)
resultado = aplicación.adquirir_token_para_cliente(
ámbitos=["https://outlook.office365.com/.default"]
)
token_de_acceso = resultado ["token_de_acceso"]
#: Crear cadena XOAUTH2
correo_electronico_del_usuario = "user@company.com"
cadena_autenticación = f"usuario={user_email}\x01auth=Bearer {access_token}\x01\x01"
auth_b64 = base64.b64encode(cadena_autenticacion.codificar()).decodificar()
#: Conexión a Outlook mediante IMAP
con imaplib.IMAP4_SSL("outlook.office365.com", 993) como imap:
imap.autenticar("XOAUTH2", lambda _: auth_base64)
imap.elegir("Bandeja de entrada")
print("Conectado vía XOAUTH2 a Outlook")Diferencias clave entre Gmail y Microsoft XOAUTH2: Gmail requiere el https://mail.google.com/ alcance (acceso completo a Gmail). Microsoft requiere IMAP.AccesoComoUsuario.Todos (delegado) o IMAP.AccesoComoAplicación (aplicación). El formato de cadena XOAUTH2 base64 es idéntico para ambos proveedores: usuario={email}\x01autenticación=Bearer {token}\x01\x01.
Un detalle crítico de implementación: los tokens expiran después de 3600 segundos. Una sesión prolongada de IMAP IDLE (ver la siguiente sección) recibirá un error de autenticación cuando el token expire a mitad de sesión. Necesitas capturar el AUTENTICACIÓN FALLIDA error, actualiza el token usando tu token de actualización, luego restablece la conexión IMAP. Este bucle de reintento no es trivial y es una razón principal por la que los equipos eligen una API administrada como Guía de la API unificada de correo electrónico en lugar de conexiones IMAP directas.
Para una guía completa de configuración de OAuth para Microsoft, incluyendo consideraciones sobre políticas de acceso condicional, consulte nuestra Microsoft Graph OAuth para Outlook guía.
OAuth XOAUTH2 en 10 líneas. Es un protocolo de autenticación. Permite a las aplicaciones acceder a recursos en nombre de un usuario. Sin necesidad de compartir las credenciales del usuario. Funciona con un token de acceso. El cliente obtiene un token del servidor de autorización. Luego presenta este token al servidor de recursos. XOAUTH2 se usa comúnmente para correo electrónico (IMAP, POP3, SMTP). Es más seguro que la autenticación básica (nombre de usuario y contraseña). Utiliza la codificación Base64 para codificar las credenciales. Requiere la autenticación de un servidor de autorización externo. Unipile maneja la adquisición de tokens, la actualización y la reautenticación IMAP automáticamente. Concéntrate en leer correos electrónicos, no en la gestión de conexiones.
Crea OAuth XOAUTH2 en 10 líneas con Unipile 1. Usa el SDK de Unipile para incializar la autenticación. 2. Define los ámbitos de acceso deseados para tus solicitudes. 3. Inicia el flujo de autorización OAuth 2.0. 4. El usuario autoriza tu aplicación. 5. Captura el código de autorización devuelto. 6. Intercambia el código por un token de acceso y un token de actualización. 7. Almacena de forma segura los tokens. 8. Utiliza el token de acceso para autenticar las solicitudes a la API. 9. Refresca el token de acceso usando el token de actualización cuando expire. 10. Implementa manejo de errores para todas las etapas del proceso.IDLE, sondeos y notificaciones push: manteniendo viva la conexión IMAP
Una vez que tenga una conexión autenticada con el servidor IMAP, el siguiente desafío es detectar nuevos mensajes de manera eficiente sin sobrecargar el servidor con solicitudes constantes. Hay tres patrones en uso hoy en día, cada uno con diferentes latencia, complejidad y requisitos de infraestructura.
| Método | Cómo funciona | Latencia | Infraestructura | Mejor para | Calificación |
|---|---|---|---|---|---|
| IMAP IDLE (RFC 2177) | El cliente envía un comando IDLE; el servidor envía notificaciones EXISTS/RECENT a través de la conexión TCP abierta cuando llega correo nuevo. El cliente debe enviar DONE + reemitir IDLE cada 29 minutos (tiempo de espera del servidor). | ~1-5 segundos | 1 conexión TCP persistente por buzón. Requiere un hilo dedicado o un bucle asíncrono. | Herramientas de usuario único, clientes de escritorio, monitorización con baja latencia | Bien |
| Sondeo (NOOP / COMPROBAR) | El cliente se reconecta periódicamente, emite SELECT + SEARCH UNSEEN para buscar nuevos mensajes, luego se desconecta. Simple y sin estado. | Igual al intervalo de sondeo (normalmente 1-15 min) | Sin estado. Funciona detrás de NAT/firewalls. Sin conexión persistente. | Procesamiento por lotes, latencia alta aceptable, entornos donde las conexiones persistentes están bloqueadas | Aceptable |
| Notificación del proveedor (Gmail Pub/Sub, webhooks de MS Graph) | El proveedor envía una notificación HTTP a tu endpoint de webhook cuando llega un nuevo correo electrónico. No se necesita conexión IMAP en reposo. Gmail usa Google Cloud Pub/Sub; Microsoft usa notificaciones de cambio de MS Graph. | Casi en tiempo real(típicamente <1 segundo) | Requiere un punto final HTTPS público y una suscripción a Pub/Sub. No hay conexión IMAP persistente en reposo. | Sistemas de producción multicuenta a gran escala, arquitecturas sin servidor | Mejor a escala |
IDLE es la opción correcta para integraciones sencillas donde controlas un pequeño número de cuentas. Los principales inconvenientes: debes reconectarte antes de que expire el tiempo de inactividad (IDLE) de 29 minutos (Gmail lo aplica estrictamente), y necesitas conexiones IMAP separadas para cada buzón, lo que resulta caro con cientos o miles de cuentas.
Notificaciones push del proveedor son la arquitectura correcta para sistemas de múltiples cuentas en producción. La integración de Pub/Sub de Gmail y los webhooks de suscripción de Microsoft Graph entregan notificaciones en tiempo casi real sin requerir una conexión IMAP persistente para cada cuenta. La contrapartida: aún necesitará abrir una conexión IMAP para recuperar el cuerpo del mensaje real cuando reciba la notificación, lo que significa que su código de conexión IMAP aún es necesario, solo que no se mantiene abierto continuamente. Para leer mensajes de correo electrónico a través de la API, consulte nuestra guía sobre leer correos electrónicos a través de la API y enviar correos electrónicos a través de API.
Matriz de solución de problemas: tiempos de espera, fallos de handshake, errores de autenticación, límites de tasa
A continuación, se presenta una referencia estructurada para los errores de conexión del servidor IMAP más comunes. Relacione el síntoma (mensaje de error o comportamiento observable) con la causa probable y la solución recomendada.
| Síntoma / Error | Categoría | Causa probable | Arregla |
|---|---|---|---|
| Conexión rechazada en el puerto 993 | Conexión | Host incorrecto, IMAP deshabilitado en la configuración del proveedor o el cortafuegos bloquea la conexión saliente a través del puerto 993. | Verifica el host de la tabla anterior. Habilita IMAP en la configuración del proveedor (Gmail: Configuración > Reenvío y POP/IMAP). Comprueba el firewall/proxy para el TCP de salida 993. |
| Tiempo de espera de enlace SSL / CERTIFICATE_VERIFY_FAILED | TLS | Certificado expirado o autofirmado, paquete de CA desactualizado, puerto incorrecto (143 en lugar de 993) | Utilice ssl.create_default_context() (Python) - no pasar ssl._create_unverified_context() en producción. Actualice su paquete de CApip install certifi. Confirma que te estás conectando al puerto 993. |
| AUTENTICACIÓNFALLIDA / [AUTENTICACIÓNFALLIDA] Credenciales inválidas | Aut | Contraseña incorrecta, contraseña de aplicación no generada, 2FA activado pero no se usó contraseña de aplicación, Autenticación Básica bloqueada por el proveedor | Genera una contraseña de aplicación específica desde la configuración de seguridad del proveedor. Si usas Gmail, asegúrate de que "Acceso de aplicaciones menos seguras" no sea el método; usa contraseña de aplicación u OAuth. Para Microsoft, verifica si la autenticación básica está deshabilitada para el inquilino. |
| AUTENTICAR XOAUTH2 - token_inválido | OAuth | Token de acceso expirado (los tokens duran 3600s), cadena XOAUTH2 base64 mal formada, ámbito incorrecto | Actualiza el token de acceso antes de conectarte. Verifica el formato de la cadena XOAUTH2: usuario={email}\x01autenticación=Bearer {token}\x01\x01. Verifica el alcance: Gmail necesita https://mail.google.com/; Outlook necesita IMAP.AccesoComoUsuario.Todos. |
| imaplib.error: error de comando AUTHENTICATE ilegal en estado AUTH | Estado | Intentando autenticarse cuando ya se está en estado autenticado, o después de un intento de autenticación fallido sin restablecer. | Cierra y vuelve a abrir la conexión IMAP antes de reintentar la autenticación. Nunca reintentes la autenticación en la misma conexión después de un fallo. |
| La conexión IMAP se interrumpe después de 29 minutos de IDLE | Ocioso | Tiempo de espera inactivo impuesto por el servidor (estándar: 30 minutos según RFC 2177). Gmail impone 29 minutos. | Problema HECHO entre los minutos 25 y 27, luego emitir inmediatamente de nuevo Ocioso. Utilice un hilo en segundo plano o una tarea asíncrona con un temporizador de latido de 25 minutos. |
| [SOBREPASADA LA CUOTA] o demasiadas conexiones simultáneas | Límite de Tasa | Se ha superado el límite de conexión impuesto por el proveedor. Gmail permite 15 conexiones IMAP simultáneas por cuenta; Outlook varía según el plan. | Use pool de conexiones. Para Gmail: máximo 15 conexiones concurrentes por cuenta. Cierre explícitamente las conexiones inactivas (CERRAR SESIÓNen lugar de abandonar TCP. Implemente retroceso exponencial en errores de conexión. |
| NO [ALERTA] Inicie sesión a través de su navegador web | Aut | Desafío de seguridad de Google activado (patrón de acceso inusual, IP nueva, se requiere captcha) | Inicia sesión a través del navegador desde la misma red para resolver el desafío de seguridad. Considera cambiar a OAuth: el acceso a la contraseña de la aplicación desde IPs desconocidas activa estos desafíos con más frecuencia que OAuth. |
| ADIÓS Cierre de sesión automático; inactivo durante demasiado tiempo | Conexión | Conexión IMAP en estado Autenticado (buzón no seleccionado) estuvo inactiva demasiado tiempo | Después de la autenticación, selecciona inmediatamente un buzón de correo o emite IDLE. Implementa lógica de reconexión cuando recibas BYE. |
| FETCH devuelve cuerpo vacío / partes nulas | Protocolo | Mensaje borrado entre BUSCAR y OBTENER, o falta de coincidencia de UID después de un reescaneo de carpeta | Siempre usa UID FETCH (sin números de secuencia) para operaciones de varios pasos. Manejar Ninguno Devuelve los valores de FETCH de forma elegante. Vuelve a emitir SEARCH después de una reconexión para obtener UIDs nuevos. |
ssl.create_default_context() (Python) - no pasar ssl._create_unverified_context() en producción. Actualice su paquete de CApip install certifi. Confirma que te estás conectando al puerto 993.
usuario={email}\x01autenticación=Bearer {token}\x01\x01. Verifica el alcance: Gmail necesita https://mail.google.com/; Outlook necesita IMAP.AccesoComoUsuario.Todos.
HECHO entre los minutos 25 y 27, luego emitir inmediatamente de nuevo Ocioso. Utilice un hilo en segundo plano o una tarea asíncrona con un temporizador de latido de 25 minutos.
CERRAR SESIÓNen lugar de abandonar TCP. Implemente retroceso exponencial en errores de conexión.
UID FETCH (sin números de secuencia) para operaciones de varios pasos. Manejar Ninguno Devuelve los valores de FETCH de forma elegante. Vuelve a emitir SEARCH después de una reconexión para obtener UIDs nuevos.
Deja de depurar errores de IMAP. Unipile expone objetos de correo electrónico limpios a través de REST: sin máquina de estados IMAP, sin lógica de actualización de tokens, sin pooling de conexiones que administrar.
Deja de depurar IMAP - Empieza a construirPor qué la IMAP en producción a gran escala es más difícil de lo que parece
Abrir una única conexión IMAP a una bandeja de entrada de Gmail son 15 líneas de Python. Escalar eso a cientos o miles de usuarios en un producto SaaS de producción es un problema de ingeniería fundamentalmente diferente. Aquí hay un desglose honesto de dónde las conexiones IMAP en bruto crean complejidad no obvia.
Los tokens de acceso caducan cada 3600 segundos. Para 1000 cuentas vinculadas, necesitas un trabajo en segundo plano que actualice proactivamente los tokens antes de que expiren, maneje la rotación de tokens de actualización (Google los rota bajo ciertas condiciones) y gestione el caso en que un usuario revoque el acceso, lo cual solo descubres en el próximo uso del token.
Cada sesión IMAP activa mantiene un estado: buzón seleccionado actual, UID visto por última vez, temporizador IDLE. Si su servidor se reinicia, pierde todo este estado y debe volver a sincronizar desde cero, potencialmente recuperando miles de mensajes que ya ha procesado. Necesita un almacén de estado persistente por cuenta.
Los fallos transitorios (interrupciones de red, errores 500 del servidor, respuestas de limitación de velocidad) requieren lógica de reintento con retroceso exponencial y jitter. Los bucles de reintento ingenuos bombardean a los proveedores y resultan en prohibiciones temporales de IP. Necesitas una cola de trabajos adecuada con retrasos de reintento configurables y gestión de "dead-letter" para cuentas fallidas permanentemente.
Las tokens de actualización de OAuth son credenciales de larga duración que otorgan acceso completo al correo electrónico. Deben cifrarse en reposo utilizando una clave respaldada por KMS, controlarse el acceso a nivel de infraestructura y rotarse si hay alguna indicación de una brecha. Esta es un área de superficie de seguridad significativa que requiere una infraestructura de administración de claves adecuada.
Gmail limita las conexiones IMAP simultáneas a 15 por cuenta. Si su aplicación abre más conexiones de las permitidas, recibirá errores OVERQUOTA. Al mismo tiempo, los proveedores también imponen cuotas de ancho de banda sobre la totalidad de los datos transferidos. Necesita agrupación de conexiones, limitación de solicitudes y seguimiento de la tasa por cuenta.
Marcadores de Gmail frente a carpetas IMAP, nomenclatura de carpetas no estándar de Outlook para Enviados/Eliminados, servidores IMAP que devuelven respuestas CAPABILITY que no coinciden con lo que realmente soportan y servidores que desconectan silenciosamente las conexiones durante las operaciones FETCH con archivos adjuntos grandes. Cada proveedor tiene un conjunto único de peculiaridades que solo surgen en producción.
Esto no es un argumento en contra de construir una integración IMAP personalizada: para una herramienta de un solo proveedor y un solo usuario, el IMAP sin procesar es perfectamente razonable. Pero para cualquier producto que necesite leer y sincronizar correos electrónicos entre múltiples proveedores y múltiples cuentas de usuario, el sobrecosto operativo de mantener una capa IMAP personalizada generalmente excede el costo de usar una API de correo electrónico dedicada. Guía de la API unificada de correo electrónico cubre las compensaciones arquitectónicas en detalle.
Sincronización de correo de producción sin la sobrecarga de IMAP. Unipile maneja la agrupación de conexiones, la renovación de tokens, la reintentación de errores y la normalización de múltiples proveedores: solo tienes que llamar a la API.
Construye a escala sin la sobrecarga de IMAPConstruir una integración IMAP sin gestionar la conexión: Unipile
Si has leído hasta aquí, tienes una idea clara de lo que se necesita para mantener conexiones IMAP en bruto en producción: bucles de actualización de tokens OAuth, gestión de estado por cuenta, agrupación de conexiones, lógica de reintentos y peculiaridades específicas del proveedor para servidores de Gmail, Outlook e IMAP. Unipile abstrae toda esta capa y te proporciona una única API REST para leer, enviar y sincronizar correos electrónicos entre los tres, con un inicio rápido de 5 minutos y menos de 10 líneas de código por operación.
Unipile gestiona el flujo OAuth completo para Gmail y Microsoft 365: adquisición, actualización y rotación de tokens. Nunca tocas un token de actualización directamente.
Una API, un esquema de respuesta. Lee correos electrónicos de una bandeja de entrada de Gmail y un servidor corporativo IMAP con la misma llamada GET /emails. Sin análisis específico del proveedor.
Recibe notificaciones HTTP cuando llegan nuevos correos electrónicos. Sin conexión IMAP persistente que administrar, sin tiempo de espera IDLE de 29 minutos que manejar, sin hilo dedicado por cuenta.
Vincula cuentas de usuario a través del flujo OAuth alojado de Unipile. Cada cuenta vinculada obtiene su propio `account_id`. Escala de 1 a 10.000 cuentas vinculadas sin cambiar tu código de integración.
Credenciales encriptadas en reposo con claves respaldadas por KMS. Unipile tiene certificación SOC 2 Tipo II y evaluación CASA Nivel 2. No se almacenan contraseñas IMAP ni tokens OAuth en su base de datos.
import solicita
DIRECCIÓN_BASE = "https://api7.unipile.com:13047/api/v1"
ENCABEZADOS = {"Clave API X": "tu-clave-api-de-unipile"}
# Paso 1: Enumera todas las cuentas vinculadas
cuentas = solicitudes.consiga(
f"{URL_BASE}/cuentas", encabezados=ENCABEZADOS
).json()
account_id = cuentas["artículos"][0]["id"]
# Paso 2: Leer los correos electrónicos de la bandeja de entrada
correos electrónicos = solicitudes.consiga(
f"{URL_BASE}/correos",
cabeceras=ENCABEZADOS,
parámetros={"account_id": id_cuenta, "límite": 10}
).json()
para email en correos eletrónicos"artículos"]:
print(correo electrónico"Asunto", correo electrónico["asistente_remitente"])
#: No hay conexión IMAP, no se actualiza el token,
#: sin contexto SSL, sin máquina de estados.
Preguntas frecuentes
Preguntas frecuentes sobre conexiones de servidor IMAP, puertos, autenticación y migración de OAuth.
Una conexión de servidor IMAP es una sesión TCP persistente entre un cliente de correo electrónico y un servidor de correo que utiliza el Protocolo de Acceso a Mensajes de Internet para sincronizar, recuperar y administrar mensajes de correo electrónico almacenados en el servidor, sin descargarlos ni eliminarlos localmente. A diferencia de POP3, IMAP mantiene los mensajes en el servidor y sincroniza el estado (leído, marcado, movido) en todos los dispositivos conectados. Para los desarrolladores, es el protocolo fundamental para crear integraciones de correo electrónico que funcionan en Gmail, Outlook y cualquier cliente estándar. API IMAP.
Utilice puerto 993 para IMAP sobre SSL/TLS (TLS implícito). Este es el estándar moderno y es requerido por todos los principales proveedores de la nube, incluyendo Gmail y Outlook. El puerto 143 es para actualizaciones STARTTLS y solo es apropiado para servidores de correo autohospedados. Nunca te conectes a un servidor de correo en la nube en el puerto 143 en producción; la mayoría ahora rechaza estas conexiones por completo. Si no estás seguro, siempre elige el puerto 993 con ssl=Verdadero.
Sí, sin excepción. SSL/TLS es obligatorio para cualquier conexión a un servidor IMAP que transmita credenciales. Los servidores de correo modernos rechazan por completo las conexiones en texto plano. RFC 9051 (IMAP4rev2) exige formalmente TLS para todas las sesiones autenticadas. Utilice siempre puerto 993 con TLS implícito para proveedores de nube. Si se conecta a un servidor autoalojado en el puerto 143, debe actualizar a TLS usando el comando STARTTLS y verificar el certificado del servidor; nunca use ssl._create_unverified_context() en producción.
La dirección del servidor IMAP para Gmail es imap.gmail.com on puerto 993 con SSL/TLS. Antes de conectarse, debe habilitar el acceso IMAP en la Configuración de Gmail en "Reenvío y correo POP/IMAP". La autenticación requiere una contraseña específica de la aplicación (si la verificación en dos pasos está habilitada) o OAuth 2.0 XOAUTH2 con el ámbito https://mail.google.com/. Google ha restringido la autenticación básica para nuevas aplicaciones y recomienda encarecidamente OAuth para cualquier acceso programático a IMAP.
La dirección del servidor IMAP tanto para cuentas personales de Outlook.com como para cuentas de empresa de Microsoft 365 es outlook.office365.com on puerto 993 con SSL/TLS. Ten en cuenta que Microsoft está finalizando el soporte para la autenticación básica (nombre de usuario/contraseña) para IMAP en Diciembre de 2026. Todas las integraciones deben migrar a OAuth 2.0 XOAUTH2 antes de esa fecha límite. Vea nuestra Microsoft Graph OAuth para Outlook guía para los pasos de migración.
Necesitas una contraseña de aplicación si tu cuenta tiene habilitada la autenticación de dos factores y estás utilizando Basic Auth para IMAP. Las contraseñas de aplicación son tokens de 16 caracteres generados a partir de la configuración de seguridad de tu proveedor (página de seguridad de la cuenta de Google para Gmail, ID de Apple para iCloud) que sustituyen tu contraseña real sin conceder acceso completo a la cuenta. Para aplicaciones de producción multiusuario, Se prefiere encarecidamente OAuth 2.0 contraseñas de aplicación: es más seguro, no requiere almacenar credenciales de usuario en tu aplicación y es el único método que seguirá siendo válido después de la depreciación de Microsoft Basic Auth en diciembre de 2026.
Sí, para servicios de Microsoft. Microsoft ha confirmado el fin de vida útil definitivo de la autenticación básica para IMAP, POP3 y SMTP en Exchange Online. Diciembre de 2026, Lo que afecta a todos los inquilinos, incluidos aquellos con exenciones existentes. Cualquier integración que utilice autenticación de nombre de usuario/contraseña contra Outlook o Microsoft 365 IMAP dejará de funcionar después de esa fecha. Google ya restringió el acceso a Basic Auth para Gmail y requiere contraseñas de aplicaciones u OAuth para cualquier acceso programático desde 2022. Si su integración IMAP se conecta a cuentas de Microsoft, debe migrar a OAuth 2.0 XOAUTH2 antes de diciembre de 2026.
Para conectarse a un servidor IMAP con OAuth 2.0, se utiliza el mecanismo SASL XOAUTH2. Después de obtener un token de acceso a través del flujo estándar de código de autorización OAuth, codifica la cadena. usuario={email}\x01autenticación=Bearer {token}\x01\x01 como base64, luego pásalo a la AUTENTICAR XOAUTH2 Comando IMAP. Para Gmail, el ámbito requerido es https://mail.google.com/. Para Microsoft 365, usa MSAL para adquirir un token con el IMAP.AccesoComoUsuario.Todos Los tokens de acceso caducan después de 3600 segundos y deben ser actualizados antes de volver a conectar; implementa una verificación de actualización de token antes de cada nueva sesión IMAP. Ver las muestras de código completas en la sección XOAUTH2 de arriba.
ES 
EN 
FR 
DE 
IT 
BR 
NL 
PL 
TR