message/get

Retrieve a single Gmail message by its ID, with optional full-content and attachment download modes.

When to Use

Incoming email data extraction: Retrieve the full content of a customer email to parse structured data (order IDs, form responses) for downstream processing.
Support ticket processing: Fetch a specific message to extract the body, subject, and sender before creating a help-desk ticket.
Order confirmation parsing: Retrieve an order confirmation email and extract structured data for integration with an ERP system.
Invoice data extraction: Download an attached PDF invoice from a vendor email and pass the binary to a document parser node.
Audit and compliance reads: Fetch specific messages for audit trail verification without modifying the message state.

Configuration

Connection

Field	Type	Description
`credentialId`	Guid required	OAuth2 credential ID from BizFirst Credentials Manager. Requires `gmail.readonly` scope.

Operation Fields

Field	Type	Default	Description
`messageId`	string required	—	Gmail message ID to retrieve.
`simple`	bool optional	`true`	When `true`, returns a simplified output (headers + metadata). When `false`, returns full message including body HTML/text, all headers, and attachment metadata.
`downloadAttachments`	bool optional	`false`	When `true`, downloads attachment binary data and includes it in the output. Only effective when `simple: false`.
`attachmentPrefix`	string optional	`attachment_`	Prefix for binary attachment field names in the output object (e.g. `attachment_0`, `attachment_1`).

Sample Configuration

{
  "nodeType": "Gmail",
  "operation": "message/get",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "messageId": "{{trigger.messageId}}",
  "simple": false,
  "downloadAttachments": true,
  "attachmentPrefix": "file_"
}

Validation Errors

Error	Cause	Resolution
`MISSING_FIELD: messageId`	`messageId` is empty	Ensure upstream node provides a valid Gmail message ID
`MESSAGE_NOT_FOUND`	Message does not exist or belongs to another account	Verify the message ID comes from the authenticated account
`INVALID_CREDENTIAL`	OAuth token expired or credential not found	Re-authenticate in BizFirst Credentials Manager
`ATTACHMENT_DOWNLOAD_FAILED`	Attachment binary could not be retrieved	Check attachment size limits and retry; large attachments may require chunked handling

Output

Success Port — Simple Mode (`simple: true`)

Field	Type	Description
`messageId`	string	Gmail message ID
`threadId`	string	Thread this message belongs to
`snippet`	string	Short preview of the message body
`from`	string	Sender email address
`to`	string	Primary recipient(s)
`cc`	string	CC recipients
`subject`	string	Email subject line
`date`	string	Message date (RFC 2822 format)
`labelIds`	string[]	Applied label IDs (e.g. `["INBOX", "UNREAD"]`)
`sizeEstimate`	number	Estimated message size in bytes

Additional Fields — Full Mode (`simple: false`)

Field	Type	Description
`text`	string	Plain text body of the message
`html`	string	HTML body of the message
`textAsHtml`	string	Plain text body converted to HTML for display
`headers`	object	All email headers as key-value pairs
`attachments`	array	Attachment metadata: filename, mimeType, size, attachmentId
`file_0`, `file_1`…	binary	Downloaded attachment binaries (when `downloadAttachments: true`)

Error Port

On failure, routes to the error port with status: "error", errorCode, and errorMessage.

Sample Output

{
  "messageId": "18e4a2f9d3c0b1a7",
  "threadId": "18e4a2f9d3c0b1a7",
  "snippet": "Please find the invoice attached for your recent purchase...",
  "from": "vendor@example.com",
  "to": "accounts@bizfirstai.com",
  "cc": "",
  "subject": "Invoice #INV-2024-0591",
  "date": "Mon, 15 Jan 2024 09:34:12 +0000",
  "labelIds": ["INBOX", "UNREAD"],
  "sizeEstimate": 24580,
  "text": "Please find the invoice attached for your recent purchase...",
  "html": "<p>Please find the invoice attached for your recent purchase...</p>",
  "attachments": [
    {
      "filename": "invoice-INV-2024-0591.pdf",
      "mimeType": "application/pdf",
      "size": 21430,
      "attachmentId": "ANGjdJ8kLp..."
    }
  ],
  "status": "success",
  "errorCode": ""
}

Expression Reference

Expression	Resolves To	Example Use
`{{trigger.messageId}}`	Message ID from upstream trigger	`messageId` field
`{{gmailGet.from}}`	Sender address from this node's output	CRM lookup key downstream
`{{gmailGet.subject}}`	Email subject from this node's output	Ticket title in help-desk node
`{{gmailGet.attachments[0].filename}}`	First attachment filename	Document routing logic
`{{gmailGet.file_0}}`	Downloaded binary of first attachment	Pass to PDF parser node

Node Policies & GuardRails

Policy	Rule
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
PII Protection	Do not log email body or attachment content in workflow execution history — email content contains PII
Quota Management	messages.get costs 5 quota units — safe for frequent reads, but avoid tight polling loops; use IMAP triggers instead
Attachment Handling	Only enable `downloadAttachments: true` when the workflow requires binary processing; unnecessary downloads waste quota and memory
Simple Mode Default	Use `simple: true` (default) for metadata reads; only use `simple: false` when body content is needed
Test Isolation	Test message retrieval workflows against a dedicated test Gmail account before connecting production

Examples

Example 1: Parse Incoming Support Email

IMAP trigger fires → fetch full message to extract body and sender for CRM ticket creation.

{
  "nodeType": "Gmail",
  "operation": "message/get",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "messageId": "{{imapTrigger.messageId}}",
  "simple": false,
  "downloadAttachments": false
}

Example 2: Download Invoice Attachment for Accounting

Retrieve an invoice email with PDF attachment to pass to the accounting integration node.

{
  "nodeType": "Gmail",
  "operation": "message/get",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "messageId": "{{messageList.messages[0].messageId}}",
  "simple": false,
  "downloadAttachments": true,
  "attachmentPrefix": "invoice_"
}

Example 3: Audit Compliance Read

Read message metadata only (no body) for compliance audit trail recording.

{
  "nodeType": "Gmail",
  "operation": "message/get",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "messageId": "{{audit.targetMessageId}}",
  "simple": true,
  "downloadAttachments": false
}