# `imaplib` — IMAP4 protocol client

Código fuente: Lib/imaplib.py

This module defines three classes, `IMAP4`, `IMAP4_SSL` and `IMAP4_stream`, which encapsulate a connection to an IMAP4 server and implement a large subset of the IMAP4rev1 client protocol as defined in RFC 3501. It is backward compatible with IMAP4 (RFC 1730) servers, but note that the `STATUS` command is not supported in IMAP4.

Availability: not WASI.

This module does not work or is not available on WebAssembly. See Plataformas WebAssembly for more information.

Three classes are provided by the `imaplib` module, `IMAP4` is the base class:

class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)

  This class implements the actual IMAP4 protocol. The connection is created and protocol version (IMAP4 or IMAP4rev1) is determined when the instance is initialized. If host is not specified, `''` (the local host) is used. If port is omitted, the standard IMAP4 port (143) is used. The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is `None`, the global default socket timeout is used.

  La clase `IMAP4` soporta la sentencia `with`. Cuando se usa de esta manera, el comando IMAP4 `LOGOUT` se emite automáticamente cuando se cierra la declaración `with`. P.ej.:

      >>> from imaplib import IMAP4
      >>> with IMAP4("domain.org") as M:
      ...     M.noop()
      ...
      ('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])

  Distinto en la versión 3.5: Se agregó soporte para la sentencia `with`.

  Distinto en la versión 3.9: El parámetro opcional timeout fue agregado.

Se definen tres excepciones como atributos de la clase `IMAP4`:

exception IMAP4.error

  Excepción lanzada por cualquier error. El motivo de la excepción se pasa al constructor como una cadena de caracteres.

exception IMAP4.abort

  Los errores del servidor IMAP4 causan que esta excepción sea lanzada. Esta es una subclase de `IMAP4.error`. Tenga en cuenta que cerrar la instancia e instanciar una nueva generalmente permitirá la recuperación de esta excepción.

exception IMAP4.readonly

  Esta excepción es lanzada cuando el servidor cambia el estado de un buzón de correo de escritura. Esta es una subclase de `IMAP4.error`. Algún otro cliente ahora tiene permiso de escritura y será necesario volver a abrir el buzón para volver a obtener el permiso de escritura.

También hay una subclase para conexiones seguras:

class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)

  Esta es una subclase derivada de `IMAP4` que se conecta a través de un socket cifrado SSL (para usar esta clase necesita un módulo de socket que se compiló con soporte SSL). Si no se especifica host, se usa `''` (el host local). Si se omite port, se usa el puerto IMAP4 estándar sobre SSL (993). ssl_context es un objeto `ssl.SSLContext` que permite agrupar opciones de configuración SSL, certificados y claves privadas en una estructura única (potencialmente de larga duración). Leer Consideraciones de seguridad para conocer las mejores prácticas.

  Nota

  With the default ssl_context, the connection is encrypted but the server certificate and hostname are not verified. To verify them, pass a context created by `ssl.create_default_context()`.

  The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is `None`, the global default socket timeout is used.

  Distinto en la versión 3.3: El parámetro ssl_context fue agregado.

  Distinto en la versión 3.4: La clase ahora admite la verificación del nombre de host con `ssl.SSLContext.check_hostname` y Server Name Indication (ver `ssl.HAS_SNI`).

  Distinto en la versión 3.9: El parámetro opcional timeout fue agregado.

  Distinto en la versión 3.12: Se han eliminado los parámetros obsoletos keyfile y certfile.

La segunda subclase permite conexiones creadas por un proceso hijo:

class imaplib.IMAP4_stream(command)

  Esta es una subclase derivada de `IMAP4` que se conecta a los descriptores de archivo `stdin/stdout` creados al pasar command a `subprocess.Popen ()`.

Se definen las siguientes funciones de utilidad:

imaplib.Internaldate2tuple(resp)

  Parse a bytes-like object containing an IMAP4 `INTERNALDATE` response and return the corresponding local time. The return value is a `time.struct_time` tuple or `None` if the input has wrong format.

