Usage¶
This document aims to show how to use yagmail
in your programs.
Most of what is shown here is also available to see in the
README, some content may be
duplicated for completeness.
Start a Connection¶
As mentioned in Configuring Credentials, there
are three ways to initialize a connection by instantiating
yagmail.SMTP
:
1. With Username and Password:
e.g. yagmail.SMTP('mygmailusername', 'mygmailpassword')
This method is not recommended, since you would be storing
the full credentials to your account in your script in plain text.
A better alternative is using keyring
, as described in the
following section:
2. With Username and keyring:
After registering a keyring
entry for yagmail
, you can
instantiate the client by simply passing your username, e.g.
yagmail.SMTP('mygmailusername')
.
3. With keyring and .yagmail:
As explained in the Setup documentation, you can also
omit the username if you have a .yagmail
file in your
home folder, containing just your GMail username. This way,
you can initialize yagmail.SMTP
without any arguments.
4. With OAuth2:
This is probably the safest method of authentication, as you
can revoke the rights of tokens. To initialize with OAuth2
credentials (after obtaining these as shown in Setup),
simply pass an oauth2_file
to yagmail.SMTP
,
for example yagmail.SMTP('user@gmail.com', oauth2_file='~/oauth2_creds.json')
.
Closing and reusing the Connection¶
By default, yagmail.SMTP
will clean up after itself
in CPython. This is an implementation detail of CPython and as such
may not work in other implementations such as PyPy (reported in
issue #39). In those
cases, you can use yagmail.SMTP
with with
instead.
Alternatively, you can close and re-use the connection with
yagmail.SMTP.close()
and yagmail.SMTP.login()
(or
yagmail.SMTP.oauth2_file()
if you are using OAuth2).
Sending E-Mails¶
yagmail.SMTP.send()
is a fairly versatile method that allows
you to adjust more or less anything about your Mail.
First of all, all parameters for yagmail.SMTP.send()
are optional.
If you omit the recipient (specified with to
), you will send an
E-Mail to yourself.
Since the use of the (keyword) arguments of yagmail.SMTP.send()
are fairly obvious, they will simply be listed here:
to
subject
contents
attachments
cc
bcc
preview_only
headers
Some of these - namely to
and contents
- have some magic
associated with them which will be outlined in the following sections.
E-Mail recipients¶
You can send an E-Mail to a single user by simply passing
a string with either a GMail username (@gmail.com
will be appended
automatically), or with a full E-Mail address:
yag.send(to='mike@gmail.com', contents="Hello, Mike!")
Alternatively, you can send E-Mails to a group of people by either passing
a list or a tuple of E-Mail addresses as to
:
yag.send(to=['to@someone.com', 'for@someone.com'], contents="Hello there!")
These E-Mail addresses were passed without any aliases.
If you wish to use aliases for the E-Mail addresses, provide a
dictionary mapped in the form {address: alias}
, for example:
recipients = {
'aliased@mike.com': 'Mike',
'aliased@fred.com': 'Fred'
}
yag.send(to=recipients, contents="Hello, Mike and Fred!")
Magical contents
¶
The contents
argument of yagmail.SMTP.send()
will be smartly guessed.
You can pass it a string with your contents or a list of elements which are either:
- If it is a dictionary, then it will be assumed that the key is the content and the value is an alias (currently, this only applies to images). For example:
contents = [
"Hello Mike! Here is a picture I took last week:",
{'path/to/my/image.png': 'PictureForMike'}
]
- If it is a string, then it will first check whether the content of the string can be read as a file locally, for example
'path/to/my/image.png'
. These files require an extension for their content type to be inferred. - If it could not be read locally, then it checks whether the string is valid HTML, such as
<h1>This is a big title!</h1>
. - If it was not valid HTML either, then it must be text, such as
"Hello, Mike!"
.
If you want to ensure that a string is treated as text and should not be checked
for any other content as described above, you can use yagmail.raw
, a subclass
of str
.
If you intend to inline an image instead of attaching it, you can use
yagmail.inline
.
Using yagmail from the command line¶
yagmail
includes a command-line application, simply called with yagmail
after you installed it. To view a full reference on how to use this, run
yagmail --help
.