OpenCoreDocuments & KnowledgeGmail

Gmail Overview

View as Markdown

The Gmail connector indexes approved email conversations as OpenCore knowledge. An Admin creates and maintains the Google credential, selects it when creating the connector, and verifies the indexed result before attaching its document set to an Agent.

What the connector indexes

Each Gmail thread becomes one document. The first available subject is its title, and each message contributes a section linked to the thread in Gmail.

DataCurrent behavior
Message contentDecodes text/plain MIME parts from each message in the thread. HTML and non-text attachment payloads are ignored; a text/plain attachment part is not distinguished from body text.
HeadersIncludes the subject and the From, To, Cc, and Bcc values in the indexed text. Message dates become document timestamps when they can be parsed.
OwnershipRecords senders as primary owners and other message participants as secondary owners.
Size safetySkips an individual plain-text part when its estimated decoded size exceeds 10 MB. Other usable parts in the thread can still be indexed.
Time windowUses the connector’s indexing start and polling window to query threads by Gmail time range.

The connector does not expose Drive-style file, folder, or shared-drive filters. Gmail coverage is determined by the mailbox accounts available through the selected credential.

Choose an authentication method

MethodUse it whenAccount boundary
OAuth appAn authorized person can complete browser consent with the Google account whose Gmail should be indexed.OpenCore saves the authorized Gmail profile as the primary account. OAuth reads only the authorized account’s mailbox. Listing Workspace users does not let an OAuth credential impersonate them; domain-wide mailbox coverage requires a Service Account with Domain-Wide Delegation.
Service AccountA Google Workspace organization manages mailbox access with Domain-Wide Delegation.The Service Account uses the configured Primary Admin Email to list every Workspace user returned by the Admin SDK, then impersonates each mailbox user. If directory listing is unavailable, the connector falls back to the configured primary account.

Both methods request the Gmail read-only scope plus read-only Workspace user and group directory scopes. Choose the method that matches how your organization administers Google access; do not use a Service Account for a personal Gmail mailbox.

Mailbox permissions and synchronization

For each indexed thread, OpenCore records a non-public external-access entry for the mailbox address used to fetch it. The Gmail connector does not add Google group IDs to that entry and does not turn a thread into public content.

When the deployment runs Gmail permission synchronization, it revisits slim thread records in the synchronization time window and updates the external-access record for each returned thread. This path preserves the same mailbox-only, non-public boundary; it does not infer broader visibility from message recipients or Workspace groups.

Updates and multiple credentials

The connector creation form defaults to pulling new content every 30 minutes. An Admin can choose another refresh frequency of at least one minute and can set an indexing start date to bound the initial historical query. Source changes appear only after a later successful index attempt.

Creating a second Gmail credential preserves existing Gmail credentials. Use separate credentials and connectors when Google environments or mailbox access boundaries differ, and confirm which credential is selected before creating the connector. Revoking or replacing one credential affects the connectors that use it, not unrelated Gmail credentials.

Before you connect

  1. Use Standard mode, because connectors and document indexing require a vector database.
  2. Obtain approval for the mailboxes and historical period that will be indexed.
  3. Start with a narrow indexing start date and a representative account boundary.
  4. Review the first index attempt and its document set before attaching it to an Agent.

Next steps