Knowledge Base
Admin

Gmail

The Gmail API is a RESTful API that can be used to access Gmail mailboxes and send mail. It lets you view and manage Gmail mailbox data like threads, messages, and labels.

Active Verified

Capabilities (11)

Get Email Thread

Get a complete email thread by ID.

get_thread(thread_id, format?) -> Thread
Required scopes:
https://www.googleapis.com/auth/gmail.readonly

Get Email Message

Get a specific email message by ID with full content.

get_message(message_id, format?) -> Message
Required scopes:
https://www.googleapis.com/auth/gmail.readonly

Modify Message Labels

Add or remove labels on a message.

modify_message(message_id, add_labels?, remove_labels?) -> Message
Required scopes:
https://www.googleapis.com/auth/gmail.modify

Send Email

Send an email from the authenticated user.

send_email(to, subject, body) -> Message
Required scopes:
https://www.googleapis.com/auth/gmail.send

Create Email Draft

Create a draft email.

create_draft(to, subject, body) -> Draft
Required scopes:
https://www.googleapis.com/auth/gmail.compose

List Labels

List all labels in the mailbox.

list_labels() -> labels
Required scopes:
https://www.googleapis.com/auth/gmail.readonly

Get Message Attachment

Fetch an attachment's bytes from a Gmail message by `message_id` and `attachment_id`. Returns base64url-encoded data; the caller decodes it. Required for Brain's attachment text extraction pipeline (PDF/DOCX/XLSX/plain text).

get_attachment(message_id, attachment_id) -> %{data, size}
Required scopes:
https://www.googleapis.com/auth/gmail.readonly

Forward Message

Forward an existing Gmail message to a new recipient. Body is prepended with optional forwarding commentary from the user, followed by the original message content (subject/from/date/body). Uses the same underlying send endpoint as `send_email` and `reply_to_thread`, distinguished by including the original message content in the outgoing body.

forward_message(message_id, to, commentary?, cc?, bcc?) -> {id, thread_id}
Required scopes:
https://www.googleapis.com/auth/gmail.send

List Email Messages

List email messages in the user's mailbox. Returns message IDs and thread IDs that can be used to fetch full message content with get_message. IMPORTANT: When a query is provided, use Gmail search operators, NOT natural language. Common queries: 'is:unread', 'in:inbox newer_than:1d', 'from:someone@email.com'. Without a query, returns the most recent messages. Gmail returns results newest-first by default.

list_messages(query?, max_results?) -> messages
Required scopes:
https://www.googleapis.com/auth/gmail.readonly

Search Emails

Search for emails using Gmail search syntax. IMPORTANT: You must translate natural language requests into Gmail search operators. NEVER pass raw natural language as the query — Gmail does keyword matching, not semantic search. COMMON PATTERNS — translate user intent to these queries: • 'latest emails' / 'recent emails' → newer_than:1d (or newer_than:3d for more results) • 'unread emails' → is:unread • 'emails needing response' / 'emails requiring reply' → is:unread in:inbox newer_than:7d • 'emails from John' → from:john • 'emails about project X' → subject:project X • 'emails with attachments' → has:attachment • 'starred emails' → is:starred DATE OPERATORS: newer_than:1d (1 day), newer_than:7d (1 week), newer_than:1m (1 month), after:2025/01/01, before:2025/12/31. COMBINE operators: 'is:unread from:boss@company.com newer_than:3d' Gmail returns results newest-first by default.

search_emails(query, max_results?) -> messages
Required scopes:
https://www.googleapis.com/auth/gmail.readonly

Reply to Thread

Reply to an existing Gmail thread. The reply is threaded inline (same conversation view) rather than starting a new thread. Use when the user asks to respond to a message the agent just read via `get_message` or `get_thread`.

reply_to_thread(thread_id, to, body, subject?, cc?, bcc?) -> {id, thread_id}
Required scopes:
https://www.googleapis.com/auth/gmail.send

Links

Authentication

  • Oauth2_authorization_code (Primary)