thread/untrash

Restore a trashed Gmail thread and all its messages back to the inbox.

30-Day Window: Threads remain recoverable from trash for 30 days. After that, they are permanently auto-deleted. thread/untrash must be called within this window.

When to Use

False-positive spam thread recovery: A spam classifier incorrectly trashed a legitimate customer conversation — restore the entire thread for continued processing.
Workflow error rollback: An automated trash operation was triggered by a misconfigured rule — restore affected threads as part of the error recovery flow.
Human-requested thread restore: A user reports that a full conversation was incorrectly removed — the workflow locates the trashed thread and restores it programmatically.
Compliance hold reversal: A thread incorrectly subject to a trash sweep needs restoration due to a legal hold requirement.
Ticket re-open restore: A closed support ticket is re-opened, requiring the original email thread to be restored to the active inbox.

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 restore from trash. All messages in the thread are restored together.

Sample Configuration

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

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: threadId`	`threadId` is empty	Provide a valid thread ID
`THREAD_NOT_FOUND`	Thread not in trash or permanently deleted	Verify thread is within the 30-day recovery window; permanently deleted threads cannot be recovered
`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 restored from 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
`{{recoveryRequest.threadId}}`	Thread ID from recovery form or event	`threadId` field
`{{errorHandler.trashedThreadId}}`	Thread ID recorded before erroneous trash action	Rollback in error recovery flow
`{{ticket.reopenedThreadId}}`	Thread ID from re-opened support ticket event	Restore thread on ticket reopen

Node Policies & GuardRails

Policy	Rule
30-Day Window	Threads are permanently deleted from trash after 30 days — recovery workflows must execute within this window
All Messages Restored	Untrashing a thread restores ALL messages in the thread — the entire conversation is returned to the inbox
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
Audit Logging	Log the untrash action (threadId, timestamp, reason) in an audit trail for compliance tracking
Quota Management	Thread untrash operations cost minimal quota — safe for use in recovery workflows
Test Isolation	Test restore workflows against a dedicated Gmail test account

Examples

Example 1: False-Positive Thread Recovery

A review node detects a misclassified spam thread and restores the entire conversation.

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

Example 2: Support Ticket Re-open

When a support ticket is re-opened, restore the original Gmail thread to the active inbox.

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

Example 3: Workflow Error Rollback

A CatchBlock detects that a trash operation was incorrectly triggered and restores the thread.

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