Manage labels
You can use labels to tag, organize, and categorize messages and threadsin Gmail. A label has a many-to-many relationship with messages andthreads: you can apply multiple labels to a single message or threadand apply a single label to multiple messages or threads.
For information about how tocreate,get,list,update,ordelete labels, see theLabels reference.
To manage labels, you must use thehttps://www.googleapis.com/auth/gmail.labels scope. For more informationabout scopes, seeGmail API-specific authorization and authentication information.
Types of labels
Labels come in two varieties: reservedSYSTEM labels and customUSER labels.System labels typically correspond to pre-defined elements in the Gmail webinterface such as the inbox. Systems label names are reserved; noUSER label canbe created with the same name as anySYSTEM label. The following table listsseveral 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 withdrafts.send ormessages.send, inserted withmessages.insert and the user's email in theFrom header, or sent by the user through the web interface. |
DRAFT | no | Automatically applied to alldraft messages created with the Gmail 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. |
HTTP 400 - Invalid label name error.Manage labels on messages & threads
Labels only exist on messages. For instance, if you list labels on a thread, youget a list of labels that exist on any of the messages within the thread. Alabel might not exist on every message within a thread. You can applymultiple labels to messages, but you can't applylabels to draft messages.
Add or remove labels to threads
When you add or remove a label to a thread, you add or remove the specifiedlabel on all existing messages in the thread.
If messages are added to a thread after you add a label, the new messagesdon't inherit the existing label associated with the thread. To add the labelto those messages, add the label to the thread again.
To add or remove the labels associated with a thread, usethreads.modify.
Add or remove labels to messages
When you add a label to a message, the label is added to that message andbecomes associated with the thread to which the message belongs. The label isn'tadded to other messages within the thread.
If you remove a label from a message and it was the only message in the threadwith that label, the label is also removed from the thread.
To add or remove the labels applied to a message, usemessages.modify.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-11 UTC.