label/getMany

List all Gmail labels in the authenticated account, including both system labels and user-created labels.

Label ID Lookup: This is the primary operation for resolving user label IDs before using them in message/addLabel, message/getMany, thread/addLabel, and thread/removeLabel. User label IDs are account-specific — always look them up dynamically.

When to Use

Label ID resolution at workflow start: Run label/getMany once at the start of a workflow to build a name-to-ID lookup map for all subsequent label operations.
Label inventory for reporting: Retrieve all labels to generate a Gmail organization report showing all categories and their message counts.
Upsert label check: Before creating a new label, call label/getMany to check if a label with the same name already exists.
Label cleanup audit: List all user-created labels to identify and delete stale or unused labels in a cleanup workflow.
Multi-account synchronization: Compare label sets across multiple Gmail accounts to ensure consistent label taxonomy for cross-account routing workflows.

Configuration

Connection

Field	Type	Description
`credentialId`	Guid required	OAuth2 credential ID from BizFirst Credentials Manager. Requires `gmail.readonly` scope.

Operation Fields

Field	Type	Default	Description
`limit`	int optional	—	Maximum number of labels to return. When not set, all labels are returned (Gmail typically has under 500 labels per account).

Sample Configuration

{
  "nodeType": "Gmail",
  "operation": "label/getMany",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d"
}

Validation Errors

Error	Cause	Resolution
`INVALID_CREDENTIAL`	OAuth token expired or credential not found	Re-authenticate in BizFirst Credentials Manager
`QUOTA_EXCEEDED`	Gmail API quota exhausted	Reduce call frequency; label lists rarely change so cache results

Output

Success Port

Field	Type	Description
`labels`	array	Array of label objects (both system and user labels)
`labels[].labelId`	string	Gmail label ID
`labels[].name`	string	Label display name
`labels[].type`	string	`system` or `user`
`labels[].labelListVisibility`	string	Label list visibility setting
`labels[].messageListVisibility`	string	Message list visibility setting
`status`	string	`success`
`errorCode`	string	Empty on success

Error Port

On failure, routes to the error port with status: "error", errorCode, and errorMessage.

Sample Output

{
  "labels": [
    { "labelId": "INBOX", "name": "INBOX", "type": "system", "labelListVisibility": "labelShow", "messageListVisibility": "show" },
    { "labelId": "SENT", "name": "SENT", "type": "system", "labelListVisibility": "labelShow", "messageListVisibility": "show" },
    { "labelId": "Label_987654321", "name": "BizFirst/Processed", "type": "user", "labelListVisibility": "labelShow", "messageListVisibility": "show" },
    { "labelId": "Label_123456789", "name": "Support/Open", "type": "user", "labelListVisibility": "labelShow", "messageListVisibility": "show" }
  ],
  "status": "success",
  "errorCode": ""
}

Expression Reference

Expression	Resolves To	Example Use
`{{labelList.labels}}`	Full array of label objects	Loop for label audit
`{{labelList.labels \| where: 'name', 'BizFirst/Processed' \| first \| prop: 'labelId'}}`	Label ID for "BizFirst/Processed"	Resolved ID for message/addLabel
`{{labelList.labels \| where: 'type', 'user'}}`	Only user-created labels	Filter for cleanup audit

Node Policies & GuardRails

Policy	Rule
Cache Label Results	Label lists change infrequently — call label/getMany once at workflow start and store results in a workflow variable rather than calling repeatedly
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
Dynamic ID Resolution	Never hardcode user label IDs in workflow config — always resolve them via label/getMany at runtime since IDs are account-specific
Quota Management	Label list operations cost 1 quota unit — very cheap, but caching avoids unnecessary calls in long-running workflows
System Label Constants	System label IDs (INBOX, SENT, TRASH, SPAM, STARRED, IMPORTANT, UNREAD) are constants — no lookup needed for these
Test Isolation	Test label listing against a dedicated Gmail test account that mirrors production label structure

Examples

Example 1: Workflow Initialization — Label ID Lookup

At workflow start, retrieve all labels and store the "BizFirst/Processed" label ID in a workflow variable.

{
  "nodeType": "Gmail",
  "operation": "label/getMany",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d"
}

Example 2: Label Inventory Report

List all user-created labels and generate a report of label names and message counts for administrative review.

{
  "nodeType": "Gmail",
  "operation": "label/getMany",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d"
}

Example 3: Upsert Label Check

Before creating a "Compliance/GDPR" label, check if it already exists to avoid the duplicate-name error.

{
  "nodeType": "Gmail",
  "operation": "label/getMany",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d"
}