"smtplib" --- Cliente de protocolo SMTP
***************************************

**Código fuente:** Lib/smtplib.py

======================================================================

El módulo "smtplib" define un objeto de sesión de cliente SMTP que se
puede utilizar para enviar correo a cualquier máquina de Internet con
un demonio de escucha SMTP o ESMTP. Para obtener detalles sobre el
funcionamiento de SMTP y ESMTP, consulte **RFC 821** (Protocolo simple
de transferencia de correo) y **RFC 1869** (Extensiones de servicio
SMTP).

Availability: not Emscripten, not WASI.

Este modulo no funciona o no está disponible para plataformas
WebAssembly "wasm32-emscripten" y "wasm32-wasi". Consulte Plataformas
WebAssembly para más información.

class smtplib.SMTP(host='', port=0, local_hostname=None, [timeout, ]source_address=None)

   An "SMTP" instance encapsulates an SMTP connection.  It has methods
   that support a full repertoire of SMTP and ESMTP operations. If the
   optional *host* and *port* parameters are given, the SMTP
   "connect()" method is called with those parameters during
   initialization.  If specified, *local_hostname* is used as the FQDN
   of the local host in the HELO/EHLO command.  Otherwise, the local
   hostname is found using "socket.getfqdn()".  If the "connect()"
   call returns anything other than a success code, an
   "SMTPConnectError" is raised. The optional *timeout* parameter
   specifies a timeout in seconds for blocking operations like the
   connection attempt (if not specified, the global default timeout
   setting will be used).  If the timeout expires, "TimeoutError" is
   raised.  The optional *source_address* parameter allows binding to
   some specific source address in a machine with multiple network
   interfaces, and/or to some specific source TCP port. It takes a
   2-tuple "(host, port)", for the socket to bind to as its source
   address before connecting. If omitted (or if *host* or *port* are
   "''" and/or "0" respectively) the OS default behavior will be used.

   Para un uso normal, solo debe requerir los métodos
   initialization/connect, "sendmail()" y "SMTP.quit()". A
   continuación se incluye un ejemplo.

   La clase "SMTP" admite la instrucción "with". Cuando se usa así, el
   comando SMTP "QUIT" se emite automáticamente cuando la "with" sale
   de la instrucción. por ejemplo:

      >>> from smtplib import SMTP
      >>> with SMTP("domain.org") as smtp:
      ...     smtp.noop()
      ...
      (250, b'Ok')
      >>>

   Genera un auditing event "smtplib.send" con argumentos "self",
   "data".

   Distinto en la versión 3.3: Se agregó soporte para la sentencia
   "with".

   Distinto en la versión 3.3: se agrego el argumento source_address.

   Nuevo en la versión 3.5: La extensión SMTPUTF8 (**RFC 6531**) ahora
   es compatible.

   Distinto en la versión 3.9: Si el parámetro *timeout* se mantiene
   en cero, lanzará un "ValueError" para evitar la creación de un
   socket no bloqueante

class smtplib.SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, certfile=None, [timeout, ]context=None, source_address=None)

   Una instancia de "SMTP_SSL" se comporta exactamente igual que las
   instancias de "SMTP". "SMTP_SSL" debe usarse para situaciones donde
   se requiere SSL desde el comienzo de la conexión y el uso
   "starttls()" no es apropiado. Si no se especifica *host*, se
   utiliza el host local. Si *port* es cero, se utiliza el puerto
   estándar SMTP sobre SSL (465). Los argumentos opcionales
   *local_hostname*, *timeout* y *source_address* tienen el mismo
   significado que en la clase "SMTP". *context*, también opcional,
   puede contener una "SSLContext" y permite configurar varios
   aspectos de la conexión segura. Por favor lea Consideraciones de
   seguridad para conocer las mejores prácticas.

   *keyfile* y *certfile* son una alternativa heredada a *context* y
   pueden apuntar a una clave privada con formato PEM y un archivo de
   cadena de certificados para la conexión SSL.

   Distinto en la versión 3.3: se agregó *contexto*.

   Distinto en la versión 3.3: se agrego el argumento source_address.

   Distinto en la versión 3.4: The class now supports hostname check
   with "ssl.SSLContext.check_hostname" and *Server Name Indication*
   (see "ssl.HAS_SNI").

   Obsoleto desde la versión 3.6: *keyfile* y *certfile* están
   obsoletos en favor de *context*. Por favor use
   "ssl.SSLContext.load_cert_chain()" en su lugar, o deje que
   "ssl.create_default_context()" seleccione los certificados CA
   confiables del sistema para usted.

   Distinto en la versión 3.9: Si el parámetro *timeout* se mantiene
   en cero, lanzará un "ValueError" para evitar la creación de un
   socket no bloqueante

