Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

A Pythonic interface for Google Mail.

Project Description
# GMail for Python

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](

## Author

* [Charlie Guo](

## Installation

For now, installation is manual (`pip` support not yet implemented) and the only requirement is to use Python 2 (2.7+ to be precise):

git clone git://

## Features

* Search emails
* Read emails
* Emails: label, archive, delete, mark as read/unread/spam, star
* Manage labels

## Basic usage

To start, import the `gmail` library.

import gmail

### Authenticating gmail sessions

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...

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

### OAuth authentication

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)

### Filtering emails

Get all messages in your inbox:


Get messages that fit some criteria:

g.inbox().mail(, 6, 18),, 8, 3))
g.inbox().mail(, 1, 1)
g.inbox().mail(sender="") # "from" is reserved, use "fr" or "sender"

Combine flags and options:

g.inbox().mail(unread=True, sender="")

Browsing labeled emails is similar to working with your inbox.


Every message in a conversation/thread will come as a separate message.

g.inbox().mail(unread=True,, 8, 3) sender="")

### Working with emails

__Important: calls to `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 mail with `prefetch=True`, which will fetch the bodies automatically.__

unread = g.inbox().mail(unread=True)
print unread[0].body
# None

print unread[0].body
# Dear ...,

Mark news past a certain date as read and archive it:

emails = g.inbox().mail(, 4, 18), sender="")
for email in emails: # can also unread(), delete(), spam(), or star()

Delete all emails from a certain person:

emails = g.inbox().mail(sender="")
for email in emails:

You can use also `label` method instead of `mailbox`:


Add a label to a message:


Download message attachments:

for attachment in email.attachments:
print 'Saving attachment: ' +
print 'Size: ' + str(attachment.size) + ' KB''attachments/' +

There is also few shortcuts to mark messages quickly:

### Roadmap
* Write tests
* Better label support
* Moving between labels/mailboxes
* Intuitive thread fetching & manipulation
* Sending mail via Google's SMTP servers (for now, check out

## Copyright

* Copyright (c) 2013 Charlie Guo

See LICENSE for details.
Release History

Release History

This version
History Node


Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting