thread/delete

Permanently delete an entire Gmail thread and all its messages. This action is irreversible.

Permanent — All Messages Deleted: thread/delete permanently removes ALL messages in the thread, not just the most recent one. This bypasses the trash. For recoverable deletion, use thread/trash instead.

When to Use

GDPR thread erasure: Permanently delete an entire email conversation containing a user's personal data after a verified erasure request with legal confirmation.
Test thread cleanup: In automated test workflows, permanently delete entire test conversation threads after test assertions are complete.
Sensitive credential thread purge: After extracting sensitive tokens from a multi-message thread, permanently delete the entire thread to prevent exposure.
Compliance-mandated destruction: Execute court-ordered destruction of a full email conversation after the required legal hold period expires.
Spam thread bulk removal: Permanently delete identified spam threads (vs. trashing them) when storage management requires immediate removal.

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 to permanently delete. ALL messages in the thread are removed.

Sample Configuration

{
  "nodeType": "Gmail",
  "operation": "thread/delete",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "threadId": "{{gdprErasure.targetThreadId}}"
}

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: threadId`	`threadId` is empty	Provide a valid thread ID
`THREAD_NOT_FOUND`	Thread does not exist or already deleted	Treat as success in cleanup workflows; thread was already removed
`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 thread 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
`{{gdprErasure.targetThreadId}}`	Thread ID from GDPR erasure request	`threadId` field
`{{loop.current.threadId}}`	Current thread in a batch deletion Loop	Bulk thread deletion
`{{testThread.threadId}}`	Thread ID from test setup node	Test cleanup

Node Policies & GuardRails

Policy	Rule
Use Trash First	Default to `thread/trash` for all deletion scenarios — use `thread/delete` only after explicit legal or compliance confirmation
All Messages Deleted	thread/delete removes ALL messages in the thread permanently — this is significantly more destructive than message/delete
GDPR Compliance	Only invoke for GDPR right-to-erasure after legal team confirmation — log the thread ID, timestamp, and reason before deletion
Human Approval Gate	Implement an approval node (HIL) upstream for production thread deletion workflows
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
Test Isolation	Test deletion workflows against a dedicated Gmail test account — never point at production inbox

Examples

Example 1: GDPR Full Thread Erasure

After legal approval via HIL node, permanently delete the entire email thread associated with the erasure request.

{
  "nodeType": "Gmail",
  "operation": "thread/delete",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "threadId": "{{gdprRequest.gmailThreadId}}"
}

Example 2: Test Conversation Cleanup

After a test workflow creates and validates a multi-message thread, delete the entire thread in cleanup.

{
  "nodeType": "Gmail",
  "operation": "thread/delete",
  "credentialId": "test-credential-id",
  "threadId": "{{testSetup.createdThreadId}}"
}

Example 3: Spam Thread Permanent Removal

After classification identifies confirmed spam threads, permanently delete them to reclaim storage.

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