fn_registry/python/functions/infra/imap_connect.md

name, kind, lang, domain, version, purity, signature, description, tags, params, output, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	params	output	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path
imap_connect	function	py	infra	1.0.0	impure	def imap_connect(host: str, port: int = 993, user: str = '', password: str = '', mailbox: str = 'INBOX', use_ssl: bool = True, timeout_s: float = 30.0) -> dict	Abre y autentica una conexion IMAP (IMAP4_SSL por defecto, IMAP4 en claro si use_ssl=False) con usuario + app-password (NO OAuth), hace login y select(mailbox), y devuelve el objeto imaplib vivo dentro del dict de estado para componer el resto de operaciones del grupo email/imap. Defaults Gmail: host imap.gmail.com, port 993. Devuelve {status:'ok', conn, mailbox, num_messages} o {status:'error', error}. Nunca lanza. Las credenciales las pasa la capa app (via pass/vault), no se resuelven aqui.	email imap infra mailbox network	name desc host Servidor IMAP, ej. imap.gmail.com. Vacio devuelve status error. name desc port Puerto IMAP. Default 993 (IMAPS sobre SSL). 143 para STARTTLS/plano. name desc user Direccion de correo / usuario de la cuenta. name desc password App-password (16 chars en Gmail, requiere 2FA) o contrasena del proveedor. NO OAuth. name desc mailbox Buzon a seleccionar tras autenticar. Default 'INBOX'. name desc use_ssl True (default) usa IMAP4_SSL cifrado. False usa IMAP4 en claro (solo redes de confianza/test). name desc timeout_s Timeout del socket en segundos para conectar/operar. Default 30.0.	dict de estado. En exito {status:'ok', conn: <imaplib.IMAP4_SSL vivo autenticado con mailbox seleccionado>, mailbox: str, num_messages: int (mensajes en el buzon, de la respuesta de SELECT)}. En fallo (host vacio, auth invalida, red caida, buzon inexistente) {status:'error', error: str} y SIN clave conn.				false	error_py_core		false			python/functions/infra/imap_connect.py

Ejemplo

import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from infra import imap_connect

# App-password de Gmail (16 chars, requiere 2FA). Pasalo desde pass/vault.
res = imap_connect(
    host="imap.gmail.com",
    port=993,
    user="gutierenmanuel15@gmail.com",
    password="abcd efgh ijkl mnop",   # app-password Gmail
    mailbox="INBOX",
)
print(res["status"])         # "ok"
print(res["num_messages"])   # p.ej. 1423
conn = res["conn"]           # objeto vivo: pasalo a imap_search / imap_fetch_message

# ... operar ...
conn.logout()                # cierra siempre al terminar

Cuando usarla

Usala como PRIMER paso de cualquier flujo de lectura de correo por IMAP: antes de listar carpetas (imap_list_mailboxes), buscar (imap_search) o leer un mensaje (imap_fetch_message). Es la fabrica del objeto conn que el resto del grupo consume. Para Gmail usa los defaults (imap.gmail.com:993); para otros proveedores cambia host/port y pasa user+pass.

Gotchas

• Funcion impura: hace red. No determinista (latencia, disponibilidad del servidor). Nunca lanza: comprueba status antes de tocar conn.
• El objeto conn VIVO viaja dentro del dict a proposito: este grupo se compone en heredocs Python, no por fn run (un proceso fn run no puede devolver un socket abierto entre invocaciones). Mantén conn en memoria del mismo proceso mientras lo uses.
• Cierra SIEMPRE con conn.logout() al terminar (o en un finally). Una conexion sin cerrar deja sesiones colgando en el servidor; Gmail limita el numero de conexiones IMAP simultaneas por cuenta.
• Auth = app-password, NO OAuth. En Gmail debes tener 2FA activado y generar una app-password; la contrasena normal de la cuenta NO funciona por IMAP.
• Si select(mailbox) falla (buzon inexistente, mayusculas mal en nombres tipo [Gmail]/Sent Mail), se hace logout y se devuelve status:'error'.
• use_ssl=False envia credenciales en claro: usalo solo contra servidores de test en redes de confianza.