imaplib.Int2AP(num)

  Convierte un número entero en una representación de bytes utilizando caracteres del conjunto [`A` .. `P`].

imaplib.ParseFlags(resp)

  Converts a bytes-like object containing an IMAP4 `FLAGS` response to a tuple of individual flags as `bytes`. The return value is an empty tuple if the input has wrong format.

imaplib.Time2Internaldate(date_time)

  Convierte date_time en una representación IMAP4 `INTERNALDATE`. El valor de retorno es una cadena de caracteres en la forma: `"DD-Mmm-YYYY HH:MM:SS +HHMM"` (incluyendo comillas dobles). El argumento date_time puede ser un número (int o float) que representa segundos en un espacio de tiempo (como lo retorna `time.time()`), una tupla de 9 que representa la hora local como una instancia de `time.struct_time` (según lo retornado por `time.localtime()`), una instancia actualizada de `datetime.datetime`, o una cadena de caracteres entre comillas dobles. En el último caso, se supone que ya está en el formato correcto.

Tenga en cuenta que los números de mensaje IMAP4 cambian a medida que cambia el buzón de correo; en particular, después de que un comando `EXPUNGE` realiza eliminaciones, los mensajes restantes se vuelven a numerar. Por lo tanto, es muy recomendable usar UIDs en su lugar, con el comando UID.

Al final del módulo, hay una sección de prueba que contiene un ejemplo más extenso de uso.

Ver también

Documentos describiendo el protocolo, y fuentes de servidores que lo implementan, del Centro de Información IMAP de la Universidad de Washington, pueden ser encontrados en (Código Fuente) https://github.com/uw-imap/imap (Fuera de mantención).

## Objetos de IMAP4

Todos los comandos IMAP4rev1 están representados por métodos del mismo nombre, ya sea en mayúsculas o minúsculas.

All arguments to commands are converted to strings, except for `AUTHENTICATE`, and the last argument to `APPEND` which is passed as an IMAP4 literal. If necessary (the string contains IMAP4 protocol-sensitive characters and isn’t enclosed with either parentheses or double quotes) each string is quoted. However, the password argument to the `LOGIN` command is always quoted. If you want to avoid having an argument string quoted (eg: the flags argument to `STORE`) then enclose the string in parentheses (eg: `r'(\Deleted)'`). Or you can quote the string yourself; an argument that is already enclosed in double quotes is left unchanged. In general, however, it is better to pass arguments unquoted and let the module quote them as needed.

Mailbox names are encoded as modified UTF-7 (RFC 3501, section 5.1.3), so a mailbox name containing non-ASCII characters can be passed as an ordinary `str`. A `str` that is already valid modified UTF-7 is left unchanged, so that a name obtained from `list()` (raw `bytes` decoded to text) round-trips; pass `bytes` to send the exact bytes with no encoding. When `UTF8=ACCEPT` is enabled (see `enable()`), mailbox names are sent as UTF-8 instead.

Distinto en la versión 3.16.0a0 (unreleased): Non-ASCII mailbox names are automatically encoded as modified UTF-7.

Most commands return a tuple: `(type, [data, ...])` where type is usually `'OK'` or `'NO'`, and data is either the text from the command response, or mandated results from the command. Each data is either a `bytes`, or a tuple. If a tuple, then the first part is the header of the response, and the second part contains the data (ie: “literal” value).

The message_set options to the commands below can be a string specifying one or more messages to be acted upon. It may be a simple message number (`'1'`), a range of message numbers (`'2:4'`), or a group of non-contiguous ranges separated by commas (`'1:3,6:9'`). A range can contain an asterisk to indicate an infinite upper bound (`'3:*'`).

Alternatively it can be specified using integers and `range` objects. It may be a single message number or a sequence. The sequence items may be integers, `(start, stop)` tuples (where `None` or `'*'` stands for the last message), or `range` objects. For example, `[1, (3, 5), 8]` and `[range(1, 6), 8]` are both equivalent to `'1,3:5,8'`.

