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 nylas CLI for the terminal. I work on the CLI, so the terminal commands below are the ones I reach for when I'm sorting a mailbox by hand.
One API for folders and labels
Nylas treats folders and labels as the same resource, addressed at /v3/grants/{grant_id}/folders, and refers to each one by a folder_id. The difference between the two models surfaces on the message, not the folder API: a message carries a folders array, and on Google that array holds label IDs, so a single Gmail message can appear under several labels like INBOX and CATEGORY_PERSONAL at once. On folder-based providers, that array holds the one folder the message lives in.