class smtplib.LMTP(host='', port=LMTP_PORT, local_hostname=None, source_address=None[, timeout])

   El protocolo LMTP, que es muy similar a ESMTP, se basa en gran
   medida en el cliente SMTP estándar. Es común usar sockets Unix para
   LMTP, por lo que nuestro método "connect()" debe ser compatible con
   eso, así como con un servidor host:puerto normal. Los argumentos
   opcionales local_hostname y source_address tienen el mismo
   significado que en la clase "SMTP". Para especificar un socket
   Unix, debe usar una ruta absoluta para *host*, comenzando con '/'.

   Se admite la autenticación mediante el mecanismo SMTP habitual.
   Cuando se usa un socket Unix, LMTP generalmente no admite ni
   requiere autenticación, pero su millaje puede variar.

   Distinto en la versión 3.9: Se ha añadido el parámetro opcional
   *timeout*.

También se define una buena selección de excepciones:

exception smtplib.SMTPException

   Subclase de "OSError" que es la clase de excepción base para todas
   las demás excepciones proporcionadas por este módulo.

   Distinto en la versión 3.4: SMTPException se convirtió en subclase
   de "OSError"

exception smtplib.SMTPServerDisconnected

   Esta excepción se genera cuando el servidor se desconecta
   inesperadamente o cuando se intenta usar la instancia "SMTP" antes
   de conectarlo a un servidor.

exception smtplib.SMTPResponseException

   Clase base para todas las excepciones que incluyen un código de
   error SMTP. Estas excepciones se generan en algunos casos cuando el
   servidor SMTP devuelve un código de error. El código de error se
   almacena en el atributo "smtp_code" del error, y el atributo
   "smtp_error" se establece en el mensaje de error.

exception smtplib.SMTPSenderRefused

   Dirección del remitente rechazada.  Además de los atributos
   establecidos por todas las excepciones "SMTPResponseException",
   éste establece 'remitente' para la cadena de caracteres que el
   servidor SMTP rechazó.

exception smtplib.SMTPRecipientsRefused

   Se rechazaron todas las direcciones de destinatarios.  Los errores
   para cada destinatario son accesibles mediante el atributo
   "recipients", el cual es un diccionario del mismo tipo que el
   "SMTP.sendmail()" retorna.

exception smtplib.SMTPDataError

   El servidor SMTP se negó a aceptar los datos del mensaje.

exception smtplib.SMTPConnectError

   Se produjo un error durante el establecimiento de conexión  con el
   servidor.

exception smtplib.SMTPHeloError

   El servidor rechazó nuestro mensaje "HELO".

exception smtplib.SMTPNotSupportedError

   El servidor no admite el comando o la opción que se intentó.

   Nuevo en la versión 3.5.

exception smtplib.SMTPAuthenticationError

   La autenticación SMTP salió mal.  Lo más probable es que el
   servidor no aceptó la combinación proporcionada de
   username/password.

Ver también:

  **RFC 821** - Simple Mail Transfer Protocol
     Definición de protocolo para SMTP. Este documento cubre el
     modelo, el procedimiento operativo y los detalles del protocolo
     para SMTP.

  **RFC 1869** - Extensiones de Servicio SMTP
     Definición de las extensiones ESMTP para SMTP. Esto describe un
     marco para extender SMTP con nuevos comandos, que admite el
     descubrimiento dinámico de los comandos proporcionados por el
     servidor y define algunos comandos adicionales.


Objetos SMTP
============

Una instancia "SMTP" tiene los siguientes métodos:

