Portal Community
Portal / Nodes / Gmail

Gmail Node

Automate email workflows in Google Gmail — send, read, organize, and manage messages, drafts, labels, and threads using OAuth2 authentication.

Authentication: All operations require a credentialId referencing a stored OAuth2 credential in the BizFirst Credentials Manager. OAuth tokens are never exposed in workflow configuration. The required Gmail API scope varies by operation: gmail.send, gmail.modify, or gmail.readonly.

Resources

Message

10 operations
send reply get getMany delete trash untrash markAsRead markAsUnread addLabel

Draft

4 operations
create get getMany delete

Label

4 operations
create get getMany delete

Thread

8 operations
get getMany delete trash untrash addLabel removeLabel reply

Authentication

All Gmail node operations authenticate via OAuth2. Credentials are stored in the BizFirst Credentials Manager and referenced by a credentialId (Guid). Never expose raw tokens in workflow configuration.

FieldTypeDescription
credentialIdGuid requiredID of the stored Gmail OAuth2 credential in the BizFirst Credentials Manager.
OAuth ScopeUsed By
https://www.googleapis.com/auth/gmail.sendmessage/send, message/reply, draft operations, thread/reply
https://www.googleapis.com/auth/gmail.modifymessage/trash, message/untrash, message/markAsRead, message/markAsUnread, message/addLabel, message/delete, label CRUD, thread label ops
https://www.googleapis.com/auth/gmail.readonlymessage/get, message/getMany, draft/get, draft/getMany, label/get, label/getMany, thread/get, thread/getMany

Gmail API Rate Limits

OperationQuota UnitsNotes
Global limit250 units/user/secondApplies across all Gmail API calls
messages.send100 unitsPersonal: 500/day; Workspace: 2,000/day
messages.get5 unitsPer message fetch
messages.list5 unitsPer list request, regardless of page size
labels.*1 unitCheap — safe for frequent use
threads.*5–10 unitsVaries by operation type
Daily Send Limits: Personal Gmail accounts are limited to 500 messages/day. Google Workspace accounts allow up to 2,000 messages/day. Design automated send workflows with throttling to stay within limits.

Gmail Search Query Syntax

filterQ field: Operations that support filterQ accept Gmail's full search query syntax. Test queries in the Gmail web UI before using in automation.
OperatorExampleDescription
from:from:client@example.comFilter by sender
to:to:support@myco.comFilter by recipient
subject:subject:InvoiceFilter by subject line
has:attachmenthas:attachmentOnly messages with attachments
after:after:2024/01/01Messages received after date
before:before:2024/12/31Messages received before date
label:label:INBOXFilter by label name
is:unreadis:unreadOnly unread messages
is:starredis:starredOnly starred messages
Combinationfrom:vendor@co.com subject:Invoice after:2024/06/01Multiple operators are ANDed

Node Policies & GuardRails

PolicyRule
Credential StorageStore OAuth credentials in BizFirst Credentials Manager — never hardcode tokens in workflow configuration
API Quota ManagementGmail API enforces 250 units/user/second — batch multiple list operations carefully and implement backoff on 429 responses
Recoverable DeletionUse message/trash instead of message/delete for recoverable deletion; delete only after legal/GDPR confirmation
PII ProtectionDo not log email bodies in workflow execution history — email content contains PII and may violate data protection regulations
Send Rate LimitingThrottle automated send operations — Gmail enforces 500 messages/day for personal accounts, 2,000/day for Google Workspace
Test IsolationTest all Gmail workflows in a dedicated test account before connecting a production inbox
Query ValidationValidate filterQ search queries in the Gmail web UI before deploying automated workflows

Common Use Case Patterns