message/addLabel

Add one or more labels to a Gmail message for categorization, routing, and workflow state tracking.

Label IDs: Use label/getMany to retrieve label IDs for user-created labels. System label IDs are constants: INBOX, SENT, TRASH, SPAM, STARRED, IMPORTANT, UNREAD.

When to Use

Workflow state tagging: Apply a "Processed" or "Ingested" label after a workflow extracts data from an email, preventing duplicate processing on subsequent runs.
Team inbox routing: Apply department-specific labels (e.g. "Finance", "Legal") so shared inbox team members can filter emails by their area.
CRM integration tagging: After syncing an email to a CRM contact, apply a "CRM-Synced" label for traceability.
Priority escalation: Apply the IMPORTANT or STARRED system label to high-priority emails identified by a classification node.
Compliance labeling: Tag emails matching specific regulatory criteria (e.g. "GDPR-Subject-Request") for compliance team review.

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
`messageId`	string required	—	Gmail message ID to apply labels to.
`labelIds`	string[] optional	—	Array of label IDs to add. Can include system labels (`STARRED`, `IMPORTANT`) and user-created label IDs. Use `label/getMany` to resolve user label IDs.

System Label IDs: INBOX, SENT, TRASH, SPAM, STARRED, IMPORTANT, UNREAD. User-created label IDs are alphanumeric strings (e.g. Label_123456789) — retrieve them with label/getMany.

Sample Configuration

{
  "nodeType": "Gmail",
  "operation": "message/addLabel",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "messageId": "{{processedEmail.messageId}}",
  "labelIds": ["Label_987654321", "STARRED"]
}

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: messageId`	`messageId` is empty	Ensure upstream node provides a valid message ID
`INVALID_LABEL_ID`	One or more label IDs do not exist in the account	Use `label/getMany` to retrieve valid label IDs before referencing them
`MESSAGE_NOT_FOUND`	Message does not exist in the account	Verify message ID comes from the authenticated account
`INVALID_CREDENTIAL`	OAuth token expired or credential not found	Re-authenticate in BizFirst Credentials Manager
`PERMISSION_DENIED`	Credential lacks `gmail.modify` scope	Re-grant OAuth permissions with the correct scope

Output

Success Port

Field	Type	Description
`success`	bool	`true` when labels were successfully applied
`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
`{{processedEmail.messageId}}`	Message ID from upstream processing node	`messageId` field
`{{labelLookup.processedLabelId}}`	Label ID from a previous label/getMany lookup	`labelIds` array element
`{{classification.departmentLabelId}}`	Department label ID resolved from classification output	Dynamic label routing
`{{imapTrigger.messageId}}`	Message ID from IMAP trigger	Label immediately on receipt

Node Policies & GuardRails

Policy	Rule
Label ID Resolution	Always resolve user label IDs with `label/getMany` at workflow start — do not hardcode user label IDs as they differ between Gmail accounts
Idempotency	Adding a label that is already applied is a no-op — safe to call multiple times for the same message
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
System Label Caution	Adding `TRASH` or `SPAM` via addLabel moves the message — use dedicated trash/spam operations for clarity
Quota Management	Label operations cost 1–5 quota units — safe for high-frequency use in batch workflows
Test Isolation	Test label workflows against a dedicated Gmail test account before connecting production

Examples

Example 1: Apply Processing State Label

After extracting data from an email, apply a "Processed" label to prevent duplicate processing.

{
  "nodeType": "Gmail",
  "operation": "message/addLabel",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "messageId": "{{dataExtraction.sourceMessageId}}",
  "labelIds": ["{{workflow.processedLabelId}}"]
}

Example 2: Priority Escalation

A sentiment analysis node detects an urgent customer complaint — apply STARRED and IMPORTANT labels.

{
  "nodeType": "Gmail",
  "operation": "message/addLabel",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "messageId": "{{sentiment.urgentMessageId}}",
  "labelIds": ["STARRED", "IMPORTANT"]
}

Example 3: Department Routing Label

A subject-line classifier determines the department and applies the corresponding label for inbox routing.

{
  "nodeType": "Gmail",
  "operation": "message/addLabel",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "messageId": "{{classifier.messageId}}",
  "labelIds": ["{{classifier.departmentLabelId}}"]
}