SMTP.set_debuglevel(level)

   Establezca el nivel de salida de depuración. Un valor de 1 o "True"
   para *level* da como resultado mensajes de depuración para la
   conexión y para todos los mensajes enviados y recibidos desde el
   servidor. Un valor de 2 para *level* da como resultado que estos
   mensajes tengan una marca de tiempo.

   Distinto en la versión 3.5: Se agregó el nivel de depuración 2.

SMTP.docmd(cmd, args='')

   Envíe un comando *cmd* al servidor. El argumento opcional *args*
   simplemente se concatena al comando, separado por un espacio.

   Esto devuelve una tupla de 2 compuestos por un código de respuesta
   numérico y la línea de respuesta real (las respuestas de varias
   líneas se unen en una línea larga).

   En funcionamiento normal, no debería ser necesario llamar a este
   método explícitamente. Se utiliza para implementar otros métodos y
   puede resultar útil para probar extensiones privadas.

   Si se pierde la conexión con el servidor mientras se espera la
   respuesta, se activará "SMTPServerDisconnected".

SMTP.connect(host='localhost', port=0)

   Conéctese a un host en un puerto determinado. Los valores
   predeterminados son para conectarse al host local en el puerto SMTP
   estándar (25). Si el nombre de host termina con dos puntos ("':'")
   seguido de un número, ese sufijo se eliminará y el número se
   interpretará como el número de puerto a utilizar. El constructor
   invoca automáticamente este método si se especifica un host durante
   la instanciación. Devuelve una tupla de 2 del código de respuesta y
   el mensaje enviado por el servidor en su respuesta de conexión.

   Genera un evento de auditoría "smtplib.connect" con argumentos
   "self", "host", "port".

SMTP.helo(name='')

   Identifíquese en el servidor SMTP usando "HELO". El argumento del
   nombre de host tiene como valor predeterminado el nombre de dominio
   completo del host local. El mensaje devuelto por el servidor se
   almacena como el atributo "helo_resp" del objeto.

   En funcionamiento normal, no debería ser necesario llamar a este
   método explícitamente. Será llamado implícitamente por "sendmail()"
   cuando sea necesario.

SMTP.ehlo(name='')

   Identifíquese en un servidor ESMTP mediante "EHLO". El argumento
   del nombre de host tiene como valor predeterminado el nombre de
   dominio completo del host local. Examine la respuesta para la
   opción ESMTP y guárdelos para que los utilice "has_extn()". También
   establece varios atributos informativos: el mensaje retornado por
   el servidor se almacena como el atributo "ehlo_resp", "does_esmtp"
   se establece en "True" o "False" dependiendo de si el servidor
   admite ESMTP, y "esmtp_features" será un diccionario que contiene
   los nombres de las extensiones de servicio SMTP de este servidor
   soportes, y sus parámetros (si los hay).

   A menos que desee utilizar "has_extn()" antes de enviar correo, no
   debería ser necesario llamar a este método explícitamente. Se
   llamará implícitamente por "sendmail()" cuando sea necesario.

SMTP.ehlo_or_helo_if_needed()

   Este método llama a "ehlo()" o "helo()" si no ha habido ningún
   comando "EHLO" o "HELO" anterior en esta sesión. Primero prueba
   ESMTP "EHLO".

   "SMTPHeloError"
      El servidor no respondió correctamente al saludo "HELO".

SMTP.has_extn(name)

   Retorna "True" si *name* está en el conjunto de extensiones de
   servicio SMTP devueltas por el servidor, "False" en caso contrario.
   El método es insensible a la presencia de mayúsculas en *name*.

SMTP.verify(address)

   Verifique la validez de una dirección en este servidor usando SMTP
   "VRFY". Retorna una tupla que consta del código 250 y una dirección
   completa **RFC 822** (incluido el nombre humano) si la dirección
   del usuario es válida. De lo contrario, devuelve un código de error
   SMTP de 400 o más y una cadena de error.

   Nota:

     Muchos sitios desactivan SMTP "VRFY" para frustrar a los
     spammers.

