Home

Awesome

<p align="center"> <img src="./docs/_static/icon.png" width="48px"/> </p>

yagmail -- Yet Another GMAIL/SMTP client

Join the chat at https://gitter.im/kootenpv/yagmail PyPI PyPI

For the asynchronous asyncio version, look here: https://github.com/kootenpv/aioyagmail

The goal here is to make it as simple and painless as possible to send emails.

In the end, your code will look something like this:

import yagmail
yag = yagmail.SMTP('mygmailusername', 'mygmailpassword')
contents = ['This is the body, and here is just text http://somedomain/image.png',
            'You can find an audio file attached.', '/local/path/song.mp3']
yag.send('to@someone.com', 'subject', contents)

In 2020, I personally prefer: using an Application-Specific Password

Table of Contents

SectionExplanation
InstallFind the instructions on how to install yagmail here
Start a connectionGet started
UsabilityShows some usage patterns for sending
RecipientsHow to send to multiple people, give an alias or send to self
Magical contentsReally easy to send text, html, images and attachments
Attaching filesHow attach files to the email
DKIM SupportAdd DKIM signature to your emails with your private key
FeedbackHow to send me feedback
Roadmap (and priorities)Yup
ErrorsList of common errors for people dealing with sending emails

Install

For Python 2.x and Python 3.x respectively:

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

As a side note, yagmail can now also be used to send emails from the command line.

Start a connection

yag = yagmail.SMTP('mygmailusername', 'mygmailpassword')

Note that this connection is reusable, closable and when it leaves scope it will clean up after itself in CPython.

As tilgovi points out in #39, SMTP does not automatically close in PyPy. The context manager with should be used in that case.

Usability

Defining some variables:

to = 'santa@someone.com'
to2 = 'easterbunny@someone.com'
to3 = 'sky@pip-package.com'
subject = 'This is obviously the subject'
body = 'This is obviously the body'
html = '<a href="https://pypi.python.org/pypi/sky/">Click me!</a>'
img = '/local/file/bunny.png'

All variables are optional, and know that not even to is required (you'll send an email to yourself):

yag.send(to = to, subject = subject, contents = body)
yag.send(to = to, subject = subject, contents = [body, html, img])
yag.send(contents = [body, img])

Furthermore, if you do not want to be explicit, you can do the following:

yag.send(to, subject, [body, img])

Recipients

It is also possible to send to a group of people by providing a list of email strings rather than a single string:

yag.send(to = to)
yag.send(to = [to, to2]) # List or tuples for emailadresses *without* aliases
yag.send(to = {to : 'Alias1'}) # Dictionary for emailaddress *with* aliases
yag.send(to = {to : 'Alias1', to2 : 'Alias2'}

Giving no to argument will send an email to yourself. In that sense, yagmail.SMTP().send() can already send an email. Be aware that if no explicit to = ... is used, the first argument will be used to send to. Can be avoided like:

yag.send(subject = 'to self', contents = 'hi!')

Note that by default all email addresses are conservatively validated using soft_email_validation==True (default).

Oauth2

It is even safer to use Oauth2 for authentication, as you can revoke the rights of tokens.

This is one of the best sources, upon which the oauth2 code is heavily based.

The code:

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

It will prompt for a google_client_id and a google_client_secret, when the file cannot be found. These variables can be obtained following the previous link.

After you provide them, a link will be shown in the terminal that you should followed to obtain a google_refresh_token. Paste this again, and you're set up!

Note that people who obtain the file can send emails, but nothing else. As soon as you notice, you can simply disable the token.

Preventing OAuth authorization from expiring after 7 days

Your Google Cloud Platform project's OAuth consent screen must be in "In production" publishing status before authorizing to not have the authorization expire after 7 days. See status at https://console.cloud.google.com/apis/credentials/consent

Your OAuth client ID must be of type "Desktop". Check at https://console.cloud.google.com/apis/credentials

Magical contents

The contents argument will be smartly guessed. It can be passed a string (which will be turned into a list); or a list. For each object in the list:

Note that local files can be html (inline); everything else will be attached.

Local files require to have an extension for their content type to be inferred.

As of version 0.4.94, raw and inline have been added.

Attaching Files

There are multiple ways to attach files in the attachments parameter (in addition to magical contents parameter).

  1. One can pass a list of paths i.e.
yag.send(to=recipients,
         subject=email_subject,
         contents=contents,
         attachments=['path/to/attachment1.png', 'path/to/attachment2.pdf', 'path/to/attachment3.zip']
)
  1. One can pass an instance of io.IOBase.
with open('path/to/attachment', 'rb') as f:
    yag.send(to=recipients,
             subject=email_subject,
             contents=contents,
             attachments=f
             )

In this example f is an instance of _io.BufferedReader a subclass of the abstract class io.IOBase.

f has in this example the attribute .name, which is used by yagmail as filename as well as to detect the correct MIME-type. Not all io.IOBase instances have the .name attribute in which case yagmail names the attachments attachment1, attachment2, ... without a file extension! Therefore, it is highly recommended setting the filename with extension manually e.g. f.name = 'my_document.pdf'

A real-world example would be if the attachment is retrieved from a different source than the disk (e.g. downloaded from the internet or uploaded by a user in a web-application)

DKIM Support

To send emails with dkim signature, you need to install the package with all related packages.

pip install yagmail[all]
# or
pip install yagmail[dkim]

Usage:

from yagmail import SMTP
from yagmail.dkim import DKIM
from pathlib import Path

# load private key from file/secrets manager
private_key = Path("privkey.pem").read_bytes()

dkim_obj = DKIM(
  domain=b"a.com",
  selector=b"selector",
  private_key=private_key,
  include_headers=[b"To", b"From", b"Subject"],
  # To include all default headers just pass None instead
  # include_headers=None,
)

yag = SMTP(dkim=dkim_obj)

# all the rest is the same

Feedback

I'll try to respond to issues within 24 hours at Github.....

And please send me a line of feedback with SMTP().feedback('Great job!') :-)

Roadmap (and priorities)

Errors

Donate

If you like yagmail, feel free (no pun intended) to donate any amount you'd like :-)

PayPal