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="openai/gpt-4o-mini",
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.