SMTP.login(user, password, *, initial_response_ok=True)

   Inicie sesión en un servidor SMTP que requiera autenticación. Los
   argumentos son el nombre de usuario y la contraseña para
   autenticarse. Si no ha habido ningún comando "EHLO" o "HELO"
   anterior en esta sesión, este método prueba primero ESMTP "EHLO".
   Este método regresará normalmente si la autenticación fue exitosa o
   puede generar las siguientes excepciones:

   "SMTPHeloError"
      El servidor no respondió correctamente al saludo "HELO".

   "SMTPAuthenticationError"
      El servidor no aceptó la combinación de nombre de
      username/password.

   "SMTPNotSupportedError"
      El servidor no admite el comando "AUTH".

   "SMTPException"
      No se encontró ningún método de autenticación adecuado.

   Cada uno de los métodos de autenticación admitidos por "smtplib" se
   prueban a su vez si se anuncian como admitidos por el servidor.
   Consulte "auth()" para obtener una lista de los métodos de
   autenticación admitidos. *initial_response_ok* se pasa a "auth()".

   El argumento de palabra clave opcional *initial_response_ok*
   especifica si, para los métodos de autenticación que lo admiten, se
   puede enviar una "respuesta inicial" como se especifica en **RFC
   4954** junto con el comando "AUTH", en lugar de requerir un
   desafío/respuesta .

   Distinto en la versión 3.5: "SMTPNotSupportedError" se puede
   generar y se agregó el parámetro *initial_response_ok*.

SMTP.auth(mechanism, authobject, *, initial_response_ok=True)

   Emita un comando "SMTP" "AUTH" para el *mechanism* de autenticación
   especificado y maneje la respuesta de desafío a través de
   *authobject*.

   *mechanism* especifica qué mecanismo de autenticación se utilizará
   como argumento para el comando "AUTH"; los valores válidos son los
   enumerados en el elemento "auth" de "esmtp_features".

   *authobject* debe ser un objeto invocable que tome un único
   argumento opcional:

      data = authobject(challenge=None)

   Si la verificación de respuesta inicial devuelve "None", o si
   *initial_response_ok* es falso, se llamará a "authobject()" para
   procesar la respuesta de desafío del servidor; el argumento
   *challenge* que se pasa será un "bytes". Debería devolver *data*
   ASCII "str" que serán codificados en base64 y enviados al servidor.

   Si la verificación de respuesta inicial devuelve "None", o si
   *initial_response_ok* es falso, se llamará a "authobject()" para
   procesar la respuesta de desafío del servidor; el argumento
   *challenge* que se pasa será un "bytes". Debería devolver *data*
   ASCII "str" que serán codificados en base64 y enviados al servidor.

   La clase "SMTP" proporciona "authobjects" para los mecanismos
   "CRAM-MD5", "PLAIN" y "LOGIN"; se denominan "SMTP.auth_cram_md5",
   "SMTP.auth_plain" y "SMTP.auth_login" respectivamente. Todos
   requieren que las propiedades de "user" y "password" de la
   instancia "SMTP" se establezcan en los valores adecuados.

   El código de usuario normalmente no necesita llamar a "auth"
   directamente, sino que puede llamar al método "login()", que
   probará cada uno de los mecanismos anteriores a su vez, en el orden
   indicado. "auth" está expuesto para facilitar la implementación de
   métodos de autenticación que no (o aún no) son compatibles
   directamente con "smtplib".

   Nuevo en la versión 3.5.

SMTP.starttls(keyfile=None, certfile=None, context=None)

   Ponga la conexión SMTP en modo TLS (Seguridad de la capa de
   transporte). Todos los comandos SMTP que siguen se cifrarán.
   Entonces deberías llamar a "ehlo()" de nuevo.

   Si se proporcionan *keyfile* y *certfile*, se utilizan para crear
   una "ssl.SSLContext".

   El parámetro *context* opcional es un objeto "ssl.SSLContext"; Esta
   es una alternativa al uso de un archivo de claves y un archivo de
   certificado y, si se especifica, tanto *keyfile* como *certfile*
   deben ser "None".

   Si no ha habido ningún comando "EHLO" o "HELO" anterior en esta
   sesión, este método intenta ESMTP "EHLO" primero.

   Obsoleto desde la versión 3.6: *keyfile* y *certfile* están
   obsoletos en favor de *context*. Por favor use
   "ssl.SSLContext.load_cert_chain()" en su lugar, o deje que
   "ssl.create_default_context()" seleccione los certificados CA
   confiables del sistema para usted.

   "SMTPHeloError"
      El servidor no respondió correctamente al saludo "HELO".

   "SMTPNotSupportedError"
      El servidor no admite la extensión STARTTLS.

   "RuntimeError"
      La compatibilidad con SSL/TLS no está disponible para su
      intérprete de Python.

   Distinto en la versión 3.3: se agregó *contexto*.

   Distinto en la versión 3.4: The method now supports hostname check
   with "SSLContext.check_hostname" and *Server Name Indicator* (see
   "HAS_SNI").

   Distinto en la versión 3.5: El error generado por falta de
   compatibilidad con STARTTLS ahora es la subclase
   "SMTPNotSupportedError" en lugar de la base "SMTPException".

