message/getMany

List and filter Gmail messages using search queries, label filters, date ranges, and sender criteria.

Search Query Tip: The filterQ field accepts Gmail's native search syntax. Test your query in the Gmail web UI search bar before using it in automation. Multiple operators are ANDed together automatically.

When to Use

Support inbox batch processing: Retrieve all unread emails in the INBOX to process them through a classification and routing workflow.
Monthly invoice retrieval: Find all emails from a vendor with "Invoice" in the subject received in the current month for accounting automation.
CRM sync from sender: Retrieve all emails from a specific client and sync them to the CRM contact timeline.
Label-based archiving: Find all messages with a specific label and batch-archive or export them to a document store.
Newsletter response processing: Gather all replies to a newsletter campaign and route them to a survey analytics pipeline.

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
`returnAll`	bool optional	`false`	When `true`, retrieves all matching messages (ignores `limit`). Use with caution — may return thousands of results.
`limit`	int optional	`50`	Maximum number of messages to return when `returnAll` is `false`. Max: 500.
`simple`	bool optional	`true`	When `true`, returns simplified message objects (headers + metadata). When `false`, includes full body content.
`downloadAttachments`	bool optional	`false`	Download attachment binaries for each message. Only effective with `simple: false`.
`filterQ`	string optional	—	Gmail search query string (e.g. `from:client@example.com subject:Invoice`). Supports full Gmail query syntax.
`labelIds`	string[] optional	—	Filter by label IDs. Only messages with ALL specified labels are returned. Use `label/getMany` to resolve label IDs.
`readStatus`	enum optional	—	Filter by read status: `read` or `unread`.
`receivedAfter`	string optional	—	ISO date string — return messages received after this date (e.g. `2024-01-01`).
`receivedBefore`	string optional	—	ISO date string — return messages received before this date.
`sender`	string optional	—	Filter by sender email address. Equivalent to adding `from:` to `filterQ`.

Sample Configuration

{
  "nodeType": "Gmail",
  "operation": "message/getMany",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "returnAll": false,
  "limit": 25,
  "simple": true,
  "filterQ": "from:vendor@example.com subject:Invoice has:attachment",
  "receivedAfter": "2024-01-01",
  "receivedBefore": "2024-01-31",
  "readStatus": "unread"
}

Validation Errors

Error	Cause	Resolution
`INVALID_CREDENTIAL`	OAuth token expired or credential not found	Re-authenticate in BizFirst Credentials Manager
`INVALID_QUERY: filterQ`	Malformed Gmail search query	Validate the query in Gmail web UI before using in workflow
`INVALID_DATE: receivedAfter`	Date string is not parseable	Use ISO format: `YYYY-MM-DD`
`LIMIT_EXCEEDED`	`limit` value exceeds maximum of 500	Set `limit` to 500 or lower; use pagination for larger sets
`QUOTA_EXCEEDED`	Gmail API quota exhausted	Reduce list frequency; implement exponential backoff on retries

Output

Success Port

Field	Type	Description
`messages`	array	Array of message objects. Each object contains the fields described below.
`messages[].messageId`	string	Gmail message ID
`messages[].threadId`	string	Thread the message belongs to
`messages[].snippet`	string	Short message preview
`messages[].from`	string	Sender address
`messages[].to`	string	Primary recipient(s)
`messages[].subject`	string	Email subject
`messages[].date`	string	Message date (RFC 2822)
`messages[].labelIds`	string[]	Applied label IDs
`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

{
  "messages": [
    {
      "messageId": "18e4a2f9d3c0b1a7",
      "threadId": "18e4a2f9d3c0b1a7",
      "snippet": "Please find invoice #INV-001 attached...",
      "from": "vendor@example.com",
      "to": "accounts@bizfirstai.com",
      "subject": "Invoice #INV-001",
      "date": "Mon, 15 Jan 2024 09:34:12 +0000",
      "labelIds": ["INBOX", "UNREAD"]
    },
    {
      "messageId": "18e4b1c2d3e4f5a6",
      "threadId": "18e4b1c2d3e4f5a6",
      "snippet": "Attached is invoice #INV-002 for January...",
      "from": "vendor@example.com",
      "to": "accounts@bizfirstai.com",
      "subject": "Invoice #INV-002",
      "date": "Wed, 17 Jan 2024 14:21:05 +0000",
      "labelIds": ["INBOX", "UNREAD"]
    }
  ],
  "status": "success",
  "errorCode": ""
}

Expression Reference

Expression	Resolves To	Example Use
`{{gmailList.messages}}`	Array of message objects	Loop node input
`{{gmailList.messages[0].messageId}}`	First result's message ID	Pass to message/get for full content
`{{$vars.vendorEmail}}`	Dynamic sender filter from workflow variable	`sender` or `filterQ` field
`{{$now \| dateFormat:'YYYY-MM-01'}}`	First day of current month	`receivedAfter` field
`{{$now \| dateFormat:'YYYY-MM-DD'}}`	Today's date	`receivedBefore` field

Node Policies & GuardRails

Policy	Rule
Credential Storage	Store OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
ReturnAll Safety	Avoid `returnAll: true` on large inboxes — set a reasonable `limit` and use date filters to scope results
Quota Management	messages.list costs 5 quota units per call; each subsequent message/get for full content adds 5 more — plan batch sizes carefully
Query Validation	Test `filterQ` queries in Gmail web UI before automation; invalid queries return zero results silently
PII Protection	Do not log message content arrays in workflow execution history — email data contains PII
Test Isolation	Test filtering workflows against a dedicated Gmail test account to avoid unintended modifications to production inbox

Examples

Example 1: Process Unread Support Inbox

Scheduled trigger fires hourly, retrieves all unread INBOX messages, and routes each to a support workflow.

{
  "nodeType": "Gmail",
  "operation": "message/getMany",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "returnAll": false,
  "limit": 50,
  "labelIds": ["INBOX"],
  "readStatus": "unread",
  "simple": true
}

Example 2: Monthly Invoice Retrieval

Retrieve all vendor invoice emails received in the current month for accounting batch processing.

{
  "nodeType": "Gmail",
  "operation": "message/getMany",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "filterQ": "from:vendor@example.com subject:Invoice has:attachment",
  "receivedAfter": "{{$now | dateFormat:'YYYY-MM-01'}}",
  "receivedBefore": "{{$now | dateFormat:'YYYY-MM-DD'}}",
  "simple": false,
  "downloadAttachments": true,
  "limit": 100
}

Example 3: CRM Sender Sync

Retrieve all emails from a specific client and append them to the CRM contact timeline.

{
  "nodeType": "Gmail",
  "operation": "message/getMany",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "sender": "{{crm.contact.email}}",
  "simple": true,
  "returnAll": true
}