label/get

Retrieve full details for a specific Gmail label by its ID, including message and thread counts.

When to Use

Label health monitoring: Retrieve a label's unread count and total message count as part of a dashboard reporting workflow to track inbox queue depth.
Label existence verification: Before applying a label in a workflow, verify the label exists and retrieve its current properties.
Unread count alerting: Monitor a specific label's messagesUnread count and trigger an alert if it exceeds a threshold.
Label property audit: Retrieve label visibility settings for compliance auditing of Gmail organization configuration.
Thread count tracking: Use label thread counts to measure the volume of conversations under a specific category label.

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
`labelId`	string required	—	Gmail label ID to retrieve. Use system label IDs (`INBOX`, `SENT`, etc.) or user label IDs from `label/getMany`.

Sample Configuration

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

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: labelId`	`labelId` is empty	Provide a valid label ID (system or user)
`LABEL_NOT_FOUND`	Label ID does not exist in this account	Use `label/getMany` to enumerate valid label IDs
`INVALID_CREDENTIAL`	OAuth token expired or credential not found	Re-authenticate in BizFirst Credentials Manager

Output

Success Port

Field	Type	Description
`labelId`	string	Gmail label ID
`name`	string	Label display name
`labelListVisibility`	string	Label list visibility setting
`messageListVisibility`	string	Message list visibility setting
`type`	string	`system` for system labels, `user` for user-created labels
`messagesTotal`	number	Total number of messages with this label
`messagesUnread`	number	Number of unread messages with this label
`threadsTotal`	number	Total number of threads with this label
`threadsUnread`	number	Number of unread threads with this label
`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

{
  "labelId": "INBOX",
  "name": "INBOX",
  "labelListVisibility": "labelShow",
  "messageListVisibility": "show",
  "type": "system",
  "messagesTotal": 1452,
  "messagesUnread": 23,
  "threadsTotal": 890,
  "threadsUnread": 18,
  "status": "success",
  "errorCode": ""
}

Expression Reference

Expression	Resolves To	Example Use
`{{labelGet.messagesUnread}}`	Count of unread messages in the label	Threshold check for alerting
`{{labelGet.threadsTotal}}`	Total thread count for reporting	Dashboard metric node
`{{labelGet.name}}`	Label display name	Notification or report title

Node Policies & GuardRails

Policy	Rule
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
System Labels	System label IDs are constants and do not require lookup — use `INBOX`, `SENT`, etc. directly
Quota Management	Label get operations cost 1 quota unit — safe for frequent polling in monitoring workflows
Count Freshness	Message/thread counts are approximate and may have a short propagation delay — not suitable for exact real-time counting
PII Protection	Label names may reflect sensitive organizational structure — do not log label metadata in public-facing audit trails
Test Isolation	Test label monitoring workflows against a dedicated Gmail test account

Examples

Example 1: Inbox Unread Count Alert

Poll INBOX unread count every 30 minutes and send a Slack alert if it exceeds 50.

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

Example 2: Support Queue Depth Report

Retrieve the "Support/Open" label message count for a daily queue depth report to management.

{
  "nodeType": "Gmail",
  "operation": "label/get",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "labelId": "{{labelLookup.supportOpenLabelId}}"
}

Example 3: Label Existence Verification

Before applying a label, verify it exists and retrieve its current properties for conditional logic.

{
  "nodeType": "Gmail",
  "operation": "label/get",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "labelId": "{{workflowConfig.processingLabelId}}"
}