SMTP.sendmail(from_addr, to_addrs, msg, mail_options=(), rcpt_options=())

   Enviar correo. Los argumentos requeridos son **RFC 822** cadena de
   dirección de origen, una lista de **RFC 822** cadenas de dirección
   (una cadena simple se tratará como una lista con 1 dirección) y una
   cadena de mensaje. La persona que llama puede pasar una lista de
   opciones de ESMTP (como "8bitmime") para usar en los comandos "MAIL
   FROM" como *mail_options*. Las opciones de ESMTP (como los comandos
   "DSN") que deben usarse con todos los comandos "RCPT" se pueden
   pasar como *rcpt_options*. (Si necesita usar diferentes opciones de
   ESMTP para diferentes destinatarios, debe usar los métodos de bajo
   nivel como "mail()", "rcpt()" y "data()" para enviar el mensaje).

   Nota:

     Los parámetros *from_addr* y *to_addrs* se utilizan para
     construir el sobre del mensaje utilizado por los agentes de
     transporte. "sendmail" no modifica los encabezados de los
     mensajes de ninguna manera.

   *msg* puede ser una cadena que contenga caracteres en el rango
   ASCII o una cadena de bytes. Una cadena se codifica en bytes
   utilizando el códec ascii, y los caracteres "\r" y "\n" solitarios
   se convierten en caracteres "\ r\n". Una cadena de bytes no se
   modifica.

   Si no ha habido ningún comando "EHLO" o "HELO" anterior en esta
   sesión, este método prueba primero ESMTP "EHLO". Si el servidor
   utiliza ESMTP, se le pasará el tamaño del mensaje y cada una de las
   opciones especificadas (si la opción está en el conjunto de
   funciones que anuncia el servidor). Si "EHLO" falla, se probará
   "HELO" y se eliminarán las opciones de ESMTP.

   Este método volverá normalmente si se acepta el correo para al
   menos un destinatario. De lo contrario, lanzará una excepción. Es
   decir, si este método no genera una excepción, alguien debería
   recibir su correo. Si este método no genera una excepción, devuelve
   un diccionario, con una entrada para cada destinatario rechazado.
   Cada entrada contiene una tupla del código de error SMTP y el
   mensaje de error adjunto enviado por el servidor.

   Si se incluye "SMTPUTF8"' en *mail_options * y el servidor lo
   admite, *from_addr* y *to_addrs* pueden contener caracteres no
   ASCII.

   Este método puede lanzar las siguientes excepciones:

   "SMTPRecipientsRefused"
      Todos los destinatarios fueron rechazados. Nadie recibió el
      correo. El atributo "recipients" del objeto de excepción es un
      diccionario con información sobre los destinatarios rechazados
      (como el que se retorna cuando se aceptó al menos un
      destinatario).

   "SMTPHeloError"
      El servidor no respondió correctamente al saludo "HELO".

   "SMTPSenderRefused"
      El servidor no aceptó el *from_addr*.

   "SMTPDataError"
      El servidor respondió con un código de error inesperado (que no
      sea el rechazo de un destinatario).

   "SMTPNotSupportedError"
      Se proporcionó "SMTPUTF8" en *mail_options* pero el servidor no
      lo admite.

   A menos que se indique lo contrario, la conexión estará abierta
   incluso después de que se lance una excepción.

   Distinto en la versión 3.2: *msg* puede ser una cadena de bytes.

   Distinto en la versión 3.5: Se agregó compatibilidad con
   "SMTPUTF8", así que la "SMTPNotSupportedError" puede ser lanzada si
   se especifica "SMTPUTF8" ya que el servidor no lo admite.