Distinto en la versión 3.16.0a0 (unreleased): Added support for the structured message_set.

Command arguments that are parenthesized lists of atoms — such as the flag_list argument of `store()` and the flags argument of `append()`, the names argument of `status()`, the sort_criteria argument of `sort()`, or the message_parts argument of `fetch()` — can be passed as a sequence of strings instead of a single preformatted string. For example, `[r'\Seen', r'\Answered']` is equivalent to `(\Seen \Answered)`.

Distinto en la versión 3.16.0a0 (unreleased): Added support for passing these arguments as a sequence.

The value-bearing arguments of the search and fetch commands can be quoted by hand, but this is error prone. Instead, they may contain `?` placeholders that are substituted, and quoted as required, from a params keyword argument, in the manner of `sqlite3` parameter substitution:

    # SEARCH FROM me@example.com SUBJECT "trip report"
    M.search(None, 'FROM ? SUBJECT ?', params=['me@example.com', 'trip report'])

    # FETCH 1:5 (FLAGS BODY[HEADER.FIELDS (DATE FROM)])
    M.fetch('1:5', 'FLAGS BODY[HEADER.FIELDS ?]', params=[['DATE', 'FROM']])

The placeholders are:

- `?` — an `astring`: a string (which will be quoted if necessary), an integer, or a list of integers and/or strings (which will be sent as a parenthesized list);

- `?f` — a flag or a list of flags, sent verbatim without quoting;

- `?s` — a message_set in the structured form described above.

`??` stands for a literal `?`.

Substitution is only performed when params is given; if no params are given, an argument containing a literal `?` is unchanged. The params keyword is accepted by `search()`, `fetch()`, `sort()`, `thread()` and `uid()`.

Added in version 3.16.0a0 (unreleased): The params keyword argument.

Una instancia de `IMAP4` tiene los siguientes métodos:

IMAP4.append(mailbox, flags, date_time, message, *, translate_line_endings=True)

  Agregar mensaje al buzón de correo con nombre.

  flags may be `None` or a string of IMAP flag tokens. Multiple flags are separated by spaces, for example `r'\Seen \Answered'`. If flags is not already enclosed in parentheses, parentheses are added automatically.

  If translate_line_endings is true (the default), line endings in message are translated to CRLF. Pass `False` to send the message literal exactly as given, which is required to preserve messages that contain bare CR or LF. In that case message must already use CRLF line endings as required by RFC 3501; for example, serialize `email` messages using `email.policy.SMTP`.

  Distinto en la versión 3.16.0a0 (unreleased): Added the translate_line_endings parameter.

IMAP4.authenticate(mechanism, authobject)

  Autenticar comando — requiere procesamiento de respuesta.

  mechanism especifica qué mecanismo de autenticación se utilizará; debe aparecer en la variable de instancia `capabilities` en la forma `AUTH=mechanism`.

  authobject debe ser un objeto invocable:

      data = authobject(response)

  Se llamará para procesar las respuestas de continuación del servidor; el argumento response que se pasa será `bytes`. Debería retornar `bytes` data que se codificarán en base64 y se enviarán al servidor. Debería retornar `None` si la respuesta de cancelación de cliente `*` se debe enviar en su lugar.

  Distinto en la versión 3.5: los nombres de usuario y las contraseñas de cadena de caracteres ahora están codificados para `utf-8` en lugar de limitarse a ASCII.

IMAP4.check()

  Control del buzón de correo en el servidor.

IMAP4.close()

  Cerrar el buzón de correo seleccionado actualmente. Los mensajes eliminados se eliminan del buzón de correo de escritura. Este es el comando recomendado antes de `LOGOUT`.

IMAP4.copy(message_set, new_mailbox, *, uid=False)

  Copia mensajes message_set al final de new_mailbox.

  If uid is true, message_set is a set of UIDs and the `UID COPY` command is used instead of `COPY`.

  Distinto en la versión 3.16.0a0 (unreleased): Added the uid parameter.

IMAP4.create(mailbox)

  Crea un nuevo buzón de correo llamado mailbox.

