List Gmail Labels
The List Gmail Labels block retrieves every label associated with a connected Gmail account and returns them as a structured list.
Retrieve all labels from a connected Gmail account
The List Gmail Labels block retrieves every label associated with a connected Gmail account and returns them as a structured list. It connects to Gmail via a Google OAuth connection ID, which you configure in the block's settings, and stores the resulting label data in a variable of your choosing using the destinationVar field.
The block returns an array of label objects, each containing three fields: an id (such as "INBOX" or "Label_123"), a name (the human-readable display name), and a type that indicates whether the label is a built-in system label or a user-created one. This distinction lets downstream steps handle standard Gmail folders and custom labels differently if needed.
This block fits naturally into workflows that need to programmatically reference Gmail labels before performing label-related operations. For example, you might run it at the start of a workflow to look up the correct label ID, then pass that ID into an Update Gmail Labels step to tag or organize messages based on dynamic conditions.
What you can build
Real-world workflows powered by the List Gmail Labels block.
Dynamic Label Lookup
Fetch all available labels at runtime so a workflow can match a label name to its ID before applying it to an email.
Email Triage Automation
List labels to identify which custom categories exist, then route incoming emails into the appropriate label-based folder automatically.
Label Audit Reporting
Retrieve the full list of system and user labels to generate a report of how a Gmail account is organized.
Conditional Label Application
Use the label list to check whether a specific label exists before attempting to apply it to a message, preventing errors in downstream steps.
Onboarding Workflow Setup
At the start of a new user onboarding flow, enumerate existing Gmail labels to determine which setup steps are still needed.
Multi-Account Label Sync
Pull label lists from multiple connected Gmail accounts to compare structures and synchronize label naming conventions across accounts.
Ready to add List Gmail Labels to your workflow?
Get Started FreeCommon questions about List Gmail Labels
What parameters does this block require?
The block requires a Google OAuth connection ID (connectionId) to authenticate with Gmail. You can also specify a destinationVar to name the variable where the returned label data will be stored in your workflow.
What does the block return?
It returns an array called labels, where each item contains three fields: id (the label's internal identifier, such as "INBOX" or "Label_123"), name (the display name), and type (either "system" for built-in Gmail labels or "user" for custom labels you have created).
Does it return both built-in Gmail folders and custom labels?
Yes. The block returns all labels in the account, including system labels like INBOX, SENT, and TRASH, as well as any user-created custom labels. The type field on each label object indicates which category it belongs to.
What workflows commonly use this block?
This block is typically used at the beginning of email management workflows where a label ID is needed before calling a step like Update Gmail Labels. It is also useful in reporting or auditing workflows that need a complete picture of how a Gmail account is structured.
Can I filter the results to only system or only user labels?
The block itself does not provide a built-in filter parameter. It returns all labels together, but each label object includes a type field with the value "system" or "user", which you can use in subsequent workflow steps to filter or branch based on label type.
Related capabilities
[Google] Create Google Doc
Create a new Google Document and optionally populate it with content.
[Google] Update Google Doc
Update the contents of an existing Google Document.
[Google] Fetch Google Doc
Fetch the contents of an existing Google Document.
[Google] Create Google Sheet
Create a new Google Spreadsheet and populate it with CSV data.
[Google] Update Google Sheet
Update a Google Spreadsheet with new data.
[Google] Fetch Google Sheet
Fetch contents of a Google Spreadsheet range.
Add List Gmail Labels to your workflow
Build powerful AI workflows with drag-and-drop blocks. No coding required.