message/delete

Permanently delete a Gmail message, bypassing the trash. This action is irreversible.

Permanent Deletion: message/delete bypasses the trash and permanently removes the message. It cannot be recovered. For recoverable deletion, use message/trash instead.

When to Use

GDPR right-to-erasure: Permanently delete a specific email containing a user's personal data after a verified erasure request, following legal confirmation.
Automated test cleanup: In CI/CD test workflows, purge test emails sent to a test Gmail account after assertions are complete.
Sensitive credential purge: After extracting a one-time password or API key from an email body, permanently delete the message to prevent credential exposure.
Compliance-mandated destruction: Execute court-ordered or regulatory email destruction after the required legal hold period expires.
Duplicate cleanup: Permanently remove identified duplicate messages after verification that the original copy has been archived elsewhere.

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 permanently delete. Ensure this is verified before passing to the node.

Sample Configuration

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

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: messageId`	`messageId` is empty or not provided	Ensure the upstream node provides a valid Gmail message ID
`MESSAGE_NOT_FOUND`	Message does not exist or already deleted	Verify the message ID; treat as idempotent success if already deleted
`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 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.targetMessageId}}`	Message ID from GDPR erasure request data	`messageId` field
`{{testCleanup.sentMessageId}}`	Message ID from previous test send node	Cleanup after test assertion
`{{loop.current.messageId}}`	Current message ID in a Loop node iteration	Batch deletion loop

Node Policies & GuardRails

Policy	Rule
Use Trash First	Default to `message/trash` for all deletion scenarios — use `message/delete` only after explicit legal or compliance confirmation
GDPR Compliance	Only invoke for GDPR right-to-erasure after legal team confirmation — log the erasure event in an audit system before deletion
Irreversibility Warning	This action cannot be undone — implement an approval node (HIL) upstream for production delete workflows
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
Audit Logging	Always log the message ID, timestamp, and deletion reason in an audit trail before executing deletion
Test Isolation	Only run automated deletion workflows against dedicated test Gmail accounts — never point at production inbox during development

Examples

Example 1: GDPR Erasure Workflow

After legal team approves an erasure request via an approval node, permanently delete the target message.

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

Example 2: Test Email Cleanup

In an automated test workflow, delete the test email after verifying it was received correctly.

{
  "nodeType": "Gmail",
  "operation": "message/delete",
  "credentialId": "test-account-credential-id",
  "messageId": "{{testSend.messageId}}"
}

Example 3: Credential Purge After Extraction

After extracting a one-time API token from an email, immediately delete the message to prevent exposure.

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