Gmail organizes mail with labels, where one message can carry several. Outlook and IMAP use folders, where a message lives in exactly one. If you integrate each natively, you write two models: a label set on Gmail and a folder tree everywhere else.
The Nylas Folders API collapses both into one resource. The same calls list, create, and apply folders on Outlook and labels on Gmail, and it maps each provider’s special folders to a common set of attributes so your code doesn’t rely on folder names.
How do I list an account’s folders and labels?
Section titled “How do I list an account’s folders and labels?”Send a GET /v3/grants/{grant_id}/folders request. Nylas returns every folder or label with an id you use to reference it later. It maps system folders to 6 common attributes (\Inbox, \Sent, \Drafts, \Junk, \Trash, and \Archive) per RFC 9051, so you can find the inbox without matching on a localized or renamed display name.
The same response shape comes back across all 6 providers, whether the account uses Gmail labels or Outlook folders, so one parser handles both.
How do I create a folder or label?
Section titled “How do I create a folder or label?”Send a POST /v3/grants/{grant_id}/folders request with a name. On Gmail the call creates a label and accepts optional text_color and background_color hex values; on Outlook and IMAP it creates a folder and ignores the color fields, which only apply to Gmail labels. Folder and label creation works across all 6 providers, and creating a Gmail label needs the gmail.labels scope.
The request below creates a folder or label with a name and Gmail label colors.
curl --compressed --request POST \ --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <NYLAS_API_KEY>' \ --data '{ "text_color": "#000000", "name": "new folder", "background_color": "#73AFFF" }'How do I move or label a message?
Section titled “How do I move or label a message?”Assign a message to a folder, or apply a label, by updating the message’s folders field with a PUT /v3/grants/{grant_id}/messages/{message_id} request. Pass the folder or label id from the list call. On Outlook this moves the message into a single folder; on Gmail, where a message can hold many labels, the array sets its full label list.
This 1 field is the difference between the two models: a single-element array behaves like a move, while a multi-element array behaves like Gmail’s multi-label tagging, so include every label you want the message to keep.
Things to know about folders and labels
Section titled “Things to know about folders and labels”The biggest difference to plan for is cardinality: a Gmail message can carry many labels at once, while an Outlook or IMAP message sits in exactly 1 folder. Code that assumes one container per message breaks on Gmail, and code that assumes many breaks on Outlook. Across all 6 providers, lean on the system attributes (\Inbox, \Sent, and the rest) rather than display names, since users rename folders and providers localize them.
Color fields are Gmail-only, and Gmail also keeps system labels like INBOX and SENT that you can’t delete. See Using the Folders API for the full attribute list and provider behavior.
What’s next
Section titled “What’s next”- Using the Folders API for the full reference and provider behavior
- List Google email messages to filter messages by folder or label
- List Microsoft email messages for folder-based filtering on Outlook
- Get real-time updates with webhooks for folder.created and folder.updated events