IMAP4.delete(mailbox)

  Elimina el buzón de correo antiguo llamado mailbox.

IMAP4.deleteacl(mailbox, who)

  Elimina las ACLs (elimina cualquier derecho) establecidas para quién en el buzón de correo.

IMAP4.enable(capability)

  Habilita capability (ver RFC 5161). La mayoría de las capacidades no necesitan estar habilitadas. Actualmente solo esta soportada la capacidad `UTF8=ACCEPT` (consulte RFC 6855).

  Added in version 3.5: El método `enable()` en sí, y soporte RFC 6855.

IMAP4.expunge(message_set=None, *, uid=False)

  Elimina permanentemente los elementos eliminados del buzón de correo seleccionado. Genera una respuesta `EXPUNGE` para cada mensaje eliminado. Los datos retornados contienen una lista de números de mensaje `EXPUNGE` en el orden recibido.

  If uid is true, the `UID EXPUNGE` command (RFC 4315) is used to remove only the messages that both are marked as deleted and have a UID in message_set. message_set is required in this case, and must be omitted otherwise.

  Distinto en la versión 3.16.0a0 (unreleased): Added the message_set and uid parameters.

IMAP4.fetch(message_set, message_parts, *, uid=False, params=None)

  Obtiene (partes de) mensajes. message_parts debe ser una cadena de nombres de partes de mensajes encerrados entre paréntesis, por ejemplo: `"(UID BODY[TEXT])"`. Los datos retornados son una tupla de mensaje parte sobre y datos.

  If uid is true, message_set is a set of UIDs and the message numbers in the response are UIDs (`UID FETCH`).

  If params is given, `?` placeholders in message_parts are substituted with the quoted parameters (see the placeholders).

  Distinto en la versión 3.16.0a0 (unreleased): Added the params and uid parameters.

IMAP4.getacl(mailbox)

  Obtiene la `ACL`s para mailbox. El método no es estándar, pero es compatible con el servidor `Cyrus`.

IMAP4.getannotation(mailbox, entry, attribute)

  Recupera la `ANNOTATION`s especificada para mailbox. El método no es estándar, pero es compatible con el servidor `Cyrus`.

IMAP4.getquota(root)

  Obtiene el uso y los límites de los recursos de la `quota` de root. Este método es parte de la extensión IMAP4 QUOTA definida en rfc2087.

IMAP4.getquotaroot(mailbox)

  Obtiene la lista de `quota` `roots` para el nombrado mailbox. Este método es parte de la extensión IMAP4 QUOTA definida en rfc2087.

IMAP4.id(fields=None)

  Send client identification information to the server and return the identification information sent back by the server (the `ID` command, defined in RFC 2971). fields is a mapping of field names to values (for example, `{'name': 'myclient', 'version': '1.0'}`); a value can be `None`. The server must support the `ID` capability.

  Added in version 3.16.0a0 (unreleased).

