The Gmail Public Labels API

[This post is by Nadav Aharony, a product manager on the Android team — Tim Bray]

We’re rolling out new developer features for the Gmail Android app: It now includes a public ContentProvider that you can use to retrieve label data. You can use this to access up-to-date unread counts for specific accounts’ inboxes and labels.

To use the API, the Gmail app needs to be at version 2.3.6 or higher on Froyo or Gingerbread; 4.0.5 or higher on Honeycomb and ICS. Before using it, be sure you first check the Gmail app version; we’ve provided a handy GmailContract.canReadLabels(Context) method to help with this. Your app will need the com.google.android.gm.permission.READ_CONTENT_PROVIDER permission.

Finding the Gmail accounts set up on the device

The Labels API needs a valid Gmail account to build a query for per-label information. Assuming the GET_ACCOUNTS permission, the AccountManager can be used to fetch this information:

// Get the account list, and pick the first one
final String ACCOUNT_TYPE_GOOGLE = "com.google";
final String[] FEATURES_MAIL = {
        "service_mail"
};
AccountManager.get(this).getAccountsByTypeAndFeatures(ACCOUNT_TYPE_GOOGLE, FEATURES_MAIL,
        new AccountManagerCallback() {
            @Override
            public void run(AccountManagerFuture future) {
                Account[] accounts = null;
                try {
                    accounts = future.getResult();
                    if (accounts != null && accounts.length > 0) {
                        String selectedAccount = accounts[0].name;
                        queryLabels(selectedAccount);
                    }

                } catch (OperationCanceledException oce) {
                    // TODO: handle exception
                } catch (IOException ioe) {
                    // TODO: handle exception
                } catch (AuthenticatorException ae) {
                    // TODO: handle exception
                }
            }
        }, null /* handler */);

Getting and accessing existing labels

Once you’ve got the email account, you can get a ContentProvider URI to query against. We've provided a simple support class called GmailContract.java for constructing the URI and defining the columns and relevant constants.

You can access any label, predefined or user-defined. The predefined labels include (you have to use symbolic constants rather than these strings, see below):

  • Priority Inbox

  • Starred

  • Chats

  • Sent

  • Drafts

  • All mail

  • Spam

  • Trash

To obtain a Cursor with information for all labels in an account, your app can either query this URI directly or use a CursorLoader. Here’s an example:

Cursor c = 
    getContentResolver().query(GmailContract.Labels.getLabelsUri(selectedAccount), 
        null, null, null, null);

You can query and watch for changes on a single label by storing the URI value in the GmailContract.Labels.URI column from the cursor data.

The NAME value for pre-defined labels can vary by locale, so don’t use GmailContract.Labels.NAME. Instead, identify pre-defined labels like Inbox, Sent or Drafts using the String value in the GmailContract.Labels.CANONICAL_NAME column. Here’s an example:

// loop through the cursor and find the Inbox
if (c != null) {
    final String inboxCanonicalName = GmailContract.Labels.LabelCanonicalName.CANONICAL_NAME_INBOX;
    final int canonicalNameIndex = c.getColumnIndexOrThrow(GmailContract.Labels.CANONICAL_NAME);
    while (c.moveToNext()) {
        if (inboxCanonicalName.equals(c.getString(canonicalNameIndex))) {
            // this row corresponds to the Inbox
        }
    }
}

If you choose to use a CursorLoader, it will keep the label counts up to date as they change over time.

Sample App

You can find a sample app that makes use of the new API here. The app provides a basic readout of label and message-count information.

People care about their incoming mail; we’re looking forward to seeing what you do with access to this information. We’re also open to suggestions as to how to improve and extend this new API.

Labels: