Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt

Use this file to discover all available pages before exploring further.

Use the Gmail interface to serve Agents via Gmail. It mounts API routes on a FastAPI app and enables automated email processing and replies.

​
Installation

Install the Gmail interface dependencies: 
uv pip install "upsonic[gmail-interface]"

​
Setup

Required environment variables:
  • GMAIL_API_SECRET (optional, for endpoint protection)
  • Gmail OAuth credentials (via credentials.json and token.json files)
The interface uses a pull-based model - you manually trigger email checks via the /gmail/check endpoint, and the agent processes unread emails.

​
Operating Modes

  • TASK (default) – Each email is processed as an independent task; no conversation history. Best for classification, auto-responders, one-off processing.
  • CHAT – Emails from the same sender share a conversation session. The agent can reference earlier emails. Best for support threads and ongoing conversations.

​
Reset Command (CHAT mode only)

In CHAT mode, senders can clear their conversation by including the reset command in the email body (e.g. /reset). You configure it with reset_command; set to None to disable. If the agent has a workspace configured, the reset command will also trigger a dynamic greeting message based on the workspace configuration. See Workspace for details.

​
Access Control (Whitelist)

Pass allowed_emails (list of email addresses). Only those senders are processed; others receive a fixed “This operation not allowed” response. Omit allowed_emails (or set None) to allow all senders.

​
Example Usage

Create an agent, expose it with the GmailInterface interface, and serve via InterfaceManager. Example with CHAT mode, reset command, and optional whitelist: 
import os
from upsonic import Agent
from upsonic.interfaces import InterfaceManager, GmailInterface, InterfaceMode

agent = Agent(
    model="anthropic/claude-sonnet-4-6",
    name="EmailAssistant",
)

gmail = GmailInterface(
    agent=agent,
    credentials_path="credentials.json",
    token_path="token.json",
    api_secret=os.getenv("GMAIL_API_SECRET"),
    mode=InterfaceMode.CHAT,
    reset_command="/reset",
    allowed_emails=["support@mycompany.com", "user@example.com"],
)

manager = InterfaceManager(interfaces=[gmail])

if __name__ == "__main__":
    manager.serve(host="0.0.0.0", port=8000, reload=False)

​
Core Components

  • GmailInterface (interface): Wraps an Upsonic Agent for Gmail via FastAPI.
  • InterfaceManager.serve: Serves the FastAPI app using Uvicorn.

​
GmailInterface Interface

Main entry point for Upsonic Gmail applications.

​
Initialization Parameters

ParameterTypeDefaultDescription
agentAgentRequiredUpsonic Agent instance.
namestr"Gmail"Interface name.
credentials_pathOptional[str]NonePath to Gmail OAuth credentials.json.
token_pathOptional[str]NonePath to Gmail OAuth token.json.
api_secretOptional[str]NoneSecret token for API authentication (or set GMAIL_API_SECRET).
modeUnion[InterfaceMode, str]InterfaceMode.TASKTASK or CHAT.
reset_commandOptional[str]"/reset"Text in email body that resets chat session (CHAT mode). Set None to disable.
storageOptional[Storage]NoneStorage backend for chat sessions (CHAT mode).
allowed_emailsOptional[List[str]]NoneWhitelist of sender emails; only these are processed. None = allow all.

​
Key Methods

MethodParametersReturn TypeDescription
attach_routesNoneAPIRouterReturns the FastAPI router and attaches endpoints.
check_and_process_emailscount: int = 10CheckEmailsResponseManually trigger email check and processing.
is_email_allowedemail: strboolWhether the sender is in the whitelist (or whitelist disabled).

​
Endpoints

Mounted under the /gmail prefix:

​
POST /gmail/check

  • Manually triggers a check for unread emails and processes them.
  • Query parameter: count (default: 3) - maximum number of emails to process.
  • Requires X-Upsonic-Gmail-Secret header if GMAIL_API_SECRET is configured.
  • Fetches unread emails, processes each with the agent, sends replies if agent decides to reply, marks emails as read.
  • Returns: 200 CheckEmailsResponse with status, processed_count, and message_ids.

​
GET /gmail/health

  • Health/status of the interface.