> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/gmail.md). # Gmail Gmail is Google's email service for sending, receiving, and managing emails. * Knowledge base source ### Connectors Choose the connector that matches your authentication method. The options below use the names shown in StackAI. | Connector | Authentication | | --------- | -------------- | | Gmail | OAuth sign-in | #### Gmail Connect to Gmail to access emails and manage your inbox. Supports reading emails, searching, and analyzing email content. **Set up in Gmail** 1. Sign in to the Google account whose inbox you want to use. **Set up in StackAI** 1. Open **Settings → Connections**, add a connection, and select **Gmail**. 2. Select **Connect**, sign in to the provider account, and review the requested access. Complete authorization to return to StackAI. 3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it. StackAI obtains the OAuth credentials during sign-in. You do not need to paste an access token or refresh token. **Provider documentation:** [Setup reference](https://support.google.com/mail/answer/7126229). #### Verify the connection Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action. If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change. ### Use an action 1. Add the required **Gmail** action to the workflow. 2. Select a connection when the action requests one. 3. Complete the required fields. Use the reference picker when a value comes from another workflow step. 4. Run the workflow and inspect the action’s output. Check the result before using it in a later step. ### Actions #### Search Emails Search emails using the Gmail API **Permission alternatives** The connection must grant one of these sets of permissions: * `https://www.googleapis.com/auth/gmail.readonly` * `https://www.googleapis.com/auth/gmail.modify` * `https://www.googleapis.com/auth/gmail.metadata` **Inputs** | Field | Type | Required | Description | | ------------------------ | ------- | -------- | -------------------------------------------------------------------------- | | Search in Gmail | string | Yes | Use the same search you type in Gmail. | | Max Results | integer | No | Max emails to return. Default 25, max 500. Default: 25. | | Include Attachments | boolean | No | Whether to return downloadable links for email attachments. Default: true. | | Parse Attachments | boolean | No | Whether to also extract text content from attachments. Default: false. | | Extract Text from Images | boolean | No | Whether to use OCR to read text from image attachments. Default: false. | **Outputs** | Field | Type | Description | | ------ | ------------- | --------------------------------------- | | Emails | object\_array | The list of emails found in the search. | #### Send Email Send an email from Gmail **Permission alternatives** The connection must grant one of these sets of permissions: * `https://www.googleapis.com/auth/gmail.compose` * `https://www.googleapis.com/auth/gmail.modify` * `https://www.googleapis.com/auth/gmail.send` **Inputs** | Field | Type | Required | Description | | ------------------------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | To (recipient emails) | string | Yes | Email address(es) of the recipient(s), comma-separated. | | CC Recipient Email(s) | string | No | Email address(es) of the CC recipient(s), comma-separated. | | BCC Recipient Email(s) | string | No | Email address(es) of the BCC recipient(s), comma-separated. | | Email Subject | string | Yes | Subject line of the email. | | Email Content | string | Yes | Content/body of the email. | | Attachment URLs | string | No | URLs of files to attach (comma-separated). Use file URLs from previous workflow steps or external file hosting. | | Message format | select (string) | No | Choose 'Plain text' for simple emails or 'Rich text (HTML)' for formatted emails with styling. Available values: Plain text, Rich text (HTML). Default: text/plain. | | Email Signature | select (string) | No | Select a signature from your Gmail account to append to the email. Leave empty to send without a signature. Options load from the selected connection. Default: . | | Save as Draft | boolean | No | Save to Drafts folder instead of sending immediately. Default: false. | | Only send to these addresses (safety) | string | No | Safety feature: Only these addresses can receive emails. Others will be skipped. Leave empty to allow all recipients. | **Outputs** | Field | Type | Description | | -------------- | ------ | -------------------------------------------------------------- | | Result Message | string | A message indicating the success or failure of the email send. | #### Reply to Email Reply to an email conversation in Gmail **Permission alternatives** The connection must grant one of these sets of permissions: * `https://www.googleapis.com/auth/gmail.modify` * `https://www.googleapis.com/auth/gmail.readonly`, `https://www.googleapis.com/auth/gmail.compose` **Inputs** | Field | Type | Required | Description | | ------------------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Email Conversation | string | Yes | The conversation to reply to. Connect this to the 'thread\_id' output from the 'On Email Received' trigger. | | Reply Message | string | Yes | The content of your reply. | | Reply All | boolean | No | Reply to all recipients (To, CC) from the message being replied to. Uses the latest message in the thread, or the specific message if 'Reply to Specific Message' is set. When off, replies only to the sender. Default: false. | | Reply to Specific Message | string | No | Reply to a specific message in the conversation. Leave empty to reply to the most recent message (recommended for most cases). | | Override Recipients | string | No | Override the auto-detected recipients. Leave empty to reply to the original sender (or all recipients if Reply All is on). Note: If you specify someone not in the original conversation, they will receive this email but won't see previous messages in the thread. | | Content Type | select (string) | No | Format of the reply message. Available values: Text, HTML. Default: text/plain. | | Email Signature | select (string) | No | Select a signature from your Gmail account to append to the reply. Leave empty to send without a signature. Options load from the selected connection. Default: . | | Attachments | string | No | Comma-separated URLs of files to attach to the reply. Default: . | **Outputs** | Field | Type | Description | | ---------------- | ------------- | ------------------------------------------ | | Reply Message ID | string | The unique ID of the sent reply message. | | Thread ID | string | The ID of the email conversation. | | Recipients | string\_array | The email addresses the reply was sent to. | | Subject | string | The subject line of the reply. | | Result Message | string | A summary of the reply action. | #### List Labels List all labels in a Gmail account **Permission alternatives** The connection must grant one of these sets of permissions: * `https://www.googleapis.com/auth/gmail.labels` * `https://www.googleapis.com/auth/gmail.readonly` * `https://www.googleapis.com/auth/gmail.modify` * `https://www.googleapis.com/auth/gmail.metadata` **Inputs** No input fields are required in this catalog entry. **Outputs** | Field | Type | Description | | ------ | ------------- | ------------------------------------ | | Labels | object\_array | List of Gmail labels in the account. | #### Remove Label from Email Remove one or more labels from an email message **Permission alternatives** The connection must grant one of these sets of permissions: * `https://www.googleapis.com/auth/gmail.modify` **Inputs** | Field | Type | Required | Description | | --------------- | ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Email to update | string | Yes | The unique identifier of the email message to remove labels from. You can get this from the 'message\_id' output of 'On Email Received' trigger or 'Search Emails' action. | | Labels | multiple\_select (string) | Yes | Select one or more labels to remove from the email. To mark an email as read, remove the 'UNREAD' label. Options load from the selected connection. | **Outputs** | Field | Type | Description | | ---------------- | ------------- | ----------------------------------------------------------------------------------------------- | | Message ID | string | The ID of the message that was modified. | | Labels to Remove | string\_array | The label IDs that were requested to be removed. Labels not present on the message are ignored. | | All Labels | string\_array | All label IDs currently on the message after modification. | #### Add Label to Email Add one or more labels to an email message **Permission alternatives** The connection must grant one of these sets of permissions: * `https://www.googleapis.com/auth/gmail.modify` **Inputs** | Field | Type | Required | Description | | -------------- | ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Email to label | string | Yes | The unique identifier of the email message to add labels to. You can get this from the 'message\_id' output of 'On Email Received' trigger or 'Search Emails' action. | | Labels | multiple\_select (string) | Yes | Choose one or more labels (e.g., Important, Finance). Options load from the selected connection. | **Outputs** | Field | Type | Description | | ------------ | ------------- | ---------------------------------------------------------- | | Message ID | string | The ID of the message that was modified. | | Added Labels | string\_array | The label IDs that were added to the message. | | All Labels | string\_array | All label IDs currently on the message after modification. | #### Send and Wait for Response Send an email with approval/choice buttons and wait for the recipient to respond. **Permission alternatives** The connection must grant one of these sets of permissions: * `https://www.googleapis.com/auth/gmail.compose` * `https://www.googleapis.com/auth/gmail.modify` * `https://www.googleapis.com/auth/gmail.send` **Inputs** | Field | Type | Required | Description | | -------------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | To (recipient email) | string | Yes | Email address of the recipient who will respond. | | Email Subject | string | Yes | Subject line of the email. | | Message | textarea | Yes | The message content explaining what needs to be reviewed or approved. | | Message format | select (string) | No | Choose 'Plain text' for a simple message or 'Rich text (HTML)' to use links, bold text, lists and tables in the body. The response buttons are added automatically in both modes. Rich text is sent with its own styling intact, including style rules and images, so treat the body as trusted content: only scripts and non-image data links are stripped. Available values: Plain text, Rich text (HTML). Default: text/plain. | | Response Type | select (string) | No | The type of response expected: approval buttons or custom choices. Available values: Approval (Approve/Reject), Multiple Choice. Default: approval. | | Choices | array | No | List of choices when response\_type is 'choice'. Max 5 options. | | Approve Button Text | string | No | Custom text for the approve button (default: 'Approve'). | | Reject Button Text | string | No | Custom text for the reject button (default: 'Reject'). | **Outputs** | Field | Type | Description | | ------------- | ------ | ---------------------------------------------------- | | Recipient | string | The email address the message was sent to. | | Response Type | string | The type of response expected. | | Resume Output | dict | The recipient's response data when workflow resumes. | | Resume Token | string | Token to resume the workflow after user response. | | Message ID | string | The Gmail message ID of the sent email. | #### Create Draft Create a draft email in Gmail **Permission alternatives** The connection must grant one of these sets of permissions: * `https://www.googleapis.com/auth/gmail.compose` * `https://www.googleapis.com/auth/gmail.modify` **Inputs** | Field | Type | Required | Description | | ---------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | To (recipient emails) | string | No | Email address(es) of the recipient(s), comma-separated. | | CC Recipient Email(s) | string | No | Email address(es) of the CC recipient(s), comma-separated. | | BCC Recipient Email(s) | string | No | Email address(es) of the BCC recipient(s), comma-separated. | | Email Subject | string | Yes | Subject line of the email. | | Email Content | string | Yes | Content/body of the draft email. | | Message format | select (string) | No | Choose 'Plain text' for simple emails or 'Rich text (HTML)' for formatted emails with styling. Available values: Plain text, Rich text (HTML). Default: text/plain. | **Outputs** | Field | Type | Description | | -------------- | ------ | ------------------------------------------------ | | Draft ID | string | The unique ID of the created draft. | | Message ID | string | The unique ID of the draft message. | | Thread ID | string | The ID of the conversation the draft belongs to. | | Result Message | string | A summary of the draft creation. | #### Forward Email Forward an existing email to new recipients **Permission alternatives** The connection must grant one of these sets of permissions: * `https://www.googleapis.com/auth/gmail.modify` * `https://www.googleapis.com/auth/gmail.readonly`, `https://www.googleapis.com/auth/gmail.compose` **Inputs** | Field | Type | Required | Description | | --------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Email to forward | string | Yes | The unique identifier of the email message to forward. Get this from the 'message\_id' output of the 'On Email Received' trigger or 'Search Emails' action. | | To (recipient emails) | string | Yes | Email address(es) to forward the message to, comma-separated. | | CC Recipient Email(s) | string | No | Email address(es) of the CC recipient(s), comma-separated. | | Note | string | No | Optional message to add above the forwarded content. | **Outputs** | Field | Type | Description | | ---------- | ------------- | ------------------------------------------------------------ | | Message ID | string | The unique ID of the forwarded message that was sent. | | Thread ID | string | The ID of the conversation the forwarded message belongs to. | | Recipients | string\_array | The email addresses the message was forwarded to. | | Subject | string | The subject line of the forwarded message. | #### Create Label Create a new label in Gmail **Permission alternatives** The connection must grant one of these sets of permissions: * `https://www.googleapis.com/auth/gmail.labels` * `https://www.googleapis.com/auth/gmail.modify` **Inputs** | Field | Type | Required | Description | | ----------------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | Label Name | string | Yes | The name of the label to create. Use '/' to nest labels (e.g., 'Clients/Acme'). | | Label List Visibility | select (string) | No | Whether the label appears in the Gmail label list. Available values: Show, Show if unread, Hide. Default: labelShow. | | Message List Visibility | select (string) | No | Whether the label appears next to messages in the message list. Available values: Show, Hide. Default: show. | **Outputs** | Field | Type | Description | | ---------- | ------ | ------------------------------------------- | | Label ID | string | The unique identifier of the created label. | | Label Name | string | The display name of the created label. | #### Archive Email Archive an email by removing it from the inbox **Permission alternatives** The connection must grant one of these sets of permissions: * `https://www.googleapis.com/auth/gmail.modify` **Inputs** | Field | Type | Required | Description | | ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Email to archive | string | Yes | The unique identifier of the email message to archive (remove from the inbox). Get this from the 'message\_id' output of the 'On Email Received' trigger or 'Search Emails' action. | **Outputs** | Field | Type | Description | | ---------- | ------------- | ------------------------------------------------------- | | Message ID | string | The ID of the message that was archived. | | All Labels | string\_array | All label IDs currently on the message after archiving. | #### Delete Email Move an email to the trash **Permission alternatives** The connection must grant one of these sets of permissions: * `https://www.googleapis.com/auth/gmail.modify` **Inputs** | Field | Type | Required | Description | | --------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Email to delete | string | Yes | The unique identifier of the email message to move to the trash. Get this from the 'message\_id' output of the 'On Email Received' trigger or 'Search Emails' action. | **Outputs** | Field | Type | Description | | -------------- | ------ | -------------------------------------------------- | | Message ID | string | The ID of the message that was moved to the trash. | | Result Message | string | A summary of the trash action. | ### Triggers A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger. #### On Email Received Start this workflow whenever a new email arrives. **Required permissions:** `https://www.googleapis.com/auth/gmail.readonly`. **Configuration** | Field | Type | Required | Description | | ---------------- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Labels | multiple\_select (array) | No | Only trigger for emails with these labels. If you select multiple, emails matching ANY of them will trigger. Leave blank to trigger on all emails. Options load from the selected connection. | | Sender | string | No | Filter by sender. Use full emails () or domains (@acme.com) to match anyone from that company. Separate multiple with commas. | | Subject includes | string | No | Match emails where the subject contains any of the comma-separated values. | | Attachments | select (string) | No | Optionally filter emails by whether they include attachments. Available values: Any, Must have attachments, No attachments. Default: any. | | Check Frequency | select (string) | No | How often to check for new emails. Available values: Every minute, Every 5 minutes, Every 15 minutes, Every 30 minutes, Every hour. Default: every\_minute. | | Timezone | select (string) | No | Timezone for the polling schedule. Available values: PACIFIC TIME, MOUNTAIN TIME, CENTRAL TIME, EASTERN TIME, ATLANTIC TIME, UTC, LONDON, PARIS, BERLIN, MOSCOW, DUBAI, INDIA, SINGAPORE, TOKYO, SYDNEY, AUCKLAND. Default: UTC. | **Event inputs** | Field | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------------------------------------------------------- | | Sender | string | Yes | The email address of the sender of the email. | | Subject | string | Yes | The subject of the email. | | Body | string | Yes | The body of the email. | | Thread ID | string | No | ID of the email conversation. Pass this to Send Email to reply in the same thread. | | Message ID | string | No | The unique Gmail message ID for use with label and read actions. Default: . | | Email Date | string | No | The date and time from the email's Date header (sender-provided). Default: . | | Attachments | files | No | The actual attachment files, ready to use in other actions. | | Attachment URLs | string | No | Comma-separated list of email attachment download URLs stored in the data pool. | **Outputs** | Field | Type | Description | | --------------- | ------ | ---------------------------------------------------------------------------------- | | Sender | string | The email address of the sender of the email. | | Subject | string | The subject of the email. | | Body | string | The body of the email. | | Thread ID | string | ID of the email conversation. Pass this to Send Email to reply in the same thread. | | Message ID | string | The unique Gmail message ID for use with label and read actions. | | Email Date | string | The date and time from the email's Date header (sender-provided). | | Attachments | files | The actual attachment files, ready to use in other actions. | | Attachment URLs | string | Comma-separated list of email attachment download URLs stored in the data pool. | ### Important behavior If an operation is denied, check the connection’s granted permissions and the account’s access in the provider. Reauthorize the connection when it needs additional permissions. Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data. The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.stackai.com/integrations/catalog/gmail.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.