IMAP4.idle(duration=None)

  Return an `Idler`: an iterable context manager implementing the IMAP4 `IDLE` command as defined in RFC 2177.

  The returned object sends the `IDLE` command when activated by the `with` statement, produces IMAP untagged responses via the iterator protocol, and sends `DONE` upon context exit.

  All untagged responses that arrive after sending the `IDLE` command (including any that arrive before the server acknowledges the command) will be available via iteration. Any leftover responses (those not iterated in the `with` context) can be retrieved in the usual way after `IDLE` ends, using `IMAP4.response()`.

  Responses are represented as `(type, [data, ...])` tuples, as described in IMAP4 Objects.

  The duration argument sets a maximum duration (in seconds) to keep idling, after which any ongoing iteration will stop. It can be an `int` or `float`, or `None` for no time limit. Callers wishing to avoid inactivity timeouts on servers that impose them should keep this at most 29 minutes (1740 seconds). Requires a socket connection; duration must be `None` on `IMAP4_stream` connections.

      >>> with M.idle(duration=29 * 60) as idler:
      ...     for typ, data in idler:
      ...         print(typ, data)
      ...
      EXISTS [b'1']
      RECENT [b'1']

  Idler.burst(interval=0.1)

    Yield a burst of responses no more than interval seconds apart (expressed as an `int` or `float`).

    This generator is an alternative to iterating one response at a time, intended to aid in efficient batch processing. It retrieves the next response along with any immediately available subsequent responses. (For example, a rapid series of `EXPUNGE` responses after a bulk delete.)

    Requires a socket connection; does not work on `IMAP4_stream` connections.

        >>> with M.idle() as idler:
        ...     # get a response and any others following by < 0.1 seconds
        ...     batch = list(idler.burst())
        ...     print(f'processing {len(batch)} responses...')
        ...     print(batch)
        ...
        processing 3 responses...
        [('EXPUNGE', [b'2']), ('EXPUNGE', [b'1']), ('RECENT', [b'0'])]

    Truco

    The `IDLE` context’s maximum duration, as passed to `IMAP4.idle()`, is respected when waiting for the first response in a burst. Therefore, an expired `Idler` will cause this generator to return immediately without producing anything. Callers should consider this if using it in a loop.

  Nota

  The iterator returned by `IMAP4.idle()` is usable only within a `with` statement. Before or after that context, unsolicited responses are collected internally whenever a command finishes, and can be retrieved with `IMAP4.response()`.

  Nota

  The `Idler` class name and structure are internal interfaces, subject to change. Calling code can rely on its context management, iteration, and public method to remain stable, but should not subclass, instantiate, compare, or otherwise directly reference the class.

  Added in version 3.14.

IMAP4.list(directory='', pattern='*')

  Lista los nombres de buzones de correo en directory coincidiendo pattern. directory por defecto es la carpeta de correo de nivel superior, y pattern por defecto coincide con cualquier cosa. Los datos retornados contienen una lista de respuestas `LIST`.

IMAP4.login(user, password)

  Identifica al cliente con una contraseña de texto sin formato. El password será citado.

IMAP4.login_cram_md5(user, password)

  Force use of `CRAM-MD5` authentication when identifying the client to protect the password. It will only work if the server `CAPABILITY` response includes the phrase `AUTH=CRAM-MD5`.

  Distinto en la versión 3.15: An `IMAP4.error` is raised if MD5 support is not available.

IMAP4.login_plain(user, password)

  Authenticate using the `PLAIN` SASL mechanism (RFC 4616).

  This is a plaintext authentication mechanism that can be used instead of `login()` when UTF-8 support is required (see RFC 6855). Since the credentials are only base64-encoded, not encrypted, this method should only be used over a TLS-protected connection, such as `IMAP4_SSL` or after `starttls()`.

  It will only work if the server supports the `PLAIN` mechanism, which it need not advertise as `AUTH=PLAIN` in its `CAPABILITY` response.

  Added in version 3.16.0a0 (unreleased).

IMAP4.logout()

  Cierra la conexión al servidor. Retorna la respuesta `BYE` desde el servidor .

  Distinto en la versión 3.8: El método ya no ignora las excepciones silenciosamente arbitrarias.

IMAP4.lsub(directory='', pattern='*')

  Lista los nombres de buzones de correos suscritos en el patrón de coincidencia del directorio directory por defecto para el directorio de nivel superior y pattern por defecto para que coincida con cualquier buzón de correo. Los datos retornados son una tupla de mensaje parte sobre y datos.

IMAP4.move(message_set, new_mailbox, *, uid=False)

  Move message_set messages onto end of new_mailbox.

  The server must support the `MOVE` capability (RFC 6851).

  If uid is true, message_set is a set of UIDs and the `UID MOVE` command is used instead of `MOVE`.

  Added in version 3.16.0a0 (unreleased).

IMAP4.myrights(mailbox)

  Muestra mis ACLs para un buzón de correo (es decir, los derechos que tengo sobre el buzón de correo).

IMAP4.namespace()

  Retorna espacios de nombres IMAP como se define en RFC 2342.

IMAP4.noop()

  Envía `NOOP` al servidor.

