Introduction to the Gmail API
In June 2014, Google introduced its first API for Gmail. For the first time, users of free Gmail accounts could programmatically manage their Gmail accounts without IMAP.
Using the API, you can perform many of the same operations available through the Gmail user interface, e.g. reading, composing, and sending messages. It also lets you manage labels on threads and messages, and search for and retrieve specific messages and threads.
The API is REST-based and can be used to access Gmail mailboxes and send mail. It specifically provides control over:
- Authentication
- Messages and Drafts
- Labels
- Threads
- Account History
Google suggests the following use cases for the API:
- Read-only mail extraction, indexing, and backup
- Label management (adding and removing labels)
- Automated or programmatic message sending
When I built my own email management application, Simplify Email (read more about it at Tuts+ in Building Advanced Email Features With IMAP and PHP), the only Google email API was restricted to paid subscribers of Google Apps. So, I built everything on IMAP. While this allowed for broad compatibility with other email providers, it created some limitations around performance and security.
The API provides access to Gmail accounts through OAuth. This allows for secure, revokable access to Gmail accounts that doesn't require users to share their email passwords with application providers.
With the Gmail API, you can send and retrieve messages, apply labels, find messages with labels, and manage email within threads.
The API's account history provides a log of message activity for applications to reference, reducing the complexity of monitoring changes to IMAP accounts in real time.
To help developers dive in with the API, Google's providing quickstart guides for Java, .NET, and Python. There are also client libraries available for Java, Javascript, .NET, Objective-C, PHP, and Python; Dart, Go, Node.js and Ruby libraries are offered as early stage/in development.
Overall, the Google Gmail API is a great step forward.
The Potential of Enhancing Gmail
I've been interested in extending Gmail ever since I wrote Twelve Gmail Ideas to Revolutionize Email (Again) in 2010. Most of the ideas I wished for, such as white listing and do not disturb, remained out of reach without Google's efforts or an API. For as important an application as Gmail is, innovation on these kinds of advanced features was quite slow.
We’re drowning in email, and managing our inboxes remains a heavy burden. Mail services and clients have done very little to help us with this. Most of the email we receive is sent by machines, not people, and yet we’re the ones who have to individually process all of it.
Analysis of my own email showed I was receiving email from more than 230 automated senders, far fewer actual people. I was tired of constructing filters in Gmail and filling in a myriad of unsubscribe forms. I wanted to have more control over managing my email and simplifying my life.
Using IMAP, I was able to build a number of the email management features I wanted. The result was Simplify Email:
And now, with the Gmail API, you can build secure, optimally performing solutions like these for Gmail specifically.
Also, in October 2014, Google announced Inbox, but it remains invitation only and I've been waiting for three months.
It's worth noting that FastMail (learn more about them here) is leading development of JMAP, a competitive offering to the proprietary Gmail API, and one which other IMAP providers could theoretically add support for.
If you're interested in learning more about JMAP, post a comment below; I may write about it at a later date.
What Can We Do With the Gmail API?
Let's walk through the basic features of the Gmail API.
Authentication
The Gmail API uses OAuth 2.0 to handle authentication and authorization. There are three authentication scopes which can be used individually or in combination.
- Read only, e.g. read a message from Gmail
- Modify, e.g. change labels applied to a thread or message
- Compose, e.g. send messages on behalf of a user
This gives users a variety of controls of how apps interact with their account.
API Components
The Gmail API provides five primary resource types:
Messages and labels are the basic units of a mailbox. Drafts, history, and threads all contain one or more messages with additional metadata.
Drafts are unsent messages. They can't be modified—only created and deleted. They can also be sent.
Labels are what we use as folders in Gmail. They help with categorizing and organizing messages and threads. There are both system labels such as INBOX, TRASH and SPAM and user generated labels such as TRAVEL.
Threads are collections of messages that represent a conversation. Labels can be added to threads, and messages can be added to threads.
History is a collection of recently modified messages in chronological order. History can be used to synchronize an application or to retrieve actions taken by the user on his or her account.
Common Scenarios
Sending Messages
You can automate sending messages from the user's account by uploading simple and multi-part messages and sending them.
Fetching Received Messages
Given the ID of an email from a search or history request, you can download its contents using get message.
Searching for Messages
You can find messages and threads that correspond to advanced Gmail filter queries.
Monitoring Changes to the Account
You can retrieve the history of account actions over the past 30 days with list history. You can use this to partially synchronize a mailbox account to your application and even to learn about the user's preferences for filtering messages of a certain kind.
Label Management
You can add and remove Labels applied to messages and threads.
Full Synchronization
You can back up an entire account from beginning to end. The API allows you to page through messages in your account with the message list method.
What's Next?
In the next tutorial, I'll begin to walk you through using the Gmail API with your PHP‑based application.
Please feel free to post your questions and comments below. You can also reach me on Twitter @reifman or email me directly. Follow my Tuts+ instructor page to see future articles on the Gmail API.
Related Links
