A Pythonic interface to Google's GMail, with all the tools you'll need. Search, read and send multipart emails, archive, mark as read/unread, delete emails, and manage labels.
This library is still under development, so please forgive some of the rough edges
Heavily inspired by Kriss "nu7hatch" Kowalik's GMail for Ruby library
For now, installation is manual (pip support not yet implemented). Supports python 2 and pypy.
git clone git://github.com/girishramnani/gmail.git
- Search emails
- Read emails
- Emails: label, archive, delete, mark as read/unread/spam, star
- Manage labels
To start, import the gmail library.
import gmail
To easily get up and running:
import gmail
g = gmail.login(username, password)
Which will automatically log you into a GMail account. This is actually a shortcut for creating a new Gmail object:
from gmail import Gmail
g = Gmail()
g.login(username, password)
# play with your gmail...
g.logout()
You can also check if you are logged in at any time:
g = gmail.login(username, password)
g.logged_in # Should be True, AuthenticationError if login fails
from gmail import Gmail, Message
g = Gmail()
g.login(username, password)
message = Message.create("Hello",
"test@test.com",
text="Hello world")
g.send(message)
If you have already received an OAuth2 access token from Google for a given user, you can easily log the user in. (Because OAuth 1.0 usage was deprecated in April 2012, this library does not currently support its usage)
gmail = gmail.authenticate(username, access_token)
Get all messages in your inbox:
g.inbox.get_mail()
Get messages that fit some criteria:
g.inbox.get_mail(after=datetime.date(2013, 6, 18), before=datetime.date(2013, 8, 3))
g.inbox.get_mail(on=datetime.date(2009, 1, 1)
g.inbox.get_mail(sender="myfriend@gmail.com") # "from" is reserved, use "fr" or "sender"
g.inbox.get_mail(to="directlytome@gmail.com")
Combine flags and options:
g.inbox.get_mail(unread=True, sender="myboss@gmail.com")
Browsing labeled emails is similar to working with your inbox.
g.get_mailbox('Urgent').get_mail()
Every message in a conversation/thread will come as a separate message.
g.inbox.get_mail(unread=True, before=datetime.date(2013, 8, 3) sender="myboss@gmail.com")
Important: calls to get_mail() will return a list of empty email messages (with unique IDs). To work with labels, headers, subjects, and bodies, call fetch() on an individual message. You can call get_mail with prefetch=True, which will fetch the bodies automatically.
unread = g.inbox.get_mail(unread=True)
print unread[0].body
# None
unread[0].fetch()
print unread[0].body
# Dear ...,
Mark news past a certain date as read and archive it:
emails = g.inbox.get_mail(before=datetime.date(2013, 4, 18), sender="news@nbcnews.com")
for email in emails:
email.read() # see other Message methods below
email.archive()
Delete all emails from a certain person:
emails = g.inbox.get_mail(sender="junkmail@gmail.com")
for email in emails:
email.delete()
You can use also get_label method instead of get_mailbox:
g.get_label("Faxes").get_mail()
Add a label to a message:
email.add_label("Faxes")
Download message attachments:
for attachment in email.attachments:
print 'Saving attachment: ' + attachment.name
print 'Size: ' + str(attachment.size) + ' KB'
attachment.save('attachments/' + attachment.name)
There are also few shortcuts to mark messages quickly:
email.read()
email.mark_as_read() # alias of email.read()
email.unread()
email.mark_as_unread() # alias of email.unread()
email.spam()
email.star()
email.unstar()
- Mailboxes are now accessed via properties (e.g.
inbox = g.inboxinstead ofg.inbox()) rather than methods. - For clarity, the
Mailbox.mail()method is now calledMailbox.get_mail()to emphasize that it's a method, not a property. - Similarly,
Mailbox.label()is nowMailbox.get_label(). - There's no need to call
fetch()on aMessage, since any attempt to access an attribute of aMessagewill automatically triggerfetch(), lazily loading the data for thatMessagecourtesy ofMessage.__getattr__. uidis now supported as a keyword argument forMailbox.get_mail().
- Write tests
- Better label support
- Moving between labels/mailboxes
- Intuitive thread fetching & manipulation
- solve issues on the python 3 part ( as it was generated using
2to3script ) Sending via Google's SMTP servers (for now, check out https://github.com/paulchakravarti/gmail-sender)
- Copyright (c) 2017 Girish Ramnani
See LICENSE for details.