Workflow blocks
Gmail
Send, read, search, organize, and label Gmail messages and drafts
gmail — Send, read, search, organize, and label Gmail messages and drafts.
Where it appears
The Gmail block lives in the Integrations group of the Workflow Builder. Connect the Gmail integration before adding it.
Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
resource | select | Yes | message | Which Gmail resource to work with. Options: message, draft. |
operation | select | Yes | — | Which action to perform on the selected resource. |
to | text (supports references) | Yes | — | Recipient email address. Use literal text or <StepName.field> to reference an address from a previous step. |
cc | text (supports references) | No | — | Optional CC recipient address(es). Accepts literal text or <StepName.field>. |
bcc | text (supports references) | No | — | Optional BCC recipient address(es), hidden from other recipients. Accepts literal text or <StepName.field>. |
subject | text (supports references) | Yes | — | Subject line of the email. Use literal text or <StepName.field> to reference a value from a previous step. |
body | text (multi-line, supports references) | Yes | — | Body content of the email, interpreted according to the Content Type field. Use literal text or <StepName.field> to reference upstream content. |
contentType | select | No | text | How the body is sent: Plain Text or HTML. Choose HTML to send formatted markup. Options: text, html. |
messageId | text (supports references) | Yes | — | Gmail message ID to act on. Use a literal ID or <StepName.field> to reference an ID from a previous step (e.g. a search result). |
query | text (supports references) | Yes | — | Gmail search query using Gmail's search operators (e.g. in:inbox from:support@example.com). Use literal text or <StepName.field>. |
maxResults | number | No | 25 | Maximum number of matching messages to return. Defaults to 25. |
addLabelIds | text (supports references) | No | — | Comma-separated Gmail label IDs to add to the message (e.g. Label_123,IMPORTANT). Accepts literal text or <StepName.field>. |
removeLabelIds | text (supports references) | No | — | Comma-separated Gmail label IDs to remove from the message (e.g. INBOX to move it out of the inbox). Accepts literal text or <StepName.field>. |
labelIds | text (supports references) | Yes | — | Comma-separated Gmail label IDs to apply to or remove from the message (e.g. Label_123,IMPORTANT). Accepts literal text or <StepName.field>. |
Inputs and outputs
Inputs are the configurable fields above. The block produces these outputs:
Outputs
Reference an output downstream with <Gmail.field>.
| Name | Type | Description |
|---|---|---|
success | boolean | Operation succeeded |
messageId | string | Sent message ID |
threadId | string | Thread ID |
error | string | Error message if failed |
message | json | Email message object |
messages | array | Array of message IDs |
resultSizeEstimate | number | Estimated result count |
modified | boolean | Message was modified |
deleted | boolean | Message was deleted |
draftId | string | Draft ID |
Example
A minimal configuration for this block:
{
"type": "gmail",
"config": {
"resource": "message",
"operation": "...",
"to": "<PreviousStep.field>",
"subject": "<PreviousStep.field>",
"body": "<PreviousStep.field>",
"contentType": "text",
"messageId": "<PreviousStep.field>",
"query": "<PreviousStep.field>",
"maxResults": 25,
"labelIds": "<PreviousStep.field>"
}
}Limits and failure modes
- Requires a connected Gmail integration. Calls fail if that integration is disconnected or its authorization has expired.
- Required fields (
resource,operation,to,subject,body,messageId,query,labelIds) must be set, or the block fails validation before it runs. - On failure the
erroroutput is populated; downstream blocks that reference other outputs may not receive values.