> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.airweave.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airweave.ai/_mcp/server. # Gmail > Gmail integration with Airweave {/* AUTO-GENERATED CONTENT START */} Gmail logo

Gmail

This connector enables AI agents and RAG systems to retrieve context from Gmail through Airweave's unified search layer. ## Configuration Gmail source connector integrates with the Gmail API to extract and synchronize email data. Connects to your Gmail account. It supports syncing email threads, individual messages, and file attachments. #### [View Source Code](https://github.com/airweave-ai/airweave/tree/main/backend/airweave/platform/sources/gmail.py) Explore the Gmail connector implementation ### Authentication This connector uses **OAuth 2.0 with custom credentials**. You need to provide your OAuth application's Client ID and Client Secret, then complete the OAuth consent flow. #### OAuth Setup Required 1. Create an OAuth application in your provider's developer console 2. Enter your Client ID and Client Secret when configuring the connection 3. Complete the OAuth consent flow ### Configuration Options This connector does not have any additional configuration options. ## Data Models The following data models are available for this connector: #### GmailThreadEntity Schema for Gmail thread entities. Reference: [https://developers.google.com/gmail/api/reference/rest/v1/users.threads](https://developers.google.com/gmail/api/reference/rest/v1/users.threads) | Field | Type | Description | | ----------------- | ------------------- | -------------------------------------------------- | | thread\_key | str | Stable Airweave thread key (thread\_\) | | gmail\_thread\_id | str | Native Gmail thread ID | | title | str | Display title derived from snippet | | last\_message\_at | Optional\[datetime] | Timestamp of the most recent message in the thread | | snippet | Optional\[str] | A short snippet from the thread | | history\_id | Optional\[str] | The thread's history ID | | message\_count | Optional\[int] | Number of messages in the thread | | label\_ids | List\[str] | Labels applied to this thread | #### GmailMessageEntity Schema for Gmail message entities. Reference: [https://developers.google.com/gmail/api/reference/rest/v1/users.messages](https://developers.google.com/gmail/api/reference/rest/v1/users.messages) | Field | Type | Description | | ------------------- | ------------------- | ---------------------------------------------------------- | | message\_key | str | Stable Airweave message key (msg\_\) | | message\_id | str | Native Gmail message ID | | subject | str | Subject line (fallback applied if missing) | | sent\_at | datetime | Timestamp from the Date header (or internal date fallback) | | internal\_timestamp | datetime | Gmail internal timestamp representing last modification | | thread\_id | str | ID of the thread this message belongs to | | sender | Optional\[str] | Email address of the sender | | to | List\[str] | Recipients of the message | | cc | List\[str] | CC recipients | | bcc | List\[str] | BCC recipients | | date | Optional\[datetime] | Date the message was sent | | snippet | Optional\[str] | Brief snippet of the message content | | label\_ids | List\[str] | Labels applied to this message | | internal\_date | Optional\[datetime] | Internal Gmail timestamp | | web\_url\_value | Optional\[str] | Direct Gmail URL for the message | #### GmailAttachmentEntity Schema for Gmail attachment entities. Reference: [https://developers.google.com/gmail/api/reference/rest/v1/users.messages.attachments](https://developers.google.com/gmail/api/reference/rest/v1/users.messages.attachments) | Field | Type | Description | | --------------- | -------------- | ---------------------------------------------------------------- | | attachment\_key | str | Stable Airweave attachment key (attach\_\\_\) | | filename | str | Attachment filename | | message\_id | str | ID of the message this attachment belongs to | | attachment\_id | str | Gmail's attachment ID | | thread\_id | str | ID of the thread containing the message | | web\_url\_value | Optional\[str] | URL to view the parent message in Gmail | #### GmailMessageDeletionEntity Deletion signal for a Gmail message. Emitted when the Gmail History API reports a messageDeleted. The entity\_id matches the message entity's ID format (msg\_\{message\_id}) so downstream deletion removes the correct parent/children. | Field | Type | Description | | ------------ | -------------- | ----------------------------------------------------- | | message\_key | str | Stable Airweave message key (msg\_\) | | label | str | Human-readable deletion label | | message\_id | str | The Gmail message ID that was deleted | | thread\_id | Optional\[str] | Thread ID (optional if not provided by change record) | {/* AUTO-GENERATED CONTENT END */} ## Integrate Airweave with Google APIs on localhost This guide will walk you through connecting Google Workspace APIs to Airweave when running locally. Google provides extensive [documentation](https://developers.google.com/workspace/guides/get-started) on setting up your workspace. Below is a streamlined process for connecting Google APIs to Airweave. 1. [Create a Google Cloud project](https://developers.google.com/workspace/guides/create-project) for your Google Workspace (if you don't already have one) 2. [Enable the Google Workspace APIs](https://developers.google.com/workspace/guides/enable-apis) for Gmail, Google Calendar, and Google Drive 3. [Configure Google OAuth 2.0 consent screen](https://developers.google.com/workspace/guides/configure-oauth-consent) 4. Under `Audience`, select `Make external` and add test users 5. Under `Data Access`, add the following scopes: ``` https://www.googleapis.com/auth/docs https://www.googleapis.com/auth/drive.photos.readonly https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/drive.metadata https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/calendar.events.public.readonly https://www.googleapis.com/auth/calendar.freebusy https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.calendars.readonly https://www.googleapis.com/auth/calendar.events.owned.readonly https://www.googleapis.com/auth/calendar.events.readonly ``` 6. [Create OAuth client ID credentials](https://developers.google.com/workspace/guides/create-credentials#oauth-client-id) 7. Under "Authorized redirect URIs," click "+ Add URI" and add the Redirect URI. Use the appropriate URL for your environment: **Production (Airweave Cloud):** ``` https://api.airweave.ai/source-connections/callback ``` **Local:** ``` http://localhost:8001/source-connections/callback ``` 8. Locate the client ID and client secret from your newly created OAuth client. Add these credentials to the `dev.integrations.yml` file to enable Google API integration.