Add simple usage to email module

[tarao1006]

BPO	45994
Nosy	@ericvsmith, @tarao1006

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2021-12-06.10:44:20.384>
labels = ['type-feature', '3.10', 'docs']
title = 'Add simple usage to email module'
updated_at = <Date 2021-12-06.16:51:58.791>
user = 'https://github.com/tarao1006'

bugs.python.org fields:

activity = <Date 2021-12-06.16:51:58.791>
actor = 'tarao1006'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-12-06.10:44:20.384>
creator = 'tarao1006'
dependencies = []
files = []
hgrepos = []
issue_num = 45994
keywords = []
message_count = 2.0
messages = ['407803', '407839']
nosy_count = 3.0
nosy_names = ['eric.smith', 'docs@python', 'tarao1006']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue45994'
versions = ['Python 3.10']

[ericvsmith]

What sort of usage example would help you?

Is https://docs.python.org/3/library/email.examples.html lacking something?

[tarao1006]

There are the simplest example to send text email and a little bit complicated example to an email with some files.

However, beginners like me want simple example to create an email composed of the combination of multipart/alternative and multipart/mixed.

There are many web sites to explain sending an email composed of multipart/alternative and multipart/mixed, but all of them use MIMEText and MIMEMultipart, which can be replaced and simplified with EmailMessage like below.

import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg['From'] = 'from@example.com'
msg['To'] = 'to@example.com'
msg['Subject'] = 'Subject'

msg.add_alternative('Hello, world.', subtype='text')
msg.add_alternative('<h1>Helo, world.</h1>', subtype='html')
with open('example.pdf', 'rb') as f:
    msg.add_attachment(
        f.read(),
        maintype='application',
        subtype='pdf',
        filename='example.pdf'
    )

with smtplib.SMTP('SMTP_HOST', 'SMTP_PORT') as smtp:
    smtp.starttls()
    smtp.login('USER', 'PASSWORD')
    smtp.send_message(msg)

Of cause I know we can obtain the code above from the combination of existing example codes, but it's a little bit difficult.

I guess the reason why they cannot find simple way partially because the official documentation does not provide example.