Nylas Folders API

To simplify your experience, the Nylas Email API uses the same commands to manage both folders and labels, and can refer to specific folders using the provider's `folder_id`. The Email API also exposes provider-specific fields (for example, Google's `background_color` field). Email providers use folders and labels to store and organize messages. Depending on the provider (Google, some IMAP providers, and so on), a message can be contained in more than one folder. ⛔️ The Delete Folder endpoint deletes a folder, including all messages it contains. ## Folders scopes The table below lists the Folders endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes. The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope. | Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` | | :------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :------------------------------------------------------------------------------------- | | **GET** `/folders`**GET** `/folders/` | `/gmail.labels` ☑️`/gmail.modify` | `Mail.Read` ☑️`Mail.ReadWrite``Mail.ReadWrite.Shared``Mail.Read.Shared` | | **POST** `/folders`**PUT** `/folders/`**DELETE** `/folders/` | `/gmail.labels` ☑️`/gmail.modify` | `Mail.ReadWrite` ☑️`Mail.ReadWrite.Shared` | For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/). ## Folders notifications You can subscribe to the following triggers so Nylas notifies you about changes to your users' data: - `folder.created` - `folder.updated` - `folder.deleted` For more information, see the [Folder notification schemas](/docs/reference/notifications/#folder-notifications). ## Folders limitations Keep the following limitations in mind when you're working with folders: - Because providers structure folders in different ways, Nylas doesn't support nested folders. Instead, Nylas flattens sub-folders and displays them in the same list as top-level folders. - For Microsoft, you can use the `parent_id` to reflect the folder hierarchy in your project. - On IMAP, the hierarchy is reflected in the folder name (for example, `Accounting.Taxes` or `INBOX\Accounting\Taxes`). - Because of how IMAP providers handle folders and labels, the folder names that Nylas returns aren't always the same as those listed in the provider's UI (for example, the "Trash" folder might be "Deleted Messages" in a Nylas response). Instead of relying on names, you should [use attributes and IDs to get the data you need](/docs/v3/email/folders/#folder-and-label-behavior). - IMAP servers use provider-specific formats to represent the folder name and hierarchy. When you make a [Create Folder request](/docs/reference/api/folders/post-folder/) for an IMAP account, Nylas creates a folder with the name you pass. If the name includes the IMAP separator that corresponds with the server settings, Nylas creates a sub-folder based on the folder name. - Nylas doesn't support using keywords to reference folders on the provider (for example, `in:inbox` returns a [`400` error](/docs/api/errors/400-response/)). Instead, Nylas recommends you use specific folder `id`s to get the data you need. - It might take up to 10 minutes for folders to be available in Nylas after you authenticate an IMAP grant.