Organize email with folders and labels in Nylas

Gmail organizes mail with labels, where one message can carry several at once. Microsoft, Yahoo, iCloud, and IMAP use folders, where a message lives in exactly one. Build email organization against each provider and you're writing to Gmail's label API, Microsoft Graph's folder API, and an IMAP folder model, each with different rules about how many places a message can be at once. The Nylas Email API gives you one set of calls that manages both, so the same code creates a Gmail label and an Outlook folder.

This post is a working tour of folders and labels from two angles: the HTTP API for your backend, and the returns every folder on the account, each with an id, name, an attributes array, and provider-specific fields like a system_folder flag on Google and a parent_id on Microsoft and EWS. On Microsoft accounts, a few query parameters narrow the result: parent_id lists the children of one folder (this one also works on EWS), single_level avoids recursing into sub-folders, and include_hidden_folders surfaces folders the provider hides by default.

curl --request GET \

  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/folders" \

  --header "Authorization: Bearer <NYLAS_API_KEY>"

From the terminal, nylas email folders list prints the folders in a table with their unread and total counts, and --json gives you the raw objects. The attributes array is the part worth understanding: it maps a folder to a standard role like \Inbox, \Sent, or \Trash, which matters because provider names vary. An IMAP account might call its trash "Deleted Messages" rather than "Trash", so you match on the attribute or the id, never on the display name.

Fetch a single folder and its counts

When you have a folder ID and want just that one, with a name. On Microsoft and EWS you can pass a parent_id to nest it under another folder, and on Google you can set background_color and text_color to give the label a color in the Gmail UI. The response returns the new folder with its id, which you use to move messages into it later.

curl --request POST \

  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/folders" \

  --header "Authorization: Bearer <NYLAS_API_KEY>" \

  --header "Content-Type: application/json" \

  --data '{ "name": "Invoices" }'

The CLI takes the name as a positional argument: nylas email folders create Invoices. It accepts --parent <folder-id> to nest the folder, and --bg-color and --text-color with hex values to color a Google label. Creating a colored label from the terminal is a single line:

nylas email folders create "Invoices" --bg-color "#16a765" --text-color "#ffffff"

Nest folders into a hierarchy

Folders aren't always flat. Microsoft and EWS support nesting, and you build a tree with parent_id: pass it on create to place a new folder under an existing one, or on the PUT to move a folder under a different parent. Nylas flattens the provider's nested structure and adds parent_id to each child, so you can re-create the hierarchy in your own interface from the list response.

nylas email folders create "2024" --parent <invoices-folder-id>

When you list folders on Microsoft, the single_level query parameter returns only the direct children of a parent_id instead of recursing the whole subtree, which keeps the folder list manageable on a large mailbox. Gmail's label model is flatter than Microsoft's folder tree, so reserve deep nesting for folder-based providers and keep labels shallow with naming conventions if you need to group them.

Rename and recolor a folder

To change a folder, request with a new folders value reassigns the message, and on single-folder providers this overwrites the folder the message was in. The CLI wraps this in nylas email move, which takes the message ID and a destination folder:

nylas email move <message-id> --folder <folder-id>

On Google the same folders array is the message's label set, so reassigning it changes which labels the message carries. The nylas email move <message-id> --archive flag archives a message, and what that means depends on the provider: on Gmail and other label-based accounts it removes every label including INBOX, while on folder-based accounts like IMAP and Microsoft the provider moves the message to its Archive folder instead. Either way it's the clean way to get a message out of the inbox without choosing a destination.

Find the inbox, sent, and trash by attribute

The folders you reference most are the system ones, and you find them by attributes, not by name. An IMAP account might label its trash "Deleted Messages", and a localized mailbox might translate "Sent", so matching on the display string is fragile. Instead, list the folders and pick the one whose attributes array contains the standard role you want, such as \Inbox, \Sent, \Drafts, or \Trash.

nylas email folders list --json

Read the attributes of each folder in that output and map the standard roles to their provider-specific id values once, at startup. From then on, your code files a message to trash by its trash folder's id, which is stable, rather than guessing at a name that shifts between providers and languages. This is the same reason the move and delete examples above take a <folder-id> rather than a folder name.

List the messages in a folder

Once mail is filed, you read a folder's contents by filtering messages on it. Pass a folder's id to the in query parameter on , or nylas email folders delete <folder-id> from the terminal. There's a serious caveat that's easy to miss: deleting a folder also deletes every message inside it. The messages don't move to trash, they go with the folder.

curl --request DELETE \

  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/folders/<FOLDER_ID>" \

  --header "Authorization: Bearer <NYLAS_API_KEY>"

Because of that, the safe pattern is to move any messages you want to keep out of the folder before you delete it. List the folder's messages, move the ones that matter elsewhere with nylas email move, and only then delete the empty folder. Treat a folder delete as a destructive operation, not a tidy-up, and you won't lose mail you meant to file away.

Provider behaviors that surface through the API

A few provider differences carry through the unified API, and knowing them up front saves a confusing afternoon. None of them break the one-API model; they just shape how you read results.

The biggest is the Gmail labels model. A single Gmail message can carry multiple labels, so its folders array holds several IDs like INBOX, UNREAD, and CATEGORY_PERSONAL. On folder-based providers a message has exactly one folder, so the array holds one ID. Write your code to handle an array either way, rather than assuming a single value, and it works across all six providers.

There's also a filtering limitation worth internalizing. You can't filter folders by keyword or attribute: a query like in:inbox returns a 400 error. To list messages in a specific folder, pass the folder's id to the in query parameter on the messages endpoint, not its name or attribute. And because IMAP folder names returned by the API don't always match the provider's UI, always identify a folder by its id or its attributes rather than the display string.

Things to keep in mind

A short list of habits keeps a folders integration predictable across providers.

• 
  Match folders by id or attributes, never by name. Provider display names vary, and IMAP especially renames system folders.


• 
  Treat the folders array as multi-valued. Gmail messages carry several labels; assuming a single folder breaks on Google.


• 
  Deleting a folder deletes its messages. Move anything you want to keep before the DELETE call.


• 
  folders rename also recolors and re-parents. Despite the name, it takes --bg-color, --text-color, and --parent, matching the PUT API.


• 
  Filter messages by folder id with in. Keyword folder filters like in:inbox return a 400.


• 
  Read counts from the folder object. total_count and unread_count come back on each folder (plus child_count on Microsoft and EWS), so you don't list messages just to show a badge.

Wrapping up

Folders and labels collapse into one resource in the Nylas Email API, so the same create, list, rename, and delete calls manage a Gmail label and an Outlook folder without per-provider branching. Move messages with an Update Message request or nylas email move, color Google labels through the folder object, and lean on attributes and IDs instead of names. The one rule to carry everywhere: a message's folders array can hold more than one entry, because on Google it's a set of labels, not a single folder.

Where to go next:

• 
  — a task-focused walkthrough


• 
  — the endpoint references


• 
  Nylas CLI email folders create — the --parent, --bg-color, and --text-color flags