thread/removeLabel

Remove one or more labels from ALL messages in a Gmail thread simultaneously.

Thread-Wide Operation: thread/removeLabel removes the specified labels from every message in the thread in a single API call — more efficient than calling message/addLabel on each message individually.

When to Use

Status label transition: Remove "Pending-Review" from an entire thread and add "Reviewed" after a reviewer completes their assessment of the conversation.
Department re-routing: Remove a department label from a thread that was incorrectly routed and apply the correct department label.
Project unassignment: When a thread is removed from a project, strip the project label from the entire conversation.
Completed workflow state reset: Remove workflow state labels (e.g. "In-Progress") from a thread when the associated task is complete.
Priority de-escalation: Remove STARRED or IMPORTANT from an entire thread after an escalation is resolved and normal SLA applies.

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 removed from every message in this thread.
`labelIds`	string[] required	—	Array of label IDs to remove from all messages in the thread.

Sample Configuration

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

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 to remove
`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 removed from 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
`{{completedTask.threadId}}`	Thread ID from completed task event	`threadId` field
`{{labelLookup.inProgressLabelId}}`	In-Progress label ID from label/getMany lookup	`labelIds` element to remove
`{{reroutedThread.threadId}}`	Thread ID for re-routing operation	Remove old department label before adding new one

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 removed from ALL messages in the thread — verify the correct thread is targeted
Idempotency	Removing a label that is not applied to thread messages is a no-op — safe to call multiple times
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
Quota Management	Thread label operations cost 1–5 quota units — safe for batch workflows
Test Isolation	Test thread label operations against a dedicated Gmail test account before connecting production

Examples

Example 1: Status Label Transition

Remove "Pending-Review" label from entire thread after review is complete, then add "Reviewed" label.

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

Example 2: Department Re-routing

Remove incorrect Finance label from a thread that was mis-routed, before applying the correct Support label.

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

Example 3: Priority De-escalation

After an escalation is resolved, remove STARRED and IMPORTANT from the thread.

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