Nota
¡Ayúdanos a traducir la documentación oficial de Python al Español! Puedes encontrar más información en Como contribuir. Ayuda a acercar Python a más personas de habla hispana.
email
— Un paquete de manejo de correo electrónico y MIME¶
Código fuente Lib/email/__init__.py
El paquete email
es una biblioteca para administrar mensajes de correo electrónico. Específicamente no está diseñado para realizar cualquier envío de mensajes de correo electrónico a SMTP (RFC 2821), NNTP u otros servidores; esas son funciones de módulos como smtplib
y nntplib
. El paquete email
intenta ser lo más compatible con RFC, admitiendo RFC 5322 y RFC 6532, así como RFC relacionados con MIME como RFC 2045, RFC 2046, RFC 2047, RFC 2183 y RFC 2231.
La estructura general del paquete de correo electrónico se puede dividir en tres componentes principales, más un cuarto componente que controla el comportamiento de los otros componentes.
El componente central del paquete es un «modelo de objetos» que representa los mensajes de correo electrónico. Una aplicación interactúa con el paquete principalmente a través de la interfaz del modelo de objetos definida en el submódulo message
. La aplicación puede usar esta API para hacer preguntas sobre un correo electrónico existente, para construir un nuevo correo electrónico o para agregar o eliminar subcomponentes de correo electrónico que utilizan la misma interfaz de modelo de objetos. Es decir, siguiendo la naturaleza de los mensajes de correo electrónico y sus subcomponentes MIME, el modelo de objetos de correo electrónico es una estructura de árbol de objetos que proporcionan la API EmailMessage
.
Los otros dos componentes principales del paquete son parser
y generator
. El parser toma la versión serializada de un mensaje de correo electrónico (una secuencia de bytes) Y la convierte en un árbol de objetos EmailMessage
. El generador toma un EmailMessage
y lo convierte de nuevo en un flujo de bytes serializado. (El analizador y el generador también manejan flujos de caracteres de texto, pero se desaconseja este uso ya que es demasiado fácil terminar con mensajes que no son válidos de una forma u otra).
El componente de control es el módulo de policy
. Cada EmailMessage
cada generator
, y cada parser
tiene un objeto de policy
asociado que controla su comportamiento. Por lo general, una aplicación solo necesita especificar la política cuando se crea un EmailMessage
, ya sea instanciando directamente un EmailMessage
para crear un nuevo correo electrónico o analizando un flujo de entrada con un parser
. Pero la política se puede cambiar cuando el mensaje se serializa mediante un generator
. Esto permite, por ejemplo, analizar un mensaje de correo electrónico genérico desde el disco, pero serializarlo utilizando la configuración estándar de SMTP al enviarlo a un servidor de correo electrónico.
El paquete de correo electrónico hace todo lo posible para ocultar los detalles de las diversas RFC que rigen de la aplicación. Conceptualmente, la aplicación debería poder tratar el mensaje de correo electrónico como un árbol estructurado de texto Unicode y archivos adjuntos binarios, sin tener que preocuparse por cómo se representan estos cuando se serializan. En la práctica, sin embargo, a menudo es necesario conocer al menos algunas de las reglas que rigen los mensajes MIME y su estructura, específicamente los nombres y la naturaleza de los «tipos de contenido» MIME y cómo identifican los documentos de varias partes. En su mayor parte, este conocimiento solo debería ser necesario para aplicaciones más complejas, e incluso entonces debería ser solo la estructura de alto nivel en cuestión, y no los detalles de cómo se representan esas estructuras. Dado que los tipos de contenido MIME se utilizan ampliamente en el software moderno de Internet (no solo en el correo electrónico), este será un concepto familiar para muchos programadores.
Las siguientes secciones describen la funcionalidad del paquete email
. Comenzamos con el modelo de objetos message
, que es la interfaz principal que usará una aplicación, y lo seguimos con los componentes del parser
y generator
. Luego cubrimos los controles de la policy
, lo que completa el tratamiento de los principales componentes de la biblioteca.
Las siguientes tres secciones cubren las excepciones que puede generar el paquete y los defectos (incumplimiento de las RFC) que el parser
puede detectar. Luego cubrimos los subcomponentes headerregistry
y contentmanager
, que proporcionan herramientas para realizar una manipulación más detallada de los encabezados y cargas útiles, respectivamente. Ambos componentes contienen características relevantes para consumir y producir mensajes no triviales, pero también documentan sus API de extensibilidad, que serán de interés para aplicaciones avanzadas.
A continuación, se muestra un conjunto de ejemplos del uso de las partes fundamentales de las API cubiertas en las secciones anteriores.
Lo anterior representa la API moderna (compatible con Unicode) del paquete de correo electrónico. Las secciones restantes, comenzando con la clase Message
, cubren la API compat32
heredada que trata mucho más directamente con los detalles de cómo se representan los mensajes de correo electrónico. La API compat32
no oculta los detalles de las RFC de la aplicación, pero para las aplicaciones que necesitan operar a ese nivel, pueden ser herramientas útiles. Esta documentación también es relevante para las aplicaciones que todavía usan la API compat32
por razones de compatibilidad con versiones anteriores.
Distinto en la versión 3.6: Documentos reorganizados y reescritos para promover la nueva API EmailMessage
/EmailPolicy
.
Contenido de la documentación del paquete email
:
email.message
: Representando un mensaje de correo electrónicoEmailMessage
EmailMessage.as_string()
EmailMessage.__str__()
EmailMessage.as_bytes()
EmailMessage.__bytes__()
EmailMessage.is_multipart()
EmailMessage.set_unixfrom()
EmailMessage.get_unixfrom()
EmailMessage.__len__()
EmailMessage.__contains__()
EmailMessage.__getitem__()
EmailMessage.__setitem__()
EmailMessage.__delitem__()
EmailMessage.keys()
EmailMessage.values()
EmailMessage.items()
EmailMessage.get()
EmailMessage.get_all()
EmailMessage.add_header()
EmailMessage.replace_header()
EmailMessage.get_content_type()
EmailMessage.get_content_maintype()
EmailMessage.get_content_subtype()
EmailMessage.get_default_type()
EmailMessage.set_default_type()
EmailMessage.set_param()
EmailMessage.del_param()
EmailMessage.get_filename()
EmailMessage.get_boundary()
EmailMessage.set_boundary()
EmailMessage.get_content_charset()
EmailMessage.get_charsets()
EmailMessage.is_attachment()
EmailMessage.get_content_disposition()
EmailMessage.walk()
EmailMessage.get_body()
EmailMessage.iter_attachments()
EmailMessage.iter_parts()
EmailMessage.get_content()
EmailMessage.set_content()
EmailMessage.make_related()
EmailMessage.make_alternative()
EmailMessage.make_mixed()
EmailMessage.add_related()
EmailMessage.add_alternative()
EmailMessage.add_attachment()
EmailMessage.clear()
EmailMessage.clear_content()
EmailMessage.preamble
EmailMessage.epilogue
EmailMessage.defects
MIMEPart
email.parser
: Analizar mensajes de correo electrónicoemail.generator
: Generando documentos MIMEemail.policy
: Objetos PolicyPolicy
Policy.max_line_length
Policy.linesep
Policy.cte_type
Policy.raise_on_defect
Policy.mangle_from_
Policy.message_factory
Policy.clone()
Policy.handle_defect()
Policy.register_defect()
Policy.header_max_count()
Policy.header_source_parse()
Policy.header_store_parse()
Policy.header_fetch_parse()
Policy.fold()
Policy.fold_binary()
EmailPolicy
default
SMTP
SMTPUTF8
HTTP
strict
Compat32
compat32
email.errors
: Clases de excepción y defectoemail.headerregistry
: Objetos de encabezado personalizadosemail.contentmanager
: Gestión de contenido MIMEemail
: Ejemplos
API heredada:
email.message.Message
: Representar un mensaje de correo electrónico usando la APIcompat32
Message
Message.as_string()
Message.__str__()
Message.as_bytes()
Message.__bytes__()
Message.is_multipart()
Message.set_unixfrom()
Message.get_unixfrom()
Message.attach()
Message.get_payload()
Message.set_payload()
Message.set_charset()
Message.get_charset()
Message.__len__()
Message.__contains__()
Message.__getitem__()
Message.__setitem__()
Message.__delitem__()
Message.keys()
Message.values()
Message.items()
Message.get()
Message.get_all()
Message.add_header()
Message.replace_header()
Message.get_content_type()
Message.get_content_maintype()
Message.get_content_subtype()
Message.get_default_type()
Message.set_default_type()
Message.get_params()
Message.get_param()
Message.set_param()
Message.del_param()
Message.set_type()
Message.get_filename()
Message.get_boundary()
Message.set_boundary()
Message.get_content_charset()
Message.get_charsets()
Message.get_content_disposition()
Message.walk()
Message.preamble
Message.epilogue
Message.defects
email.mime
: Creación de correo electrónico y objetos MIME desde ceroemail.header
: Cabeceras internacionalizadasemail.charset
: Representa conjunto de caracteresCharset
Charset.input_charset
Charset.header_encoding
Charset.body_encoding
Charset.output_charset
Charset.input_codec
Charset.output_codec
Charset.get_body_encoding()
Charset.get_output_charset()
Charset.header_encode()
Charset.header_encode_lines()
Charset.body_encode()
Charset.__str__()
Charset.__eq__()
Charset.__ne__()
add_charset()
add_alias()
add_codec()
email.encoders
: Codificadoresemail.utils
: Utilidades misceláneasemail.iterators
: Iteradores
Ver también
- Módulo
smtplib
Cliente SMTP (Protocolo simple de transporte de correo)
- Módulo
poplib
Cliente POP (Protocolo de oficina postal)
- Módulo
imaplib
Cliente IMAP (Protocolo de acceso a mensajes de Internet)
- Módulo
nntplib
Cliente NNTP (Protocolo de transporte de noticias de red)
- Módulo
mailbox
Herramientas para crear, leer y administrar colecciones de mensajes en disco utilizando una variedad de formatos estándar.