Gmail - Upsonic AI

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

Parameter	Type	Default	Description
`agent`	`Agent`	Required	Upsonic `Agent` instance.
`name`	`str`	`"Gmail"`	Interface name.
`credentials_path`	`Optional[str]`	`None`	Path to Gmail OAuth credentials.json.
`token_path`	`Optional[str]`	`None`	Path to Gmail OAuth token.json.
`api_secret`	`Optional[str]`	`None`	Secret token for API authentication (or set `GMAIL_API_SECRET`).
`mode`	`Union[InterfaceMode, str]`	`InterfaceMode.TASK`	`TASK` or `CHAT`.
`reset_command`	`Optional[str]`	`"/reset"`	Text in email body that resets chat session (CHAT mode). Set `None` to disable.
`storage`	`Optional[Storage]`	`None`	Storage backend for chat sessions (CHAT mode).
`allowed_emails`	`Optional[List[str]]`	`None`	Whitelist of sender emails; only these are processed. `None` = allow all.

Key Methods

Method	Parameters	Return Type	Description
`attach_routes`	None	`APIRouter`	Returns the FastAPI router and attaches endpoints.
`check_and_process_emails`	`count: int = 10`	`CheckEmailsResponse`	Manually trigger email check and processing.
`is_email_allowed`	`email: str`	`bool`	Whether 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.

​Installation

​Setup

​Operating Modes

​Reset Command (CHAT mode only)

​Access Control (Whitelist)

​Example Usage

​Core Components

​GmailInterface Interface

​Initialization Parameters

​Key Methods

​Endpoints

​POST /gmail/check

​GET /gmail/health

Installation

Setup

Operating Modes

Reset Command (CHAT mode only)

Access Control (Whitelist)

Example Usage

Core Components

`GmailInterface` Interface

Initialization Parameters

Key Methods

Endpoints

`POST /gmail/check`

`GET /gmail/health`