Skip to content

Docs/Connectors

Gmail

Email in one Gmail or Google Workspace mailbox as message records and thread episodes. Attachment contents are never read.

The gmail connector reads one mailbox: who wrote to whom, when, the subject and the body text, and how each thread went. The mailbox owner authorizes it themself.

Connector name gmail
Products Records, episodes
Credentials A Google OAuth client and a refresh token from the mailbox owner
Scope https://www.googleapis.com/auth/gmail.readonly
Status Preview: tested against Google's documented responses, not yet on a live account

What it reads

Object Contents
email_message Thread and message ids, sent time, sender, to and cc addresses, subject, body as plain text, system labels, attachment count and file types, reply and forward flags, position in the thread
email_participant One row per sender and recipient of each message: role, name and address

Bodies are converted from HTML when there is no plain text part, and the quoted history below "On ... wrote:" or a forwarded message marker is cut, so each message is sent once. Bodies longer than maxBodyLength characters are cut.

Episodes. One per thread: each message in order, as sent, replied or forwarded, by its sender.

Every name and address is cleaned on your computer before anything is sent. Each participant's name and address is learned by the scrubber, so a name in a body or a signature is replaced too, and the run stops before upload if one survives.

What it never reads

  • Attachment contents. Only the count and file types are sent; file names are not.
  • Messages with an excluded label. By default: CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, SPAM, TRASH, DRAFT and CHAT.
  • Names of labels you created. Only their count is sent.
  • Bcc recipients as a column. They are learned by the scrubber and sent only as cleaned participant rows.

Setup

  1. In Google Cloud Console, enable the Gmail API and create an OAuth client of type Web application or Desktop.
  2. Have the mailbox owner sign in once with the gmail.readonly scope and offline access, and keep the refresh token.
  3. Connect:
bash
datayield connect gmail -o clientId=<client id> -o clientSecret=env:GOOGLE_CLIENT_SECRET -o refreshToken=env:GMAIL_REFRESH_TOKEN

Add one source per mailbox. Reading many mailboxes through Google Workspace domain-wide delegation is not supported yet.

Options

Option Required Meaning
clientId, clientSecret, refreshToken yes, or accessToken The OAuth client and the owner's refresh token. Stored as secrets.
accessToken instead of the above A current access token, for a one-off run
excludeLabels no Label ids or names never read. Replaces the default list. Add CATEGORY_PERSONAL to leave out the Primary tab.
includeLabels no Read only messages with one of these labels
excludeDomains no Skip a message when anyone on it has an address at one of these domains
excludePersonalDomains no Also skip messages with anyone at gmail.com, outlook.com and similar. Default false.
maxBodyLength no Longest body sent, in characters. Default 20000.

New records on each run

Each run asks Gmail for threads with mail since the last successful run and keeps the messages sent inside the window. Gmail's per-user rate limits are retried with backoff.