Setup

This page shows you how to install yagmail and how to set it up to use your system keyring service.

Installing from PyPI

The usual way of installing yagmail is through PyPI. It is recommended to install it together with the keyring library, by running the following (for Python 2.x and 3.x respectively):

pip install yagmail[all]
pip3 install yagmail[all]

If installing yagmail with keyring causes issues, omit the [all] to install it without.

Installing from GitHub

If you’re not scared of things occasionally breaking, you can also install directly from the GitHub repository. You can do this by running the following (for Python 2.x and 3.x respectively):

pip install -e git+https://github.com/kootenpv/yagmail#egg=yagmail[all]
pip3 install -e git+https://github.com/kootenpv/yagmail#egg=yagmail[all]

Just like with the PyPI installation method, if installing with keyring causes issues, simply omit the [all] to install yagmail without it.

Configuring Credentials

While it’s possible to put the username and password for your E-Mail address into your script, yagmail enables you to omit both. Quoting from keyrings README:

What is Python keyring lib?

The Python keyring lib provides a easy way to access the system
keyring service from python. It can be used in any
application that needs safe password storage.

If this sparked your interest, set up a Python interpreter and run the following to register your GMail credentials with yagmail:

import yagmail
yagmail.register('mygmailusername', 'mygmailpassword')

(this is just a wrapper for keyring.set_password('yagmail', 'mygmailusername', 'mygmailpassword'))

Note

For GMail, you must use an Application-Specific Password as the password (your regular Google account password will no longer work over SMTP).

Now, instantiating yagmail.Client is as easy as doing:

yag = yagmail.Client('mygmailusername')

If you want to also omit your username, you can create a .yagmail file in your home folder, containing just your username. Then, you can instantiate the client without passing any arguments. (Note that ~/.yagmail is completely optional; if it is absent and you do not pass a user argument, a ValueError will be raised).

Using OAuth2

Another safe method for authenticating is using OAuth2, which allows you to revoke token permissions easily. To use OAuth2, pass the location of the credentials file to yagmail.Client:

yag = yagmail.Client('user@gmail.com', oauth2_file='~/oauth2_creds.json')
yag.send(subject="Great!")

If the file could not be found, then it will prompt for a google_client_id and google_client_secret. You can obtain these on this OAauth2 Guide, upon which the OAauth2 code of yagmail is heavily based. After you have provided these, a link will be shown in the terminal that you should follow to obtain a google_refresh_token. Paste this again, and you’re set up!

Important

By default, Google OAuth tokens expire after 7 days unless your Google Cloud Platform (GCP) project has a publishing status of “In production”.

For personal use: * Go to your Google Cloud Console and set the publishing status to “In production” (Publish App). You can click through any unverified-app warnings that appear during authorization. * Ensure your OAuth Client ID type is set to “Desktop”.

If somebody obtains the file, they can send E-Mails, but nothing else. As soon as you notice, you can simply disable the token.