IMAP4.open(host, port, timeout=None)

  Opens socket to port at host. The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is `None`, the global default socket timeout is used. Also note that if the timeout parameter is set to be zero, it will raise a `ValueError` to reject creating a non-blocking socket. This method is implicitly called by the `IMAP4` constructor. The connection objects established by this method will be used in the `IMAP4.read()`, `IMAP4.readline()`, `IMAP4.send()`, and `IMAP4.shutdown()` methods. You may override this method.

  Genera un evento de auditoría `imaplib.open` con argumentos `self`, `host`, `port`.

  Distinto en la versión 3.9: El parámetro timeout fue agregado.

IMAP4.partial(message_num, message_part, start, length)

  Obtiene partes truncadas de un mensaje. Los datos retornados son una tupla de mensaje parte sobre y datos.

IMAP4.proxyauth(user)

  Asume la autenticación como user. Permite a un administrador autorizado hacer un proxy en el buzón de correo de cualquier usuario.

IMAP4.read(size)

  Lee size bytes del servidor remoto. Podemos sobrescribir este método.

IMAP4.readline()

  Lee una línea del servidor remoto. Podemos sobrescribir este método.

IMAP4.recent()

  Solicita al servidor una actualización. Los datos retornados son `None` si no hay mensajes nuevos, de lo contrario el valor de respuesta es `RECENT`.

IMAP4.rename(oldmailbox, newmailbox)

  Cambia el nombre del buzón de correo llamado oldmailbox a newmailbox.

IMAP4.response(code)

  Retorna los datos para la respuesta code si se recibió, o `None`. Retorna el código dado, en lugar del tipo habitual.

IMAP4.search(charset, criterion, [..., ]*, uid=False, params=None)

  Busca en el buzón de correo mensajes coincidentes. El charset puede ser `None`, en cuyo caso no se especificará `CHARSET` en la solicitud al servidor. El protocolo IMAP requiere que se especifique al menos un criterio; se lanzará una excepción cuando el servidor retorne un error. charset debe ser `None` si la capacidad `UTF8=ACCEPT` se habilitó utilizando el comando `enable()`.

  If uid is true, the message numbers in the response are UIDs (`UID SEARCH`).

  A criterion passed as `str` is encoded to charset (which must name a codec known to Python); pass `bytes` to send a criterion that is already encoded, for example when charset is one that Python does not support. When charset is `None` (as it must be under `UTF8=ACCEPT`), the criterion is sent using the connection’s encoding instead.

  If params is given, `?` placeholders in the criteria are substituted with the quoted parameters (see the placeholders).

  Ejemplo:

      # M is a connected IMAP4 instance...
      typ, msgnums = M.search(None, 'FROM', '"John Smith"')

      # or:
      typ, msgnums = M.search(None, '(FROM "John Smith")')

      # or, letting the module quote the value (this is recommended):
      typ, msgnums = M.search(None, 'FROM ?', params=['John Smith'])

  Distinto en la versión 3.16.0a0 (unreleased): Added the params and uid parameters. `str` search criteria are encoded to charset.

IMAP4.select(mailbox='INBOX', readonly=False)

  Seleccione un buzón de correo. Los datos retornados son el recuento de mensajes en mailbox (respuesta `EXISTS`). El mailbox predeterminado es `'INBOX'`. Si se establece el indicador readonly, no se permiten modificaciones en el buzón de correo.

IMAP4.send(data)

  Envía `data` al servidor remoto. Podemos sobrescribir este método.

  Lanza un evento de auditoría `imaplib.send` con argumentos `self`, `data`.

IMAP4.setacl(mailbox, who, what)

  Establece una `ACL` para mailbox. El método no es estándar, pero es compatible con el servidor `Cyrus`.

IMAP4.setannotation(mailbox, entry, attribute[, ...])

  Establece `ANNOTATION`s para mailbox. El método no es estándar, pero es compatible con el servidor `Cyrus`.

IMAP4.setquota(root, limits)

  Establece los recursos limits de la `quota` de los root. Este método es parte de la extensión IMAP4 QUOTA definida en rfc2087.

