Before using the Labels API, be sure your code first checks if the user's version of the Gmail app supports these new queries. We've provided a handy
GmailContract.canReadLabels(Context)
method to help determine this.To use the Labels API, an app must first find the email address of a valid Gmail account to query for label information. With the GET_ACCOUNTS permission, the AccountManager can return 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 */);
With an email address selected, you can then obtain a ContentProvider URI to query against. We've provided a simple class called GmailContract.java to construct the URI and define the columns returned.
An app can query this URI directly (or better yet: use a CursorLoader) to obtain a Cursor with information for all labels on an account:
Cursor labelsCursor = getContentResolver().query(GmailContract.Labels.getLabelsUri(selectedAccount), null, null, null, null);
With the data in this cursor, you can then persist the URI value in the
GmailContract.Labels.URI
column to query and watch for changes on a single label.The
NAME
value for pre-defined labels can vary by locale, so don't use GmailContract.Labels.NAME
. Instead, you can programmatically identify pre-defined labels like Inbox, Sent or Drafts using the String value in the GmailContract.Labels.CANONICAL_NAME
column:
// loop through the cursor and find the Inbox
if (labelsCursor != null) {
final String inboxCanonicalName = GmailContract.Labels.LabelCanonicalName.CANONICAL_NAME_INBOX;
final int canonicalNameIndex = labelsCursor.getColumnIndexOrThrow(GmailContract.Labels.CANONICAL_NAME);
while (labelsCursor.moveToNext()) {
if (inboxCanonicalName.equals(labelsCursor.getString(canonicalNameIndex))) {
// this row corresponds to the Inbox
}
}
}
To see an example of this API in action, check out the sample app.