Migrating from Tags to Folders and Labels

We’ve put this guide together to help you transition from using the deprecated Tags API to the new Folders and Labels API

Why make this change?

The previous Tags API abstracted away the differences between folders and labels by presenting a unified entity (the “tag”). While a good idea in theory, we found this design to cause issues when implementing more advanced applications. We spent a lot of time talking with developers and getting feedback. (Thanks!)

What’s new?

The new API preserves the semantics and the differences between traditional folders and Gmail labels. In the new system, you can perform the same operations with folders and labels, but depending on the provider, the operation may translate differently. For example, applying a label to a message adds the label to the message (Gmail), but applying a folder moves the message into the folder (generic IMAP, Exchange).

How do I determine whether to use the /folders endpoints or the /labels endpoints for an account?

The account object contains an organization_unit attribute, set to “folder” or “label”, which will tell you whether to use the /folders endpoints or the /labels endpoints for that account. You can check this via the Account. Note this value is provider-dependent; a generic IMAP or Exchange message will only have the “folder” attribute and a Gmail message will only have the “labels” attribute.

Previously, I used tags to get the folders or labels of a thread. How do I do that now?

Folders and labels are now exposed on both the thread and message objects. Depending on the organization_unit parameter, the message object has either a folder or labels attribute. Similarly, a thread has a folders or labels attribute which contains the set of all folders or labels for its messages.

Previously, I used tags to filter threads. How do I do that now?

We’ve introduced the new in filter query parameter which may be used to filter messages and threads that are in either a folder (generic IMAP, Exchange) or have that label (Gmail). The in parameter is provider-agnostic and works for both folders and labels. Note we currently support only a single value for the in parameter.

How do I filter by ‘unread’ and ‘starred’ that do not map to folders or labels?

Unread and starred properties are now boolean attributes on the message and thread object. For example, an unread, starred thread would return:

The unread and starred values can be passed as query parameters to filter messages and threads. For example, to request all the starred threads in a user’s Inbox, you would make a request of the form:

:::xml
GET https://api.nylas.com/threads?in=inbox&starred=True

Are folder and label objects exposed in the Delta API as well?

We have recently exposed the folder and label objects in the Delta API. The tags objects will be removed when Tags API is fully disabled (see below).

I’m using the Ruby or Python SDK. Have those been updated?

Yup, please make sure you’re running the latest version.

How long will the tags API continue functioning?

Before announcing this change, we’ve worked with existing production customers to begin migrating their applications and found the switch to be surprisingly quick and painless. Currently custom tag creation has been disabled. The full tags API will be officially disabled on September 30, 2015.