IMAP4.shutdown()

  Cierra la conexión establecida en `open`. Este método es llamado implícitamente por `IMAP4.logout()`. Podemos sobrescribir este método.

IMAP4.socket()

  Retorna la instancia de socket utilizada para conectarse al servidor.

IMAP4.sort(sort_criteria, charset, search_criterion, [..., ]*, uid=False, params=None)

  El comando `sort` es una variante de `search` con semántica de clasificación para los resultados. Los datos retornados contienen una lista separada por espacios de números de mensajes coincidentes.

  Sort tiene dos argumentos antes del argumento (s) search_criterion; una lista entre paréntesis de sort_criteria, y la búsqueda del charset. Tenga en cuenta que, a diferencia de `search`, el argumento de búsqueda charset es obligatorio. También hay un comando `uid sort` que corresponde a `sort` de la misma manera que `uid search` corresponde a `search`. El comando `sort` primero busca en el buzón de correo mensajes que coincidan con los criterios de búsqueda dados utilizando el argumento charset para la interpretación de cadenas de caracteres en los criterios de búsqueda. Luego retorna los números de mensajes coincidentes.

  If uid is true, the message numbers in the response are UIDs (`UID SORT`).

  As with `search()`, a search_criterion passed as `str` is encoded to charset; pass `bytes` to send one already encoded.

  If params is given, `?` placeholders in the search criteria are substituted with the quoted parameters (see the placeholders).

  Este es un comando de extensión `IMAP4rev1`.

  Distinto en la versión 3.16.0a0 (unreleased): Added the params and uid parameters. `str` search criteria are encoded to charset.

IMAP4.starttls(ssl_context=None)

  Envía un comando `STARTTLS`. El argumento ssl_context es opcional y debe ser un objeto `ssl.SSLContext`. Esto habilitará el cifrado en la conexión IMAP. Leer Consideraciones de seguridad para conocer las mejores prácticas.

  Nota

  With the default ssl_context, the connection is encrypted but the server certificate and hostname are not verified. To verify them, pass a context created by `ssl.create_default_context()`.

  Added in version 3.2.

  Distinto en la versión 3.4: El método ahora admite la verificación del nombre de host con `ssl.SSLContext.check_hostname` y Server Name Indication (ver `ssl.HAS_SNI`).

IMAP4.status(mailbox, names)

  Solicita condiciones de estado con nombre para mailbox.

IMAP4.store(message_set, command, flag_list, *, uid=False)

  Alters flag dispositions for messages in mailbox. command is specified by section 6.4.6 of RFC 3501 as being one of «FLAGS», «+FLAGS», or «-FLAGS», optionally with a suffix of «.SILENT».

  If uid is true, message_set is a set of UIDs and the `UID STORE` command is used instead of `STORE`.

  Por ejemplo, para establecer el indicador de eliminación en todos los mensajes:

      typ, data = M.search(None, 'ALL')
      for num in data[0].split():
         M.store(num, '+FLAGS', r'\Deleted')
      M.expunge()

  Nota

  Creating flags containing “]” (for example: «[test]») violates RFC 3501 (the IMAP protocol). However, imaplib has historically allowed creation of such flags, and popular IMAP servers, such as Gmail, accept and produce such flags. There are non-Python programs which also create such flags. Although it is an RFC violation and IMAP clients and servers are supposed to be strict, imaplib still continues to allow such flags to be created for backward compatibility reasons, and as of Python 3.6, handles them if they are sent from the server, since this improves real-world compatibility.

  Distinto en la versión 3.16.0a0 (unreleased): Added the uid parameter.

IMAP4.subscribe(mailbox)

  Suscribe al nuevo buzón de correo.

