Introduction to the Gmail API

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

Using theAPI, you can performmany 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 retrievespecific messages and threads.

The APIis REST-based andcan be used to access Gmail mailboxes and send mail. It specificallyprovides control over:

• Authentication
• Messages and Drafts
• Labels
• Threads
• AccountHistory

Google suggests the following use casesfor theAPI:

• Read-only mail extraction, indexing, and backup
• Label management (adding andremoving labels)
• Automated or programmatic message sending

When I built my own email management application,Simplify Email (read more about it at Tuts+ inBuilding Advanced Email Features With IMAP and PHP), the only Google emailAPI 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 forsecure, revokableaccess to Gmail accounts that doesn't require users toshare 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 withinthreads.

The API's account history provides a log of message activity for applications to reference, reducing the complexity of monitoring changes toIMAP accounts in realtime.

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 ofEnhancing Gmail

I've been interested in extending Gmail ever sinceI wroteTwelve Gmail Ideas to Revolutionize Email (Again)in 2010. Mostof the ideasI wished for, such as white listing and do not disturb, remained out of reach without Google's efforts oran API.For as important an application asGmail 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)isleading developmentofJMAP, 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 usesOAuth 2.0to 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
• Labels
• Drafts
• History
• Threads

Messages and labels are the basic units of a mailbox. Drafts, history, and threads all contain one or more messages with additional metadata.

Draftsare unsent messages. They can't be modified—only created and deleted. They can also be sent.

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

Threadsare collections of messages that represent a conversation. Labels can be added to threads, and messages can be added to threads.

Historyis 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 findmessages and threads that correspond toadvanced 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 towalk you through using the Gmail APIwith your PHP‑based application.

Please feel free to post your questions and comments below. You can also reach me on Twitter@reifmanoremail medirectly. Followmy Tuts+ instructor pageto see future articles on the Gmail API.

Related Links

• Google Gmail API Overview
• Building Advanced Email Features With IMAP and PHP (Tuts+)
• JMAP: A Better Way to Email