label/delete

Delete a user-created Gmail label. The label is removed from all messages and cannot be recovered.

System Labels Cannot Be Deleted: Labels like INBOX, SENT, TRASH, SPAM, STARRED, IMPORTANT, and UNREAD are system labels and cannot be deleted. Attempting to delete them returns CANNOT_DELETE_SYSTEM_LABEL. Only user-created labels (type: user) can be deleted.

Label Removal from Messages: Deleting a label removes it from ALL messages it was applied to. The messages themselves are not deleted — only the label association is removed.

When to Use

Completed project cleanup: When a project is archived or completed in a project management system, delete the corresponding Gmail project label to clean up the inbox sidebar.
Client offboarding: When a client relationship ends, delete the client-specific Gmail label as part of the offboarding workflow.
Test environment cleanup: After automated test workflows create temporary labels for testing purposes, delete them in the cleanup phase.
Label reorganization: Delete old labels as part of a label taxonomy reorganization workflow that recreates them under a new naming convention.
Stale label hygiene: In a scheduled cleanup workflow, identify user labels with zero messages and delete them to maintain a clean label structure.

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
`labelId`	string required	—	Gmail label ID to delete. Must be a user-created label (type: `user`). Use `label/getMany` to resolve the ID.

Sample Configuration

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

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: labelId`	`labelId` is empty	Provide a valid user label ID
`CANNOT_DELETE_SYSTEM_LABEL`	Attempting to delete a system label	Only user-created labels can be deleted — check `type` field before deleting
`LABEL_NOT_FOUND`	Label ID does not exist or was already deleted	Treat as idempotent success in cleanup workflows
`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 the label was permanently deleted
`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
`{{labelLookup.projectLabelId}}`	Label ID resolved from label/getMany earlier in workflow	`labelId` field
`{{loop.current.labelId}}`	Current label ID in a batch cleanup Loop	Batch label deletion
`{{labelCreate.labelId}}`	Label ID from earlier label/create in same workflow	Delete after test workflow completes

Node Policies & GuardRails

Policy	Rule
System Label Guard	Always verify `type: 'user'` before deleting — system labels throw CANNOT_DELETE_SYSTEM_LABEL
Message Impact Awareness	Deleting a label removes it from all messages it was applied to — messages are NOT deleted, only the label association is removed
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
Idempotency	Deleting a label that no longer exists returns LABEL_NOT_FOUND — handle this gracefully in the error port for cleanup workflows
Quota Management	Label delete operations cost minimal quota — safe for batch cleanup workflows
Test Isolation	Test label deletion against a dedicated Gmail test account to avoid deleting production labels

Examples

Example 1: Project Archive Cleanup

When a project is archived, resolve and delete its Gmail label as part of the offboarding workflow.

{
  "nodeType": "Gmail",
  "operation": "label/delete",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "labelId": "{{labelList.labels | where: 'name', 'Projects/{{project.name}}' | first | prop: 'labelId'}}"
}

Example 2: Test Cleanup

After a test workflow completes, delete the temporary label that was created for testing.

{
  "nodeType": "Gmail",
  "operation": "label/delete",
  "credentialId": "test-credential-id",
  "labelId": "{{testSetup.createdLabelId}}"
}

Example 3: Stale Label Batch Cleanup

A scheduled workflow finds all user labels with 0 messages and deletes them via a Loop node.

{
  "nodeType": "Gmail",
  "operation": "label/delete",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "labelId": "{{loop.current.labelId}}"
}