Gmail doesn’t use folders. It uses labels, and a single message can carry several at once. The Gmail API exposes them through the users.labels resource, with rules that surprise developers: reserved system labels you can’t create or delete, a 5,000-label cap per mailbox, and color values restricted to a fixed palette of 102 hex codes. The Nylas Folders API exposes the same labels as folders, with the same request shape it uses for Outlook folders and IMAP mailboxes, so one integration manages labels across providers.
How does the Gmail API represent labels?
Section titled “How does the Gmail API represent labels?”A Gmail label is a tag attached to a message rather than a container that holds it. The Gmail API represents each label as a users.labels resource with an id, name, type (system or user), and optional color properties. Google’s labels guide documents 13 common system labels, and Google’s Gmail Help caps user-created labels at 5,000 per mailbox.
According to the users.labels reference, system labels like INBOX, SENT, DRAFT, SPAM, and TRASH can’t be created, deleted, or renamed; the API rejects the attempt with a 400 error. System labels use uppercase IDs, while user labels get generated IDs like Label_42. Label names accept forward slashes for nesting, so Project/Alpha renders as a nested label in the Gmail UI.
What are Gmail’s reserved system labels?
Section titled “What are Gmail’s reserved system labels?”Gmail’s reserved system labels are the labels Gmail creates in every account, such as INBOX, SENT, and TRASH. Google’s labels guide says “System label names are reserved; no USER label can be created with the same name as any SYSTEM label.” The guide lists 13 common system label IDs.
| System label ID | Can be manually applied | What it marks |
|---|---|---|
INBOX | Yes | Messages in the inbox |
SPAM | Yes | Messages in Spam |
TRASH | Yes | Messages in Trash |
UNREAD | Yes | Unread messages |
STARRED | Yes | Starred messages |
IMPORTANT | Yes | Messages marked important |
SENT | No | Messages sent with messages.send or drafts.send, or through the web interface |
DRAFT | No | Drafts created with the Gmail API or the Gmail interface |
CATEGORY_PERSONAL | Yes | The Personal tab |
CATEGORY_SOCIAL | Yes | The Social tab |
CATEGORY_PROMOTIONS | Yes | The Promotions tab |
CATEGORY_UPDATES | Yes | The Updates tab |
CATEGORY_FORUMS | Yes | The Forums tab |
The users.labels reference adds that system labels “are internally created and cannot be added, modified, or deleted,” and that applying or removing them on messages “is not guaranteed” outside cases like INBOX and UNREAD. A label’s type field returns system for these and user for labels you create.
How do you create and apply labels with the Gmail API?
Section titled “How do you create and apply labels with the Gmail API?”Creating a label is a POST to users.labels.create with a name and optional visibility and color settings; applying one is a POST to users.messages.modify with an addLabelIds array. Creation needs the gmail.labels OAuth scope, while modifying messages needs the broader gmail.modify scope.
The example below uses google-api-python-client to create a colored label and apply it to a search result in bulk. The batchModify endpoint accepts up to 1,000 message IDs per request and is idempotent: re-applying an existing label is a no-op, not an error. Before any of this runs, the Google Cloud setup (project, consent screen, credentials) takes 15-20 minutes.
from google.oauth2.credentials import Credentialsfrom googleapiclient.discovery import build
creds = Credentials.from_authorized_user_file( "token.json", scopes=["https://www.googleapis.com/auth/gmail.modify"],)service = build("gmail", "v1", credentials=creds)
# Create a nested label with preset colorsnew_label = service.users().labels().create( userId="me", body={ "name": "Receipts/2026", "labelListVisibility": "labelShow", "messageListVisibility": "show", "color": {"textColor": "#ffffff", "backgroundColor": "#4a86e8"}, },).execute()
# Find matching messages and label them in one batch (up to 1,000 IDs)results = service.users().messages().list( userId="me",).execute()ids = [msg["id"] for msg in results.get("messages", [])]
if ids: service.users().messages().batchModify( userId="me", body={"ids": ids, "addLabelIds": [new_label["id"]]}, ).execute()Which colors can a Gmail label use?
Section titled “Which colors can a Gmail label use?”Gmail label colors must come from a fixed palette of 102 hex values. The users.labels color fields say “Only the following predefined set of color values are allowed” for both textColor and backgroundColor, and setting a color requires both fields. Values such as #4986e7, #4a86e8, #000000, and #ffffff are on the list.
The palette is the same 102 values for text and background, so any allowed value works in either field. A hex value outside the list, such as #4986e8, isn’t allowed even though the field looks like a free-form #RRGGBB string. Copy values from Google’s list rather than picking colors in a design tool, and validate them in your own code before calling users.labels.create or users.labels.update.
What’s the difference between system and user labels?
Section titled “What’s the difference between system and user labels?”System labels are built into every Gmail account and serve fixed functions; user labels are the ones you create and manage. The API enforces the split: attempts to delete or rename a system label fail with 400, and creating labels past the 5,000-per-mailbox cap fails too.
| Behavior | System labels | User labels |
|---|---|---|
| ID format | Uppercase (INBOX, SENT) | Label_N (Label_42) |
| Create / delete | Not allowed (400 error) | Allowed, up to 5,000 |
| Rename | Not allowed | Allowed with an update call |
| Custom colors | No | Preset palette only |
| Nesting | Fixed hierarchy | Slash (/) in the name |
The CATEGORY_* labels (PERSONAL, SOCIAL, UPDATES, FORUMS, PROMOTIONS) deserve special care. They correspond to Gmail’s inbox tabs, and a message can sit in a category while carrying user labels. Removing CATEGORY_PROMOTIONS from a message moves it to the Primary tab, a side effect that surprises developers expecting a plain label removal.
How do you manage Gmail labels with the Nylas API?
Section titled “How do you manage Gmail labels with the Nylas API?”The Nylas Folders API maps Gmail labels onto its folder resource: GET /v3/grants/{grant_id}/folders returns every system and user label, and POST /v3/grants/{grant_id}/folders creates one. Gmail-specific fields survive the mapping. Each folder carries system_folder (true for Google-created labels), and user labels accept text_color and background_color from Google’s 102-value palette.
The samples below list every label on a connected Gmail account. System labels come back with their Gmail IDs as both id and name, such as INBOX and CATEGORY_SOCIAL, and standard ones carry an attributes value like \Inbox or \Junk. The same request returns Outlook folders and IMAP mailboxes in the same shape.
curl --compressed --request GET \ --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <NYLAS_API_KEY>' \ --header 'Content-Type: application/json'{ "request_id": "1", "data": [ { "id": "CATEGORY_FORUMS", "grant_id": "2", "name": "CATEGORY_FORUMS", "system_folder": true }, { "id": "CATEGORY_PERSONAL", "grant_id": "2", "name": "CATEGORY_PERSONAL", "system_folder": true }, { "id": "CATEGORY_PROMOTIONS", "grant_id": "2", "name": "CATEGORY_PROMOTIONS", "system_folder": true }, { "id": "CATEGORY_SOCIAL", "grant_id": "2", "name": "CATEGORY_SOCIAL", "system_folder": true }, { "id": "CATEGORY_UPDATES", "grant_id": "2", "name": "CATEGORY_UPDATES", "system_folder": true }, { "id": "CHAT", "grant_id": "2", "name": "CHAT", "system_folder": true }, { "id": "DRAFT", "grant_id": "2", "name": "DRAFT", "attributes": ["\\Drafts"], "system_folder": true }, { "id": "IMPORTANT", "grant_id": "2", "name": "IMPORTANT", "attributes": ["\\Important"], "system_folder": true }, { "id": "INBOX", "grant_id": "2", "name": "INBOX", "attributes": ["\\Inbox"], "system_folder": true }, { "id": "SENT", "grant_id": "2", "name": "SENT", "attributes": ["\\Sent"], "system_folder": true }, { "id": "SPAM", "grant_id": "2", "name": "SPAM", "attributes": ["\\Junk"], "system_folder": true }, { "id": "STARRED", "grant_id": "2", "name": "STARRED", "system_folder": true }, { "id": "TRASH", "grant_id": "2", "name": "TRASH", "attributes": ["\\Trash"], "system_folder": true }, { "id": "UNREAD", "grant_id": "2", "name": "UNREAD", "system_folder": true } ]}import Nylas from "nylas";
const nylas = new Nylas({ apiKey: "<NYLAS_API_KEY>", apiUri: "<NYLAS_API_URI>",});
async function fetchFolders() { try { const folders = await nylas.folders.list({ identifier: "<NYLAS_GRANT_ID>", });
console.log("folders:", folders); } catch (error) { console.error("Error fetching folders:", error); }}
fetchFolders();from nylas import Client
nylas = Client( "<NYLAS_API_KEY>", "<NYLAS_API_URI>")
grant_id = "<NYLAS_GRANT_ID>"folder_id = "<FOLDER_ID>"
folder = nylas.folders.list( grant_id)
print(folder)The same grant handles other label tasks through the Email API:
- Apply labels. A
PUTto/v3/grants/{grant_id}/messages/{message_id}with afoldersarray sets the message’s full label list in 1 request. Google allows several labels per message; Microsoft allows one folder. - Track label changes. The
folder.created,folder.updated, andfolder.deletedwebhooks report label changes without polling. - Scopes. Listing and creating labels needs only the non-restricted
gmail.labelsscope. Applying labels to messages needsgmail.modify, a restricted scope covered in the Gmail restricted scopes guide.
The folders and labels recipe covers the move-vs-tag distinction across providers, and Using the Folders API documents every field. If your app only works with Gmail and already uses google-api-python-client, calling users.labels directly is a reasonable choice.
Things to know about Gmail labels
Section titled “Things to know about Gmail labels”The 5,000-label cap is real and enforced; large CRM-style integrations that create one label per customer hit it faster than expected, so prefer a few stable labels plus metadata on your side. Label IDs are stable for the life of the account, but display names aren’t unique: deleting and recreating a label with the same name produces a new Label_N ID, which breaks any code that cached the old one.
Filtering messages by label works at list time, too. Pass a label’s ID as the in query parameter on the messages endpoint, or use Gmail search operators like label:receipts-2026 through search_query_native; the Google messages recipe shows both patterns with code.
What’s next
Section titled “What’s next”- Quickstart: Email API connects a Gmail account and makes a first API call in under 5 minutes.
- Organize email with folders and labels covers the cross-provider folder model and moving messages.
- How to list Google email messages filters messages by label and Gmail search operators.
- Using the Folders API is the full reference, including common attributes.
- Gmail API quotas prices native
labelsandmessagescalls in quota units.