thread/addLabel

Add one or more labels to ALL messages in a Gmail thread simultaneously.

Thread-Wide Operation: Unlike message/addLabel which targets a single message, thread/addLabel applies the specified labels to every message in the thread in a single API call — more efficient for conversation-level categorization.

When to Use

Conversation-level status tagging: Apply a "Processed" or "CRM-Synced" label to the entire thread after extracting and syncing all messages to a CRM system.
Department routing by conversation: Apply team labels to entire threads so team members see complete conversations filtered by their department label.
Priority escalation at thread level: Apply STARRED or IMPORTANT to an entire conversation when an escalation is triggered, ensuring all past messages are visibly flagged.
Project labeling: Tag a full conversation with a project label when it is associated with a project in the project management system.
Compliance thread labeling: Apply regulatory compliance labels to an entire conversation for audit and governance workflows.

Configuration

Connection

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

Operation Fields

Field	Type	Default	Description
`threadId`	string required	—	Gmail thread ID. Labels are applied to every message in this thread.
`labelIds`	string[] required	—	Array of label IDs to add to all messages in the thread. Supports system labels and user label IDs.

Sample Configuration

{
  "nodeType": "Gmail",
  "operation": "thread/addLabel",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "threadId": "{{processedThread.threadId}}",
  "labelIds": ["{{workflow.processedLabelId}}", "STARRED"]
}

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: threadId`	`threadId` is empty	Provide a valid thread ID
`MISSING_FIELD: labelIds`	`labelIds` is empty array	Provide at least one label ID
`INVALID_LABEL_ID`	One or more label IDs do not exist	Resolve label IDs with `label/getMany` before using
`THREAD_NOT_FOUND`	Thread does not exist in the account	Verify thread ID comes from the authenticated account
`INVALID_CREDENTIAL`	OAuth token expired or credential not found	Re-authenticate in BizFirst Credentials Manager

Output

Success Port

Field	Type	Description
`success`	bool	`true` when labels were successfully applied to all thread messages
`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

{
  "success": true,
  "status": "success",
  "errorCode": ""
}

Expression Reference

Expression	Resolves To	Example Use
`{{processedThread.threadId}}`	Thread ID from upstream processing node	`threadId` field
`{{workflow.processedLabelId}}`	Label ID resolved from label/getMany at workflow start	`labelIds` array element
`{{classification.departmentLabelId}}`	Department label ID from classification output	Dynamic label routing

Node Policies & GuardRails

Policy	Rule
Label ID Resolution	Always resolve user label IDs with `label/getMany` at workflow start — never hardcode user label IDs
Thread-Wide Impact	Labels are applied to ALL messages in the thread — verify the correct thread is targeted before applying sensitive labels
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
Idempotency	Adding a label that is already applied to all thread messages is a no-op — safe to call multiple times
Quota Management	Thread label operations cost 1–5 quota units — safe for batch workflows using a Loop node
Test Isolation	Test thread labeling against a dedicated Gmail test account before connecting production

Examples

Example 1: Thread Processing State Label

After syncing all messages from a thread to the CRM, apply a "CRM-Synced" label to the entire conversation.

{
  "nodeType": "Gmail",
  "operation": "thread/addLabel",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "threadId": "{{crmSync.threadId}}",
  "labelIds": ["{{labelLookup.crmSyncedLabelId}}"]
}

Example 2: Priority Escalation Thread Flag

Mark an entire escalated conversation as STARRED and IMPORTANT for high visibility.

{
  "nodeType": "Gmail",
  "operation": "thread/addLabel",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "threadId": "{{escalation.threadId}}",
  "labelIds": ["STARRED", "IMPORTANT"]
}

Example 3: Project Thread Association

When a conversation is linked to a project in the project management tool, apply the project label to the entire thread.

{
  "nodeType": "Gmail",
  "operation": "thread/addLabel",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "threadId": "{{project.linkedThreadId}}",
  "labelIds": ["{{labelLookup.projectLabelId}}"]
}