Gmail

The Gmail connector indexes message headers and message bodies into the local SQLite index and exposes read tools for labels, messages, and threads, plus three HITL-gated write tools for drafting and sending mail.

---

What’s indexed

• Service id: gmail
• Item types: email
• Body: the message body, up to 16,384 UTF-16 code units. The sync walks the MIME tree of a format=full message and prefers the text/plain part, falling back to text/html converted to plain text; quoted reply chains and signature blocks are stripped. If no body part can be extracted (an encrypted or malformed message, or one exceeding the walker’s depth/part bounds) the connector falls back to Gmail’s short snippet, which stays searchable but is marked incomplete (body_complete = 0) rather than claiming to be the whole message.
• Attachments are never fetched — attachment bytes never reach the index.

Bandwidth, not quota

Fetching bodies uses format=full instead of format=metadata. Both are the same users.messages.get call, so switching format does not change what the request costs you against your Gmail API quota — but format=full returns the inline part bytes, so an initial mailbox sync moves substantially more data than it did before this was enabled.

(The absolute cost of users.messages.get is Google’s to set and has changed: the current published figure is 20 quota units, while Cloud projects that used the API between November 2025 and April 2026 keep their previously-set quotas. Check Gmail API usage limits for your project rather than assuming a number.)

Indexing depth is enforced on every sync, not just at reindex time. A connector set to summary clamps the body to 512 UTF-16 code units; metadata_only suppresses it entirely. See Indexing depth.

Authenticate

nimbus connector auth gmail

OAuth (Google). The Gateway resolves a short-lived access token per service via the per-service Google OAuth flow and injects it into the connector spawn as GOOGLE_OAUTH_ACCESS_TOKEN. Tokens are never logged and never reach the LLM context.

Read tools (no HITL)

Tool	Purpose
gmail_label_list	List all Gmail labels.
gmail_message_list	List Gmail message ids (metadata). Supports a Gmail search q (same syntax as the Gmail UI).
gmail_message_read	Read a single Gmail message (format: minimal | metadata | full | raw).
gmail_thread_read	Read a Gmail thread and its messages.

Write tools (HITL-gated)

Every tool below requires interactive consent through the Gateway HITL gate before it executes.

Tool	Purpose
gmail_draft_create	Create a Gmail draft.
gmail_draft_send	Send an existing Gmail draft by id.
gmail_message_send	Send a new Gmail message (not a draft).

See also

• Connectors overview
• HITL and safety