> ## 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.

# Gmail

> Host agents as Gmail email assistants

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:

```bash theme={null}
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)

<Note>
  The interface uses a pull-based model - you manually trigger email checks via the `/gmail/check` endpoint, and the agent processes unread emails.
</Note>

## 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](/concepts/agents/advanced/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:

```python theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.