message/untrash

Restore a Gmail message from the trash back to the inbox (or its previous label location).

Recovery Window: Messages remain in trash for 30 days before auto-permanent-deletion. message/untrash must be called within this window. After 30 days, the message is permanently gone.

When to Use

False-positive spam recovery: A spam classifier incorrectly trashed a legitimate customer email — restore it to the inbox for processing.
Workflow error recovery: An automated trash operation was triggered by a misconfigured rule — restore affected messages as part of the error recovery flow.
Human-requested restore: A user reports a missing email via a support portal — the workflow locates and restores the trashed message programmatically.
Compliance hold reversal: A message incorrectly subject to a trash sweep needs restoration due to a legal hold requirement.
Test workflow cleanup reversal: After a test run incorrectly trashed messages in a shared account, restore them in the cleanup phase.

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
`messageId`	string required	—	Gmail message ID to restore from trash.

Sample Configuration

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

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: messageId`	`messageId` is empty	Ensure the upstream node provides a valid message ID
`MESSAGE_NOT_FOUND`	Message does not exist, not in trash, or permanently deleted	Check that the message is currently in the TRASH label and within the 30-day window
`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 message 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.messageId}}`	Message ID from a recovery request form or event	`messageId` field
`{{errorHandler.trashedMessageId}}`	Message ID recorded before an erroneous trash action	Rollback in error recovery flow
`{{loop.current.messageId}}`	Current message in a batch restore Loop	Bulk untrash operation

Node Policies & GuardRails

Policy	Rule
30-Day Window	Messages are permanently deleted from trash after 30 days — recovery workflows must execute within this window
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
Idempotency	Calling untrash on a message that is not in trash returns MESSAGE_NOT_FOUND — handle this in the error port gracefully
Audit Logging	Log the untrash action (messageId, timestamp, reason) in an audit trail for compliance tracking
Quota Management	Untrash operations cost minimal API quota — safe for batch usage in a Loop node
Test Isolation	Test restore workflows against a dedicated Gmail test account before connecting production

Examples

Example 1: Restore False-Positive Spam

After a spam classifier flags a legitimate email, the review node detects the error and restores the message.

{
  "nodeType": "Gmail",
  "operation": "message/untrash",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "messageId": "{{spamReview.falsePositiveMessageId}}"
}

Example 2: User-Requested Email Recovery

A user submits a recovery request via a form. The workflow retrieves the message ID from the request and restores the email.

{
  "nodeType": "Gmail",
  "operation": "message/untrash",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "messageId": "{{formSubmission.gmailMessageId}}"
}

Example 3: Workflow Error Rollback

A CatchBlock node detects that a trash operation was triggered incorrectly and rolls back by restoring the message.

{
  "nodeType": "Gmail",
  "operation": "message/untrash",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "messageId": "{{catchBlock.failedOperation.messageId}}"
}