SMTP.send_message(msg, from_addr=None, to_addrs=None, mail_options=(), rcpt_options=())

   Este es un método conveniente para llamar a "sendmail()" con el
   mensaje representado por un objeto "email.message.Message". Los
   argumentos tienen el mismo significado que para "sendmail()",
   excepto que *msg* es un objeto "Mensaje".

   Si *from_addr* es "None" o *to_addrs* es "None", "send_message"
   llena esos argumentos con direcciones extraídas de los encabezados
   de *msg* como se especifica en **RFC 5322**: *from_addr* se
   establece en el campo *Sender* si está presente, y de lo contrario,
   en el campo *From*. *to_addrs* combina los valores (si los hay) de
   los campos *To*, *Cc* y *Bcc* de *msg*. Si aparece exactamente un
   conjunto de encabezados *Resent-** en el mensaje, los encabezados
   normales se ignoran y en su lugar se utilizan los encabezados
   *Resent- **. Si el mensaje contiene más de un conjunto de
   encabezados *Resent-**, se lanza un "ValueError", ya que no hay
   forma de detectar sin ambigüedades el conjunto más reciente de
   encabezados *Resent-*.

   "send_message" serializa *msg* usando "BytesGenerator" con "\r\n"
   como *linesep*, y llama a "sendmail()" para transmitir el mensaje
   resultante.  Independientemente de los valores de *from_addr* y
   *to_addrs*, "send_message" no transmite ningún encabezado *Bcc* o
   *Resent-Bcc* que puedan aparecer en *msg*.  Si alguna de las
   direcciones en *from_addr* y *to_addrs* contiene caracteres que no
   son ASCII y el servidor no anuncia la compatibilidad con
   "SMTPUTF8", se lanza un error "SMTPNotSupported".  De lo contrario,
   el "Message" se serializa con un clon de su "policy" con el
   atributo "utf8" establecido en "True" y "SMTPUTF8" y
   "BODY=8BITMIME" se agregan a *mail_options*.

   Nuevo en la versión 3.2.

   Nuevo en la versión 3.5: Soporte para direcciones
   internacionalizadas ("SMTPUTF8").

SMTP.quit()

   Termine la sesión SMTP y cierre la conexión.  Retorna el resultado
   del comando SMTP "QUIT".

Los métodos de bajo nivel correspondientes a los comandos estándar
SMTP/ESMTP "`HELP", "RSET", "NOOP", "MAIL", "RCPT", y "DATA" también
están soportados. Normalmente, no es necesario llamarlos directamente,
por lo que no se documentan aquí. Para más detalles, consulte el
código del módulo.


Ejemplo SMTP
============

Este ejemplo solicita al usuario las direcciones necesarias en el
sobre del mensaje (direcciones 'To' y 'From' ) y el mensaje que se
entregará. Tenga en cuenta que los encabezados que se incluirán con el
mensaje deben incluirse en el mensaje tal y como se introdujeron; este
ejemplo no procesa los encabezados **RFC 822** . En particular, las
direcciones 'To' y 'From deben incluirse explícitamente en los
encabezados de los mensajes.

   import smtplib

   def prompt(prompt):
       return input(prompt).strip()

   fromaddr = prompt("From: ")
   toaddrs  = prompt("To: ").split()
   print("Enter message, end with ^D (Unix) or ^Z (Windows):")

   # Add the From: and To: headers at the start!
   msg = ("From: %s\r\nTo: %s\r\n\r\n"
          % (fromaddr, ", ".join(toaddrs)))
   while True:
       try:
           line = input()
       except EOFError:
           break
       if not line:
           break
       msg = msg + line

   print("Message length is", len(msg))

   server = smtplib.SMTP('localhost')
   server.set_debuglevel(1)
   server.sendmail(fromaddr, toaddrs, msg)
   server.quit()

Nota:

  En general, querrá usar las características del paquete "email" para
  construir un mensaje de correo electrónico, que luego puede enviar a
  través de "send_message()"; ver email: Ejemplos.
