You can use labels to tag, organize, and categorize messages and threads in Gmail. A label has a many-to-many relationship with messages and threads: a single message or thread may have multiple labels applied to it and a single label may be applied to multiple messages or threads.
For information on how to create, get, list, update, or delete labels, see the Labels reference.
Contents
Types of labels
Labels come in two varieties: reserved SYSTEM labels and custom USER labels.
System labels typically correspond to pre-defined elements in the Gmail web
interface such as the inbox. Systems label names are reserved; no USER label can
be created with the same name as any SYSTEM label. The following table lists
several of the most common Gmail system labels:
| Name | Can be manually applied | Notes |
|---|---|---|
INBOX |
yes | |
SPAM |
yes | |
TRASH |
yes | |
UNREAD |
yes | |
STARRED |
yes | |
IMPORTANT |
yes | |
SENT |
no | Applied automatically to messages that are sent with
drafts.send or
messages.send, inserted
with messages.insert
and the user's email in the From header, or sent by the user through
the web interface. |
DRAFT |
no | Automatically applied to all
draft messages created with the
API or Gmail interface. |
CATEGORY_PERSONAL |
yes | Corresponds to messages that are displayed in the Personal tab of the Gmail interface. |
CATEGORY_SOCIAL |
yes | Corresponds to messages that are displayed in the Social tab of the Gmail interface. |
CATEGORY_PROMOTIONS |
yes | Corresponds to messages that are displayed in the Promotions tab of the Gmail interface. |
CATEGORY_UPDATES |
yes | Corresponds to messages that are displayed in the Updates tab of the Gmail interface. |
CATEGORY_FORUMS |
yes | Corresponds to messages that are displayed in the Forums tab of the Gmail interface. |
Applying labels to messages and threads
Messages and threads can have multiple labels associated with them; however,
draft messages cannot have labels applied to them. Modifying the labels applied
to a thread applies or removes the specified labels from all messages in the
thread. You can modify which labels are associated with a message or thread by
calling messages.modify or
threads.modify, respectively.