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()
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('[email protected]', 'subject', contents)
Or a simple one-liner:
yagmail.SMTP('mygmailusername').send('[email protected]', 'subject', 'This is the body')
Note that it will read the password securely from your keyring (read below). If you don't want this, you can also initialize with:
yag = yagmail.SMTP('mygmailusername', 'mygmailpassword')
but honestly, do you want to have your password written in your script?
Similarly, I make use of having my username in a file named .yagmail
in my home folder.
Section | Explanation |
---|---|
Install | Find the instructions on how to install yagmail here |
Username and password | No more need to fill in username and password in scripts |
Start a connection | Get started |
Usability | Shows some usage patterns for sending |
Recipients | How to send to multiple people, give an alias or send to self |
Magical contents | Really easy to send text, html, images and attachments |
Feedback | How to send me feedback |
Roadmap (and priorities) | Yup |
Errors | List of common errors for people dealing with sending emails |
For Python 2.x and Python 3.x respectively:
pip install yagmail[all]
pip3 install yagmail[all]
If you get problems installing keyring, try installing without, i.e. pip install yagmail
.
As a side note, yagmail
can now also be used to send emails from the command line.
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.
You know you want it. Set it up by opening a Python interpreter and running:
import yagmail
yagmail.register('mygmailusername', 'mygmailpassword')
In fact, it is just a wrapper for keyring.set_password('yagmail', 'mygmailusername', 'mygmailpassword')
.
When no password is given and the user is not found in the keyring, getpass.getpass()
is used to prompt the user for a password. Upon entering this once, it can be stored in the keyring and never asked again.
Another convenience can be to save a .yagmail file in your home folder, containing just the email username. You can then omit everything, and simply use yagmail.SMTP()
to connect. Of course, this wouldn't work with more accounts, but it might be a nice default. Upon request I'll consider adding more details to this .yagmail file (host, port and other settings).
yag = yagmail.SMTP('mygmailusername')
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.
Defining some variables:
to = '[email protected]'
to2 = 'easterbunny@someone.com
to3 = '[email protected]'
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])
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!')
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:
- If it is a dictionary it will assume the key is the content and the value is an alias (only for images currently!) e.g. {'/path/to/image.png' : 'MyPicture'}
- It will try to see if the content (string) can be read as a file locally, e.g. '/path/to/image.png'
- if impossible, it will check if the string is valid html
e.g.
<h1>This is a big title</h1>
- if not, it must be text. e.g. 'Hi Dorika!'
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.
raw
ensures a string will not receive any "magic" (inlining, html, attaching)inline
will make an image appear in the text.
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!')
:-)
Added possibility of ImageOptional SMTP arguments should go with **kwargs to my SMTPCC/BCC (high)Custom names (high)Allow send to return a preview rather than to actually sendJust use attachments in "contents", being smart guessed (high, complex)Attachments (contents) in a list so they actually define the order (medium)Use lxml to see if it can parse the html (low)Added tests (high)Allow caching of content (low)Extra other types (low)(for example, mp3 also works, let me know if something does not work)Probably a naming issue with content type/default typeChoose inline or not somehow (high)Make lxml module optional magic (high)Provide automatic fallback for complex content(medium)(should work)yagmail
as a command on CLI upon installAddedfeedback
function on SMTP to be able to send me feedback directly :-)Added the option to validate emailaddresses...however, I'm unhappy with the error handling/loggin of wrong emailsLogging count & mail capability (very low)Add documentation to exception classes (low)addraw
and `inline```- ~~Travis CI integration ~~
- ~~ Add documentation to all functions (high, halfway) ~~
- Prepare for official 1.0
- Go over documentation again (medium)
- Allow
.yagmail
file to contain more parameters (medium) - Add option to shrink images (low)
-
Make sure you have a keyring entry (see section No more password and username), or use getpass to register. I discourage to use username / password in scripts.
-
smtplib.SMTPException: SMTP AUTH extension not supported by server
-
SMTPAuthenticationError: Application-specific password required
-
YagAddressError: This means that the address was given in an invalid format. Note that
From
can either be a string, or a dictionary where the key is anemail
, and the value is analias
{'[email protected]', 'Sam'}. In the case of 'to', it can either be a string (email
), a list of emails (email addresses without aliases) or a dictionary where keys are the email addresses and the values indicate the aliases. -
YagInvalidEmailAddress: Note that this will only filter out syntax mistakes in emailaddresses. If a human would think it is probably a valid email, it will most likely pass. However, it could still very well be that the actual emailaddress has simply not be claimed by anyone (so then this function fails to devalidate).
-
Click to enable the email for being used externally https://www.google.com/settings/security/lesssecureapps
-
Make sure you have a working internet connection
-
If you get an
ImportError
try to install withsudo
, see issue #13
If you like yagmail
, feel free (no pun intended) to donate any amount you'd like :-)