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).
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
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@example.com To: firstname.lastname@example.org, email@example.com 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:
from = 'firstname.lastname@example.org' to = ['email@example.com', 'firstname.lastname@example.org'] subject = 'OMG Super Important Message' body = 'Hey, what's up?\n\n- You' email_text = """\ From: %s To: %s Subject: %s %s """ % (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:
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:
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.
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
import smtplib gmail_user = 'email@example.com' 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 = 'firstname.lastname@example.org' gmail_password = 'P@ssword!' from = gmail_user to = ['email@example.com', 'firstname.lastname@example.org'] subject = 'OMG Super Important Message' body = 'Hey, what's up?\n\n- You' email_text = """\ From: %s To: %s Subject: %s %s """ % (from, ", ".join(to), subject, body) try: server = smtplib.SMTP_SSL('smtp.gmail.com', 465) server.ehlo() server.login(gmail_user, gmail_password) server.sendmail(from, to, email_text) server.close() print 'Email sent!' except: print 'Something went wrong...'
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!
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.