Gmail

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.

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

Create an OAuth application in your provider’s developer console
Enter your Client ID and Client Secret when configuring the connection
Complete the OAuth consent flow

Configuration Options

The following configuration options are available for this connector:

Configuration Parameters

Gmail configuration schema.

after_date

Optional[str]Required

Sync emails after this date (format: YYYY/MM/DD or YYYY-MM-DD).

included_labels

list[str]Defaults to []

Labels to include (e.g., ‘inbox’, ‘sent’, ‘important’). Defaults to inbox and sent.

excluded_labels

list[str]Defaults to []

Labels to exclude (e.g., ‘spam’, ‘trash’, ‘promotions’, ‘social’). Defaults to spam and trash.

excluded_categories

list[str]Defaults to []

Gmail categories to exclude (e.g., ‘promotions’, ‘social’, ‘updates’, ‘forums’).

gmail_query

Optional[str]Required

Advanced. Custom Gmail query string (overrides all other filters if provided).

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

Field	Type	Description
thread_key	str	Stable Airweave thread key (thread_<gmail_id>)
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

Field	Type	Description
message_key	str	Stable Airweave message key (msg_<gmail_id>)
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

Field	Type	Description
attachment_key	str	Stable Airweave attachment key (attach_<message>_<filename>)
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_<gmail_id>)
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)

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 on setting up your workspace. Below is a streamlined process for connecting Google APIs to Airweave.

Create a Google Cloud project for your Google Workspace (if you don’t already have one)
Enable the Google Workspace APIs for Gmail, Google Calendar, and Google Drive
Configure Google OAuth 2.0 consent screen
Under Audience, select Make external and add test users
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

Create OAuth client ID credentials

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

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.