Gmail

Text

The Gmail connector is a text connector that fetches email threads via the Gmail REST API and extracts claims from message bodies using db.ingest_text().

How it works

Fetches email threads matching an optional Gmail search query via the Gmail REST API
Recursively extracts text/plain content from MIME payloads
Concatenates all messages in a thread with newline separators
Passes concatenated thread text to db.ingest_text() for claim extraction
Rate limited with a 0.1s sleep between API calls

1 Create OAuth Credentials

Go to the Google Cloud Console and create OAuth 2.0 credentials for your project.

2 Enable the Gmail API

In the API Library, search for Gmail API and enable it for your project.

3 Configure OAuth Scopes

The connector requires the following scope:

https://www.googleapis.com/auth/gmail.readonly — read-only access to email messages and threads

4 Obtain an Access Token

Complete the OAuth2 flow to obtain an access token (starts with ya29.). The token must be a valid Google OAuth2 access token with the Gmail read scope.

5 Install the requests package

$ pip install requests

6 Connect

conn = db.connect("gmail", token="ya29.a0...")
result = conn.run(db)

Parameter	Required	Default	Description
`token`	Yes	—	Google OAuth2 access token (`ya29....`)
`query`	No	`""`	Gmail search query (e.g. `"label:inbox"`)
`max_results`	No	`100`	Maximum number of threads to fetch
`save`	No	`False`	Encrypt and persist token

Note: In db.connect(), the access_token parameter is passed as token.

Basic usage

conn = db.connect("gmail", token="ya29.a0...")
result = conn.run(db)

With query filter

conn = db.connect("gmail",
    token="ya29.a0...",
    query="label:inbox newer_than:7d",
    max_results=50,
)
result = conn.run(db)

With save

conn = db.connect("gmail",
    token=os.environ["GMAIL_TOKEN"],
    query="from:team@company.com",
    save=True,
)
result = conn.run(db)