IMAP4.thread(threading_algorithm, charset, search_criterion, [..., ]*, uid=False, params=None)

  El comando `thread` es una variante de `search` con semántica de hilos para los resultados. Los datos retornados contienen una lista de miembros de hilos separados por espacios.

  Los miembros de del hilo (thread) consisten en cero o más números de mensajes, delimitados por espacios, que indican sucesivos padres e hijos.

  Thread tiene dos argumentos antes del argumento(s) search_criterion; un threading_algorithm, y la búsqueda del charset. Tenga en cuenta que, a diferencia de `search`, el argumento de búsqueda charset es obligatorio. También hay un comando `uid thread` que corresponde a `thread` de la misma manera que `uid search` corresponde a `search`. El comando `thread` primero busca en el buzón de correo mensajes que coincidan con los criterios de búsqueda dados utilizando el argumento charset para la interpretación de cadenas de caracteres en los criterios de búsqueda. Luego retorna los mensajes coincidentes enfilados según el algoritmo de subproceso especificado.

  If uid is true, the message numbers in the response are UIDs (`UID THREAD`).

  As with `search()`, a search_criterion passed as `str` is encoded to charset; pass `bytes` to send one already encoded.

  If params is given, `?` placeholders in the search criteria are substituted with the quoted parameters (see the placeholders).

  Este es un comando de extensión `IMAP4rev1`.

  Distinto en la versión 3.16.0a0 (unreleased): Added the params and uid parameters. `str` search criteria are encoded to charset.

IMAP4.uid(command, arg, [..., ]*, params=None)

  Ejecuta argumentos de comando con mensajes identificados por UID, en lugar de número de mensaje. Retorna la respuesta apropiada al comando. Se debe proporcionar al menos un argumento; Si no se proporciona ninguno, el servidor retornará un error y se lanzará una excepción.

  If params is given, `?` placeholders in the `SEARCH`, `SORT` and `THREAD` criteria or in the `FETCH` parts are substituted with the quoted parameters (see the placeholders).

  Distinto en la versión 3.16.0a0 (unreleased): Added the params parameter.

IMAP4.unsubscribe(mailbox)

  Darse de baja del antiguo buzón de correo.

IMAP4.unselect()

  `imaplib.IMAP4.unselect()` libera recursos del servidor asociados al buzón de correo seleccionado y devuelve el servidor al estado autenticado. Este comando realiza las mismas acciones que `imaplib.IMAP4.close()`, con la excepción de que ningún mensaje es permanentemente borrado del buzón de correo actualmente seleccionado.

  Added in version 3.9.

IMAP4.xatom(name[, ...])

  Permite comandos de extensión simples notificados por el servidor en la respuesta `CAPABILITY`.

Los siguientes atributos se definen en instancias de `IMAP4`:

IMAP4.PROTOCOL_VERSION

  El protocolo mas recientemente admitido en la respuesta `CAPABILITY` desde el servidor.

IMAP4.debug

  Valor entero para controlar la salida de depuración. El valor de inicialización se toma de la variable del módulo `Debug`. Valores mayores de tres rastrean cada comando.

IMAP4.utf8_enabled

  Valor booleano que normalmente es `False`, pero se establece en `True` si un comando `enable()` es exitosamente emitido para la capacidad `UTF8=ACCEPT`.

  Added in version 3.5.

property IMAP4.file

  Internal `BufferedReader` associated with the underlying socket. This property is documented for legacy purposes but not part of the public interface. The caller is responsible to ensure that the current file is closed before changing it.

  Deprecated since version 3.15, will be removed in version 3.19.

## Ejemplo IMAP4

Aquí hay un ejemplo mínimo (sin verificación de errores) que abre un buzón de correo y recupera e imprime todos los mensajes:

    import getpass, imaplib

    M = imaplib.IMAP4(host='example.org')
    M.login(getpass.getuser(), getpass.getpass())
    M.select()
    typ, data = M.search(None, 'ALL')
    for num in data[0].split():
        typ, data = M.fetch(num, '(RFC822)')
        print('Message %s\n%s\n' % (num, data[0][1]))
    M.close()
    M.logout()

Nota

A `FETCH` response may contain additional or unsolicited data (see RFC 3501, section 7.4.2), so production code should inspect the whole response rather than rely on `data[0][1]`.