Gmail — Input & Output

Output Ports

Port	Trigger	Description
success	Operation completed successfully	Gmail API returned a 2xx response. Output data is available on this port.
error	API error or network failure	The Gmail API returned an error, the OAuth2 token was invalid or expired, or a network fault occurred. Error details are in the error output object.

message — Output Schemas

message/send and message/reply — Output

Field	Type	Description
`id`	string	Gmail message ID of the sent or replied message.
`threadId`	string	Thread ID this message belongs to. For new sends, this is a new thread. For replies, it matches the original thread.
`labelIds`	string[]	Labels applied to the sent message, typically `["SENT"]`.

{
  "id": "18f3c2b4a5d6e789",
  "threadId": "18f3c2b4a5d6e789",
  "labelIds": ["SENT"]
}

message/get — Output (Simplified: true)

Field	Type	Description
`id`	string	Gmail message ID.
`threadId`	string	Thread this message belongs to.
`labelIds`	string[]	Labels currently applied to the message.
`from`	string	Sender email address and display name (e.g. `"Acme Corp <billing@acme.com>"`).
`to`	string	Primary recipient(s).
`subject`	string	Email subject line.
`date`	string	Message date in RFC 2822 format.
`snippet`	string	Short text preview as shown in the Gmail message list.
`bodyText`	string	Decoded plain text body.
`bodyHtml`	string	Decoded HTML body, if present.
`attachments`	object[]	Attachment metadata. See attachment schema below. Binary data present when `DownloadAttachments: true`.

{
  "id": "18c1f2e3d4c5b6a7",
  "threadId": "18c1f2e3d4c5b6a7",
  "labelIds": ["INBOX", "UNREAD"],
  "from": "supplier@vendorcorp.com",
  "to": "accounts@mycompany.com",
  "subject": "Invoice #INV-2026-0312",
  "date": "Fri, 23 May 2026 09:15:03 +0000",
  "snippet": "Please find attached invoice #INV-2026-0312...",
  "bodyText": "Please find attached invoice #INV-2026-0312 for services rendered in April 2026. Amount: $4,250.00.",
  "bodyHtml": "<p>Please find attached invoice...</p>",
  "attachments": [
    {
      "attachmentId": "ANGjdJ8Kx2aP...",
      "filename": "Invoice_INV-2026-0312.pdf",
      "mimeType": "application/pdf",
      "size": 87432
    }
  ]
}

message/getMany — Output

Field	Type	Description
`messages`	object[]	Array of message objects. Each entry has the same schema as `message/get` output when `Simplified: true`.
`nextPageToken`	string	Pagination token for the next page of results. Empty when all results have been returned.
`resultSizeEstimate`	integer	Estimated total number of matching messages.

message/delete, message/trash, message/untrash, message/markAsRead, message/markAsUnread — Output

Field	Type	Description
`success`	boolean	`true` when the operation completed without error.
`id`	string	The message ID that was acted upon.

message/addLabel — Output

Field	Type	Description
`id`	string	The message ID.
`threadId`	string	The thread ID.
`labelIds`	string[]	Updated full list of label IDs on the message after the operation.

draft — Output Schemas

draft/create — Output

Field	Type	Description
`id`	string	Gmail draft ID for the newly created draft.
`message`	object	The draft message object, containing `id`, `threadId`, and `labelIds`.

{
  "id": "r-7894561230abcdef",
  "message": {
    "id": "18f4a1b2c3d4e567",
    "threadId": "18f4a1b2c3d4e567",
    "labelIds": ["DRAFT"]
  }
}

draft/get — Output

Field	Type	Description
`id`	string	Draft ID.
`message`	object	Full message object for the draft, same schema as `message/get` with `Simplified: true`.

draft/getMany — Output

Field	Type	Description
`drafts`	object[]	Array of draft objects, each with `id` and `message` fields.
`nextPageToken`	string	Pagination token.
`resultSizeEstimate`	integer	Estimated total number of drafts.

label — Output Schemas

label/create and label/get — Output

Field	Type	Description
`id`	string	Gmail label ID (e.g. `"Label_5823947123"` for custom labels).
`name`	string	Label display name.
`labelListVisibility`	string	`"labelShow"` or `"labelHide"`.
`messageListVisibility`	string	`"show"` or `"hide"`.
`messagesTotal`	integer	Total messages with this label (present on `label/get`).
`messagesUnread`	integer	Unread message count for this label (present on `label/get`).

label/getMany — Output

Field	Type	Description
`labels`	object[]	Array of label objects, each with `id`, `name`, and visibility fields.

thread — Output Schemas

thread/get — Output (Simplified: true)

Field	Type	Description
`id`	string	Gmail thread ID.
`snippet`	string	Snippet from the most recent message in the thread.
`historyId`	string	Gmail history ID for change tracking.
`messages`	object[]	Array of simplified message objects in the thread, ordered oldest to newest.

thread/reply — Output

Same schema as message/send — returns id, threadId, and labelIds for the reply message.

thread/addLabel and thread/removeLabel — Output

Field	Type	Description
`id`	string	Thread ID.
`historyId`	string	Updated history ID after label modification.

Attachment Object Schema

Present in message/get, message/getMany, draft/get, and the Gmail Trigger when DownloadAttachments: true.

Field	Type	Description
`attachmentId`	string	Gmail attachment ID. Used to fetch attachment data via the Gmail API if not downloaded inline.
`filename`	string	Original filename of the attachment.
`mimeType`	string	MIME type (e.g. `"application/pdf"`, `"image/png"`).
`size`	integer	File size in bytes.

When DownloadAttachments: true, each attachment's binary data is mapped to a separate binary field named {AttachmentPrefix}{index} (e.g. attachment_0, attachment_1).

Error Codes

HTTP Status	Cause	Resolution
`401`	OAuth2 token expired or revoked	Re-authorise the credential in BizFirst Credentials Manager and ensure the OAuth2 consent includes Gmail access.
`403`	Insufficient Gmail API scope or quota exceeded	Verify the credential has full Gmail access. Check the Google Cloud Console for quota usage on the Gmail API.
`404`	MessageId, ThreadId, DraftId, or LabelId not found	Confirm the ID is valid and belongs to the authenticated account. IDs from other accounts will return 404.
`429`	Gmail API rate limit exceeded	Reduce concurrent Gmail node executions. Add a Delay node between bulk operations.
`500`	Gmail API internal error	Transient error. Retry the operation. If persistent, check Google Workspace Status Dashboard.

Referencing Output in Downstream Nodes

If a Gmail node is named fetchEmail, reference its output fields using the following patterns:

Value Needed	Expression
Message ID	`{{ nodes.fetchEmail.output.id }}`
Thread ID	`{{ nodes.fetchEmail.output.threadId }}`
Sender address	`{{ nodes.fetchEmail.output.from }}`
Subject line	`{{ nodes.fetchEmail.output.subject }}`
Plain text body	`{{ nodes.fetchEmail.output.bodyText }}`
HTML body	`{{ nodes.fetchEmail.output.bodyHtml }}`
First attachment filename	`{{ nodes.fetchEmail.output.attachments[0].filename }}`
Label list from message/send	`{{ nodes.sendEmail.output.labelIds }}`
Draft ID	`{{ nodes.createDraft.output.id }}`
Custom label ID	`{{ nodes.listLabels.output.labels[0].id }}`

Thread ID reuse: When chaining a message/get or message/getMany with a subsequent thread/reply, pass {{ nodes.getMsg.output.threadId }} as the ThreadId for the reply operation to maintain conversation continuity.