label/create

Create a new user-defined Gmail label for categorizing and routing messages in automated workflows.

When to Use

Workflow processing labels: Create a "Processed-by-BizFirst" label at workflow initialization to tag emails after automated extraction, preventing duplicate processing.
Project-specific labels: When a new project is created in a project management system, automatically create a corresponding Gmail label for email routing.
Team inbox routing labels: Create department or team labels (Finance, Support, Legal) to route emails from a shared inbox to the appropriate team's filter view.
Compliance category labels: Create regulatory compliance labels (GDPR-Request, Legal-Hold) for classification workflows.
CRM integration tags: Create client-specific labels when a new client record is added to the CRM, enabling per-client email filtering.

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
`name`	string required	—	Label display name. Must be unique in the account. Case-sensitive. Supports nesting with "/" separator (e.g. "Projects/Alpha").
`labelListVisibility`	enum optional	`labelShow`	Whether the label appears in the Gmail label list: `labelShow` (visible), `labelHide` (hidden), `labelShowIfUnread` (visible only when messages are unread).
`messageListVisibility`	enum optional	`show`	Whether messages with this label appear in the message list: `show` or `hide`.

Sample Configuration

{
  "nodeType": "Gmail",
  "operation": "label/create",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "name": "BizFirst/Processed",
  "labelListVisibility": "labelShow",
  "messageListVisibility": "show"
}

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: name`	Label name is empty	Provide a non-empty label name
`LABEL_ALREADY_EXISTS`	A label with this name already exists	Use `label/getMany` to check for existing labels before creating; implement upsert logic
`INVALID_LABEL_NAME`	Label name contains invalid characters or is too long	Gmail label names must be under 225 characters and cannot contain certain special characters
`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 (e.g. `Label_987654321`) — use this in message/addLabel and thread/addLabel operations
`name`	string	Label display name as stored
`labelListVisibility`	string	Configured list visibility setting
`messageListVisibility`	string	Configured message visibility setting
`type`	string	`user` for user-created labels
`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": "Label_987654321",
  "name": "BizFirst/Processed",
  "labelListVisibility": "labelShow",
  "messageListVisibility": "show",
  "type": "user",
  "status": "success",
  "errorCode": ""
}

Expression Reference

Expression	Resolves To	Example Use
`{{labelCreate.labelId}}`	New label ID from this node's output	Pass immediately to message/addLabel
`{{project.name}}`	Project name from CRM or upstream data	Dynamic label name: `Projects/{{project.name}}`
`{{client.name}}`	Client name for per-client label	Label name: `Clients/{{client.name}}`

Node Policies & GuardRails

Policy	Rule
Idempotency Check	Check for existing labels with `label/getMany` before creating — duplicate label names throw an error
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
Label ID Capture	Always store the returned `labelId` in a workflow variable for use in subsequent message/addLabel operations
Naming Convention	Use a consistent prefix (e.g. "BizFirst/") for workflow-created labels to distinguish them from manually created labels
Quota Management	Label create operations cost 1 quota unit — safe for frequent creation in provisioning workflows
Test Isolation	Test label creation workflows against a dedicated Gmail test account; created labels persist and must be manually deleted after testing

Examples

Example 1: Workflow Initialization Label

At the start of an automated email processing workflow, ensure the "Processed" label exists (create it if not).

{
  "nodeType": "Gmail",
  "operation": "label/create",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "name": "BizFirst/Processed",
  "labelListVisibility": "labelShowIfUnread",
  "messageListVisibility": "show"
}

Example 2: New CRM Client Label

When a new client is added to the CRM, create a Gmail label for their email folder.

{
  "nodeType": "Gmail",
  "operation": "label/create",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "name": "Clients/{{crm.newClient.name}}",
  "labelListVisibility": "labelShow",
  "messageListVisibility": "show"
}

Example 3: Compliance Category Label

Create a GDPR-Request label for flagging emails that contain data subject access requests.

{
  "nodeType": "Gmail",
  "operation": "label/create",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "name": "Compliance/GDPR-Request",
  "labelListVisibility": "labelShow",
  "messageListVisibility": "show"
}