message/trash

Move a Gmail message to the trash. The message is recoverable for 30 days before permanent auto-deletion.

Recoverable: Trashed messages are retained for 30 days and can be restored with message/untrash. This is the recommended default deletion method over message/delete.

When to Use

Post-processing cleanup: After extracting and processing data from an email, move it to trash to keep the inbox clean while retaining the ability to recover.
Spam/junk archival: Automatically trash emails identified as spam by a classification node, with the option to review and recover false positives.
Inbox zero automation: After routing emails to appropriate labels or CRM records, trash the original inbox copy to maintain a clean working inbox.
Automated test cleanup: Trash test emails during workflow testing to avoid inbox clutter while keeping messages recoverable during the test cycle.
Low-priority message deferral: Move bulk or low-priority emails to trash for a timed review period before permanent deletion.

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 move to the trash.

Sample Configuration

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

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: messageId`	`messageId` is empty	Ensure upstream node provides a valid message ID
`MESSAGE_NOT_FOUND`	Message does not exist or is already trashed	Verify the message ID; already-trashed messages return this error
`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 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
`{{processedMessage.messageId}}`	Message ID from upstream processing node	`messageId` field
`{{loop.current.messageId}}`	Current message ID in a batch Loop node	Batch trash operation
`{{imapTrigger.messageId}}`	Message ID from IMAP trigger	Post-processing cleanup

Node Policies & GuardRails

Policy	Rule
Preferred Deletion Method	Use `message/trash` instead of `message/delete` for all standard deletion scenarios — trashed messages are recoverable for 30 days
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
Quota Management	Trash operation costs minimal quota units — safe for batch workflows using a Loop node
Recovery Window	Messages in trash are auto-permanently-deleted after 30 days — ensure recovery workflows run within this window if reversal is needed
PII Protection	Do not log message IDs in a way that cross-references with PII data in workflow execution history
Test Isolation	Test trash workflows against a dedicated Gmail test account before connecting a production inbox

Examples

Example 1: Post-Processing Inbox Cleanup

After extracting data from a processed email and creating a CRM record, move the source email to trash.

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

Example 2: Batch Trash Spam-Classified Messages

After a classification node identifies spam messages, loop through the results and trash each one.

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

Example 3: Inbox Zero After Label Routing

After applying project labels to an email and syncing to a project management system, trash the inbox copy.

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