thread/trash

Move an entire Gmail thread and all its messages to the trash. Recoverable for 30 days.

Recommended Deletion Method: thread/trash is the safe default for removing email conversations — all messages in the thread are moved to trash and remain recoverable for 30 days. Use thread/delete only when permanent removal is explicitly required.

When to Use

Closed support ticket archival: After a support ticket is fully resolved and closed, trash the associated Gmail thread to clean the inbox while keeping the conversation available for 30 days.
Processed conversation removal: After all messages in a thread have been extracted, synced to a CRM, and processed, trash the thread for inbox hygiene.
Spam thread removal with recovery option: Move identified spam threads to trash rather than permanently deleting, allowing false positives to be recovered.
Inbox zero automation: After labeling and routing all messages in a thread, trash the original inbox thread as part of inbox zero maintenance.
Automated test cleanup: Trash test threads during test workflow cleanup cycles while retaining them for post-test inspection within the 30-day window.

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 move to trash. All messages in the thread are trashed together.

Sample Configuration

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

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: threadId`	`threadId` is empty	Provide a valid thread ID
`THREAD_NOT_FOUND`	Thread does not exist or is already trashed	Handle gracefully — thread may have been trashed previously
`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 moved to trash
`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
`{{resolvedTicket.gmailThreadId}}`	Thread ID from resolved support ticket	`threadId` field
`{{imapTrigger.threadId}}`	Thread ID from IMAP trigger	Post-processing cleanup
`{{loop.current.threadId}}`	Current thread in a batch Loop	Batch thread trash operation

Node Policies & GuardRails

Policy	Rule
Preferred Over Delete	Use `thread/trash` as the default for all thread removal scenarios — provides 30-day recovery window
All Messages Affected	Trashing a thread moves ALL messages in the thread — verify the entire thread should be removed before invoking
30-Day Recovery Window	Trashed threads auto-permanently-delete after 30 days — run untrash workflows within this window if recovery is needed
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
Quota Management	Thread trash operations cost minimal quota — safe for batch workflows
Test Isolation	Test thread trash workflows against a dedicated Gmail test account

Examples

Example 1: Resolved Ticket Thread Cleanup

After a support ticket is marked resolved and archived in the help-desk, trash the Gmail thread.

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

Example 2: Batch Processed Thread Cleanup

After extracting data from multiple threads via a Loop, trash all processed threads.

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

Example 3: Spam Thread Bulk Trash

Classified spam threads are trashed (not permanently deleted) to allow false-positive recovery.

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