How to Send Emails with Gmail using Python

There are quite a few ways to send email with Python, whether it be through a 3rd party library like with boto and SES, or through an email protocol like SMTP. While the subject of using Python to send emails may seem like it's been done to death, there are just so many different ways to do it and so many issues that can come up. I thought it would be helpful to write up a tutorial on how to send emails with Gmail as the provider using Python.

The SMTP Protocol

This may not come as a surprise, but of course Python already has a library that lets you connect to an SMTP server, like the one Gmail uses. This library is called, predictably, smtplib and comes included with Python.

SMTP (Simple Mail Transfer Protocol) is an application-level protocol (on top of TCP) used to communicate with mail servers from external services, like an email client on your phone. SMTP is a delivery protocol only, so you can't actually retrieve email with it, you can only send email, which is what we'll be focusing on in this article. If you want to retrieve email instead, then you'll want to check out the IMAP (Internet Message Access Protocol) protocol.

I should note that many email services, like Gmail, don't usually use SMTP on their internal mail servers. SMTP is usually just provided as an outward-facing interface to their service via the smtp.gmail.com server. This is mostly meant to be used by email clients on your phone or computer (like Outlook, Thunderbird, etc). Occassionally it can be used for other third party services. For example, let's say you run a Gmail app like Block Sender, in which you need to send email on behalf of users. To do so, using Python and SMTP may be one option to connect to the user's account.

Opening the Connection

As already mentioned, Python conveniently comes with the smtplib, which handles all of the different parts of the protocol, like connecting, authenticating, validation, and of course, sending emails.

Using this library, there are a few different ways you can create a connection to your mail server. In this section, we'll focus on creating a plain, insecure connection (which should rarely, if ever, be used). This connection is unencrypted and defaults to port 25. However, the protocol for mail submission actually uses 587, which is what we'll use.

These connections are really simple to create with smtplib. The unencrypted version can be created with:

import smtplib

try:
    server = smtplib.SMTP('smtp.gmail.com', 587)
    server.ehlo()
except:
    print 'Something went wrong...'

And that's it. There really isn't much more to it than passing the server address, port, and calling .helo(), which identifies you to the SMTP server. Using this server object you can now send email over an insecure connection.

Note: You might not be ready to send emails quite yet. Gmail imposes some restrictions on SMTP connections like this. See the section "Authenticating with Gmail" below for more info.

Using a Secure Connection

When an SMTP connection is secured via TLS/SSL, it is done over port 465 and is typically called SMTPS. Needless to say, you should always use a secured connection.

There are a few different ways you can secure your SMTP connections in the smtplib library. The first way is to first create an insecure connection and then upgrading to TLS. This is done using the .starttls() method.

import smtplib

try:
    server = smtplib.SMTP('smtp.gmail.com', 587)
    server.ehlo()
    server.starttls()
    # ...send emails
except:
    print 'Something went wrong...'

Notice that while this is very similar to the previous insecure connection we created, all that's different is that we're using the .starttls() method to upgrade the connection to secure.

Your other option is to create an SSL connection right from the start. In this case, you'll want to use the .SMTP_SSL() method instead:

import smtplib

try:
    server_ssl = smtplib.SMTP_SSL('smtp.gmail.com', 465)
    server_ssl.ehlo()   # optional
    # ...send emails
except:
    print 'Something went wrong...'

Among other slight differences, we use the SMTPS port (465) right away, although you could just leave the port parameter out of this and smtplib will default to 465 anyway.

Now that we have our connection, let's create an email.

Creating the Email

Emails, at the very core, are just strings of text connected by newline characters. Most emails will at least have the "From", "To", "Subject" and a body fields. Here is a simple example:

From: [email protected]
To: [email protected], [email protected]
Subject: OMG Super Important Message

Hey, what's up?

- You

As you can see, each line contains a new field with its data. No binary protocol, no XML, no JSON, just line-separated strings.

A simple way to parameterize these fields is to use string formatting in Python:

sent_from = '[email protected]'
to = ['[email protected]', '[email protected]']
subject = 'OMG Super Important Message'
body = 'Hey, what's up?\n\n- You'

email_text = """\
From: %s
To: %s
Subject: %s

%s
""" % (sent_from, ", ".join(to), subject, body)

Now all you have to do is pass the email_text string to smtplib, which we'll show in the next section, and you're good to go.

Authenticating with Gmail

There are a few steps you need to take before you can send emails through Gmail with SMTP, and it has to do with authentication. If you're using Gmail as the provider, you'll need to tell Google to allow you to connect via SMTP, which is considered a "less secure" method.

You can't really blame Google for setting it up this way since your application (or some other 3rd party app) will need to have your plaint-text password for this to work, which is definitely not ideal. It's not like the OAuth protocol where a revocable token is issued, so they have to find another way to ensure no unauthorized parties access your data.

For many other email providers you won't need to do any of the extra steps I describe here.

First, you'll want to allow less secure apps to access your account. For detailed instructions on how to do this, you should check out this page:

Allowing less secure apps to access your account

If you have 2-step verification enabled on your account, then you'll need to create an app-specific password for less secure apps like this. In that case, you'll need to follow the instructions here:

Sign in using App Passwords

And finally, if you're still getting an SMTPAuthenticationError with an error code of 534, then you'll need to do yet another step for this to work.

Display Unlock Captcha

I haven't had to do this last step for my own accounts, but I've read that it doesn't actually work right away. Apparently after you enable less secure apps, you may need to wait a few minutes before trying the 'Display Unlock Captcha' link. If you run in to this problem and find a good way around it, please let us know in the comments!

As for the actual Python code, all you need to do is call the login method:

import smtplib

gmail_user = '[email protected]'
gmail_password = 'P@ssword!'

try:
    server = smtplib.SMTP_SSL('smtp.gmail.com', 465)
    server.ehlo()
    server.login(gmail_user, gmail_password)
except:
    print 'Something went wrong...'

Sending the Email

Now that you have your SMTP connection set up and authorized your app with Google, you can finally use Python to send email with Gmail.

Using the email string we constructed above, and the connected/authenticated server object, you need to call the .sendmail() method. Here is the full code, including the methods for closing the connection:

import smtplib

gmail_user = '[email protected]'
gmail_password = 'P@ssword!'

sent_from = gmail_user
to = ['[email protected]', '[email protected]']
subject = 'OMG Super Important Message'
body = 'Hey, what's up?\n\n- You'

email_text = """\
From: %s
To: %s
Subject: %s

%s
""" % (sent_from, ", ".join(to), subject, body)

try:
    server = smtplib.SMTP_SSL('smtp.gmail.com', 465)
    server.ehlo()
    server.login(gmail_user, gmail_password)
    server.sendmail(sent_from, to, email_text)
    server.close()

    print 'Email sent!'
except:
    print 'Something went wrong...'

Conclusion

Aside from the Gmail-specific authorization steps (involving less secure apps, etc), this code should work for just about any other email provider that supports SMTP access, assuming you have the correct server address and port. If you find that other providers put special restrictions on SMTP access like Google does, let us know! We'd like to include as much info as possible here.

Do you programmatically send emails with SMTP? What kind of applications do you use it for? Let us know in the comments!

Resources

• https://docs.python.org/3.5/library/smtplib.html
• http://stackoverflow.com/a/27515833/2684304

Edit: Thanks to cropr (in the comments) for pointing out that Gmail imposes a number of restrictions on people sending email with SMTP. Free accounts are limited to 500 emails per day and are rate-limited to about 20 emails per second.

If you think you'll exceed these limits, then you may want to either set up your own SMTP server or use services like AWS SES or Sendgrid.