Welcome to Gmail Client’s documentation!¶
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.
Install using pip
pip install gmail_client
- Search emails
- Read emails
- Emails: label, archive, delete, mark as read/unread/spam, star
- Manage labels
To start, import the gmail_client library.
To easily get up and running:
import gmail_client g = gmail_client.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_client 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_client.login(username, password) g.logged_in # should be True, AuthenticationError if login fails
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_client.authenticate(username, access_token)
Get all messages in your inbox:
Get messages that fit some criteria:
g.inbox().mail(after=datetime.date(2013, 6, 18), before=datetime.date(2013, 8, 3)) g.inbox().mail(on=datetime.date(2009, 1, 1) g.inbox().mail(sender="firstname.lastname@example.org") # "from" is reserved, use "fr" or "sender" g.inbox().mail(to="email@example.com")
Combine flags and options:
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, before=datetime.date(2013, 8, 3) sender="firstname.lastname@example.org")
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.body # None unread.fetch() print unread.body
Also calling Message.fetch twice is lazy in order to save requests. You can force fetch:
Mark news past a certain date as read and archive it:
emails = g.inbox().mail(before=datetime.date(2013, 4, 18), sender="email@example.com") for email in emails: email.read() email.archive()
Delete all emails from a certain person:
emails = g.inbox().mail(sender="firstname.lastname@example.org") for email in emails: email.delete()
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: ' + attachment.name print 'Size: ' + str(attachment.size) + ' KB' attachment.save('attachments/' + attachment.name)
A Mailbox object.
Attachment(name, content_type, content)¶
Attachments are files sent in the email.
The base exception in the library. Also raised when there was an ambiguous exception that occurred while handling a request.
A Connection error occurred.
Gmail Authentication failed.