Gmail connector

The Gmail connector connects to the Gmail API and enables search, read, label, quarantine, and send operations on Gmail mailboxes.

You can use this connector in Agent Builder and Workflows.

You can create a Gmail connector in Stack Management > Connectors or when adding a Gmail data source.

Gmail connectors support the following authentication types:

Quick Connect OAuth 2.0 (recommended, read-only) Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

Elastic's managed OAuth flow for Gmail. Grants gmail.readonly access only. Write actions are not available with this authentication type. No app setup is required — select this option and authorize access through Elastic. Refer to Quick Connect OAuth 2.0.

OAuth 2.0 authorization code (required for write actions)

Uses your own Google OAuth 2.0 app. Grants gmail.modify access, which covers reads, label changes, trash, and send. Required for modifyLabels, trashMessage, untrashMessage, sendMessage, replyMessage, markAsRead, and markAsUnread. See Get API credentials for setup instructions.

You can test connectors when creating or editing the connector in Kibana. The test verifies connectivity by fetching the authenticated user's profile from the Gmail API.

Search for messages using Gmail search syntax.

query

(Optional) Gmail search query using operators such as from:, to:, subject:, is:unread, after:YYYY/MM/DD, newer_than:Nd. Prefer narrow queries to keep responses small.

maxResults

(Optional) Number of message IDs to return. Default 10, capped at 100.

pageToken

(Optional) Pagination cursor from a previous response.

List message IDs, optionally filtered by label.

maxResults

(Optional) Number of message IDs to return. Default 10, capped at 100.

pageToken

(Optional) Pagination cursor from a previous response.

labelIds

(Optional) Filter by label IDs, for example ["INBOX"] or ["SENT"].

Retrieve a single message by ID.

messageId

(Required) Gmail message ID from searchMessages or listMessages.

format

(Optional) minimal for headers only (default), full for body and attachment metadata, raw for RFC 2822 format.

Retrieve an attachment by message ID and attachment ID. Call getMessage with format: "full" first to get attachment IDs from payload.parts[].body.attachmentId.

messageId

(Required) Gmail message ID.

attachmentId

(Required) Attachment ID from the message's payload.parts[].body.attachmentId.

List all Gmail labels (system and user-created) with their IDs and names. Call this before modifyLabels to resolve a label name (for example, "Quarantine") to its ID.

Remove the UNREAD label from a message. Reversible with markAsUnread. Requires OAuth 2.0 authorization code auth.

messageId

(Required) Gmail message ID.

Add the UNREAD label to a message. Reversible with markAsRead. Requires OAuth 2.0 authorization code auth.

messageId

(Required) Gmail message ID.

Add or remove labels on a message. The quarantine primitive: pass the quarantine label ID in addLabelIds and ["INBOX"] in removeLabelIds to move a message out of the inbox. Requires OAuth 2.0 authorization code auth.

messageId

(Required) Gmail message ID.

addLabelIds

(Optional) Label IDs to add. Call listLabels to resolve a name to an ID.

removeLabelIds

(Optional) Label IDs to remove. At least one of addLabelIds or removeLabelIds is required.

Move a message to Trash. Reversible with untrashMessage within 30 days. Requires OAuth 2.0 authorization code auth.

messageId

(Required) Gmail message ID.

Restore a message from Trash. Rolls back a trashMessage call. Only effective within 30 days of trashing. Requires OAuth 2.0 authorization code auth.

messageId

(Required) Gmail message ID.

Send an email from the authenticated user's Gmail account. Irreversible once accepted by the receiving mail server. Supports plain-text and HTML bodies, bare addr-spec recipients only, and no attachments in v1. Available in Workflows only. Requires OAuth 2.0 authorization code auth.

to

(Required) Recipient email addresses (bare addr-spec, for example ["user@example.com"]).

subject

(Required) Email subject line.

body

(Required) Email body content.

bodyType

(Optional) "text" (default) or "html".

cc

(Optional) CC recipient addresses.

bcc

(Optional) BCC recipient addresses.

Send a reply to an existing message, preserving the thread. The connector fetches the original message to set threading headers and determine the default recipient from Reply-To or From. Available in Workflows only. Requires OAuth 2.0 authorization code auth.

messageId

(Required) Gmail message ID to reply to.

body

(Required) Reply body content.

bodyType

(Optional) "text" (default) or "html".

subject

(Optional) Override the reply subject. Defaults to Re: <original subject>.

to

(Optional) Override recipient addresses. Defaults to the Reply-To or From address of the original message.

• Write actions require OAuth 2.0 authorization code auth. Quick Connect OAuth 2.0 is limited to gmail.readonly. The modifyLabels, trashMessage, untrashMessage, sendMessage, replyMessage, markAsRead, and markAsUnread actions are not available with Quick Connect OAuth 2.0.
• Existing connectors must be re-authorized. Google does not re-prompt for consent when the requested scope changes. If you created a Gmail connector before write action support was added, edit the connector and re-authorize it so Google issues a token that includes gmail.modify.
• Permanent deletion is not supported. Use trashMessage (reversible with untrashMessage). Gmail permanently removes trashed mail after 30 days.
• No attachments in sendMessage v1. Attachment support is planned for a future release.

Use the Action configuration settings to customize connector networking, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use xpack.actions.customHostSettings to set per-host configurations.

No setup required. Select Quick Connect OAuth 2.0 when you create the connector in Kibana and follow the authorization prompt to grant Elastic read-only access to your Gmail. Your Google Workspace administrator might need to approve the Elastic app. Refer to Quick Connect OAuth 2.0.

To use write actions, create a Google OAuth 2.0 app and authorize it with the gmail.modify scope:

1. Go to the Google Cloud Console and create or select a project.
2. Enable the Gmail API for the project.
3. Under APIs & Services → Credentials, create an OAuth 2.0 client ID of type Web application. Add your Kibana instance URL as an authorized redirect URI.
4. Note the Client ID and Client Secret.
5. When creating the Gmail connector in Kibana, select OAuth 2.0 authorization code, enter the client ID and secret, and authorize the connector. Google will prompt you to grant gmail.modify access.