---
name: imap_list_mailboxes
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def imap_list_mailboxes(conn) -> dict"
description: "Lista los buzones/carpetas de una cuenta IMAP ya conectada. Ejecuta conn.list() sobre una conexion imaplib viva (de imap_connect), parsea cada linea de respuesta para extraer el nombre de carpeta y lo decodifica de modified-UTF-7 (RFC 3501) a Unicode (codec imap4-utf-7 si esta disponible, conversion manual si no, ASCII best-effort como fallback). Las carpetas anidadas de Gmail salen con prefijo ([Gmail]/Sent Mail, [Gmail]/Spam). Devuelve {status:'ok', mailboxes:[...]} o {status:'error', error}. Nunca lanza."
tags: [email, imap, infra, mailbox, network]
params:
  - name: conn
    desc: "Objeto imaplib.IMAP4[_SSL] vivo y autenticado, producido por imap_connect. None devuelve status error."
output: "dict de estado. En exito {status:'ok', mailboxes: list[str]} con los nombres de carpeta decodificados a Unicode (ej. ['INBOX', '[Gmail]/Sent Mail', '[Gmail]/Spam']). En fallo (conn None, respuesta LIST no OK) {status:'error', error: str}."
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_py_core"
imports: []
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/infra/imap_list_mailboxes.py"
---

## Ejemplo

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

c = imap_connect("imap.gmail.com", 993, "gutierenmanuel15@gmail.com", "abcd efgh ijkl mnop")
conn = c["conn"]

res = imap_list_mailboxes(conn)
print(res["status"])        # "ok"
for mb in res["mailboxes"]:
    print(mb)               # INBOX, [Gmail]/Sent Mail, [Gmail]/Spam, [Gmail]/Trash, ...

conn.logout()
```

## Cuando usarla

Usala despues de `imap_connect` cuando necesites descubrir que carpetas tiene
la cuenta antes de buscar o leer (ej. saber el nombre exacto del buzon de
enviados o spam para pasarlo a `imap_search`/`imap_connect`). Imprescindible
con Gmail, donde los nombres llevan el prefijo `[Gmail]/` y pueden estar
localizados segun el idioma de la cuenta.

## Gotchas

- Funcion impura: hace red sobre el `conn` vivo. Nunca lanza: comprueba
  `status`. Requiere un `conn` valido de `imap_connect` (no resuelve
  credenciales ni reconecta).
- El objeto `conn` es el mismo objeto vivo del grupo: se opera en el mismo
  proceso Python (heredoc), no por `fn run`.
- Nombres de carpeta no-ASCII vienen en modified-UTF-7 (RFC 3501): `&...-`
  delimita la secuencia y usa `,` en vez de `/` en el base64. Se decodifican a
  Unicode; si el codec/conversion falla, la entrada se conserva en ASCII
  best-effort (puede mostrar mojibake) en vez de perderse o lanzar.
- Los nombres de carpeta de Gmail dependen del idioma de la cuenta y del
  prefijo `[Gmail]/`. No los hardcodees: descubrelos con esta funcion.
- Cierra la conexion con `conn.logout()` al terminar (responsabilidad del
  caller, no de esta funcion).
