Skip to content
Skip to main content

Gmail API labels: system label IDs and colors

Last updated:

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.

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 IDCan be manually appliedWhat it marks
INBOXYesMessages in the inbox
SPAMYesMessages in Spam
TRASHYesMessages in Trash
UNREADYesUnread messages
STARREDYesStarred messages
IMPORTANTYesMessages marked important
SENTNoMessages sent with messages.send or drafts.send, or through the web interface
DRAFTNoDrafts created with the Gmail API or the Gmail interface
CATEGORY_PERSONALYesThe Personal tab
CATEGORY_SOCIALYesThe Social tab
CATEGORY_PROMOTIONSYesThe Promotions tab
CATEGORY_UPDATESYesThe Updates tab
CATEGORY_FORUMSYesThe 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 Credentials
from 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 colors
new_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",
q="from:[email protected] after:2026/01/01",
).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()

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.

BehaviorSystem labelsUser labels
ID formatUppercase (INBOX, SENT)Label_N (Label_42)
Create / deleteNot allowed (400 error)Allowed, up to 5,000
RenameNot allowedAllowed with an update call
Custom colorsNoPreset palette only
NestingFixed hierarchySlash (/) 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.

The same grant handles other label tasks through the Email API:

  • Apply labels. A PUT to /v3/grants/{grant_id}/messages/{message_id} with a folders array 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, and folder.deleted webhooks report label changes without polling.
  • Scopes. Listing and creating labels needs only the non-restricted gmail.labels scope. Applying labels to messages needs gmail.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.

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.