thread/getMany

List and filter Gmail threads using search queries, label filters, date ranges, and read status criteria.

When to Use

Unread conversation processing: Retrieve all unread threads in the inbox to process each conversation in a support routing workflow.
Client correspondence archive: Retrieve all threads from a specific sender to archive a complete email history before account closure.
Label-based thread batch processing: Get all threads with a "Needs-Review" label and route each to a human review queue.
Monthly conversation report: List all threads received in the current month for volume reporting and SLA analysis.
Multi-thread label operations: Retrieve threads matching criteria and apply a new label to all of them via a Loop + thread/addLabel workflow.

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 threads (ignores `limit`).
`limit`	int optional	`50`	Maximum number of threads to return.
`simple`	bool optional	`true`	When `true`, returns simplified thread objects with message summaries. When `false`, includes full message bodies.
`labelIds`	string[] optional	—	Filter threads that have ALL of the specified label IDs.
`includeSpamTrash`	bool optional	`false`	When `true`, includes threads from Spam and Trash in results.
`filterQ`	string optional	—	Gmail search query string. Supports full Gmail query syntax.
`readStatus`	enum optional	—	Filter by status: `read` or `unread`.
`receivedAfter`	string optional	—	ISO date — only threads with messages received after this date.
`receivedBefore`	string optional	—	ISO date — only threads with messages received before this date.
`sender`	string optional	—	Filter by sender email address.

Sample Configuration

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

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 query in Gmail web UI first
`INVALID_DATE`	Date string is not parseable	Use ISO format: `YYYY-MM-DD`
`QUOTA_EXCEEDED`	Gmail API quota exhausted	Reduce list frequency; implement backoff

Output

Success Port

Field	Type	Description
`threads`	array	Array of thread objects
`threads[].threadId`	string	Gmail thread ID
`threads[].historyId`	string	Thread history ID
`threads[].snippet`	string	Preview of the most recent message
`threads[].messages`	array	Array of message summary objects in the thread
`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

{
  "threads": [
    {
      "threadId": "18e4a2f9d3c0b1a7",
      "historyId": "1234567",
      "snippet": "We'd like to move forward with the proposal...",
      "messages": [
        { "messageId": "18e4a2f9d3c0b1a7", "from": "client@example.com", "subject": "Re: Proposal", "date": "Mon, 15 Jan 2024 09:34:12 +0000" }
      ]
    }
  ],
  "status": "success",
  "errorCode": ""
}

Expression Reference

Expression	Resolves To	Example Use
`{{threadList.threads}}`	Array of thread objects	Loop node input
`{{threadList.threads[0].threadId}}`	First thread's ID	Pass to thread/get for full content
`{{$now \| dateFormat:'YYYY-MM-01'}}`	First day of current month	`receivedAfter` for monthly report

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 date filters and reasonable limits
Quota Management	Thread list costs 5 quota units per call — plan batch sizes carefully for high-volume workflows
PII Protection	Do not log thread arrays in workflow execution history — they contain email content with PII
Query Validation	Test `filterQ` queries in Gmail web UI before deploying automated thread workflows
Test Isolation	Test thread listing workflows against a dedicated Gmail test account

Examples

Example 1: Unread Support Thread Processing

Scheduled trigger retrieves all unread inbox threads hourly for support routing.

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

Example 2: Client Correspondence Archive

Retrieve all threads from a departing client for archival before account closure.

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

Example 3: Monthly Conversation Report

List all threads from the current month for SLA and volume analytics.

{
  "nodeType": "Gmail",
  "operation": "thread/getMany",
  "credentialId": "a3f9d12b-44e1-4c89-b7d2-9f0a1e2b3c4d",
  "receivedAfter": "{{$now | dateFormat:'YYYY-MM-01'}}",
  "receivedBefore": "{{$now | dateFormat:'YYYY-MM-DD'}}",
  "returnAll": true
}