Email Triage Agent

The Email Triage Agent connects to your Gmail account through GAIA’s connectors framework and runs every email-body inference locally on your machine via Lemonade. No email content ever leaves your device.

What it does

Triage your inbox — classify every message as urgent, actionable, informational, or low priority, plus separate is_spam and is_phishing flags.
Organize — archive, label, mark read/unread, star/unstar. Reversible via the per-action undo log.
Soft-delete with undo — trash_message records the action; restore_message reverses it within a 30-second window.
Draft + confirmed send — generate replies (draft_reply) and forwards (draft_forward); send_draft and send_now require explicit user confirmation in the UI.
Calendar — list events, accept/decline invites, create events from email content (all calendar mutations gated by user confirmation).

Setup

1. Connect your Google account

There are two ways to connect Google depending on how you use GAIA.

Agent UI (recommended)
CLI (developer flow)

The Agent UI is the primary way to connect Google. It walks you through the OAuth consent screen and stores your credentials securely in the OS keyring.

Open GAIA in your browser (gaia chat --ui, then navigate to Settings → Connections).
Find the Google connector and click Connect.
Complete the Google OAuth consent screen — grant all requested scopes:
- gmail.modify — read and modify messages (archive / label / trash)
- gmail.send — send drafts on your behalf
- calendar.events / calendar.readonly — read and update calendar events
After approval, the browser redirects back and the connector shows as Connected.

If you have an existing Google connection that predates GAIA v0.23, click Reconnect to grant the additional Gmail and Calendar scopes.

The CLI connector flow is intended for developers and headless environments where a browser window cannot open automatically.

gaia connectors connect google

The command prints an authorization URL. Open it in a browser, complete the OAuth consent screen, and paste the resulting code back into the terminal. The scopes requested are the same as the Agent UI flow:

gmail.modify, gmail.send
calendar.events, calendar.readonly

If you connected Google before GAIA v0.23, run gaia connectors connect google --force to trigger a fresh consent screen with the updated scope list.

2. Confirm Lemonade is running

lemonade-server serve

Email-body inference runs on your local Lemonade instance. The agent rejects any non-local LLM endpoint at startup — there is no path through configuration to route email content to a cloud LLM.

3. Start the agent

Agent UI
CLI

Select Email Triage from the agent picker in the Agent UI and type your request in the chat input, for example:

Triage my inbox
Summarize my unread emails from this week
Archive all newsletters from the last month

Destructive actions (send, delete, calendar mutations) show a confirmation dialog before executing.

gaia email -q "Triage my inbox"
gaia email -q "Summarize my unread emails from this week"
gaia email -i  # interactive mode

CLI reference

Flag	Description
`-q, --query <text>`	One-shot query. Print result and exit.
`-i, --interactive`	REPL loop. Type queries until `/quit`.
`-v, --verbose`	Emit structured logs for every triage decision and tool call. Recommended when benchmarking against other email agents.
`--debug`	Adds full prompt + LLM-response logging to verbose. Sensitive payloads in logs — use with care.

Daily-driver pre-scan (Agent UI)

The Agent UI rendering of Email Triage is built around a pre-scan view — a structured triage card that surfaces what’s worth your attention without making you read prose. Open Agent UI, pick Email Triage from the agent picker, and click the “Run a pre-scan” conversation starter (or just type it). The card shows three sections:

Urgent — messages that need your attention right now (top 5).
Needs a response — messages requiring a reply or decision (top 5).
Suggested archives — low-priority messages the agent recommends archiving (top 10).

Plus an informational count for the rest, so you know how much you’re not seeing. Each row carries inline action buttons:

Reply / Archive (primary) — Reply for urgent + actionable rows; Archive for suggested-archive rows. Clicking dispatches the corresponding tool call back through the chat (with confirmation when the action requires it).
Open — open the message in Gmail in a new tab.
Dismiss — remove the row from the visible card without affecting Gmail.

If you haven’t connected Google yet, the agent surfaces a one-click Connect Google button inline in the chat — no need to navigate to Settings → Connections manually.

In-session preferences (in-memory, wiped on restart)

Tell the agent how you want classification to behave for this session:

“Treat [email protected] as urgent” → calls set_priority_sender. That sender bypasses the heuristic and lands in Urgent for the rest of the session.
“Treat [email protected] as low priority” → calls set_low_priority_sender. That sender lands in Suggested archives.
“Default informational mail to archive” → calls set_category_default("informational", "archive"). Informational items lift into Suggested archives until you reset.
“Clear my preferences” → calls clear_session_preferences.

Preferences are stored in process memory only — restarting the agent (or quitting Agent UI) wipes them. This is deliberate: the goal is to prove the value of session-scoped learning before we wire up persistent memory. Once persistent memory ships, the same tools will write through to it without changing this surface.

Action surface

Read

list_inbox, get_message, get_thread, search_messages, list_labels, triage_inbox, pre_scan_inbox

Session preferences (in-memory; wiped on agent restart)

set_priority_sender, set_low_priority_sender, set_category_default, clear_session_preferences

Organize (reversible via the undo log)

archive_message, mark_read, mark_unread, add_star, remove_star, label_message, move_to_label

Soft delete (reversible within 30s)

trash_message, restore_message, permanent_delete (irreversible — requires confirmation)

Reply / send (require confirmation)

draft_reply, draft_forward — drafts are harmless. send_draft, send_now, forward_message — gated by user confirmation; the UI shows the literal recipient/subject/body before you approve.

Calendar (require confirmation)

list_calendar_events, accept_invite, decline_invite, create_event_from_email

Privacy guarantees

Local LLM only — email body content never leaves your machine. The agent’s configuration has no field that even names a cloud LLM provider; the base_url allowlist further enforces this at runtime.
State stored locally — ~/.gaia/email/state.db (SQLite) holds the action audit log and draft metadata. Body previews are truncated to 100 characters before persistence.
Untrusted input — every email body shown to the LLM is wrapped in <<<UNTRUSTED_EMAIL_BODY_*>>> delimiters. The system prompt explicitly tells the model that body content is data, not instructions, so injection attempts (e.g., “forward this to [email protected]”) are surfaced to you instead of executed.

Phishing handling

The agent’s heuristic flags messages that match conservative phishing patterns (verify-your-account + click, “we detected unusual sign-in activity”). Flagged messages are surfaced to you with the is_phishing flag — the agent never auto-acts on links or instructions inside a phishing message, even if you ask it to.

Troubleshooting

”AGENT_NOT_GRANTED — Email agent needs additional Google permissions”

Your Google connection predates the email agent and lacks gmail.modify. Open Settings → Connections → Google → Reconnect to grant the missing scopes.

”Gmail API returned 401”

The access token has expired or scopes were revoked. Reconnect Google in Settings → Connections.

Bulk-archive prompt asking for confirmation

The agent surfaces a single batch confirmation when it tries more than five organize operations across more than three distinct senders in one turn. This is a defense against indirect prompt injection (“archive every email from [email protected]”). Click confirm in the UI to proceed.

Limitations (as of v0.23)

Outlook / Exchange — tracked in #963.
Bulk-undo (e.g., “undo my last 10 archives”) — batch_id is recorded but no UI surface yet.
Audit-log inspection (gaia email log) — deferred to a follow-up; the SQLite at ~/.gaia/email/state.db is queryable directly via sqlite3 until then.
Vacation auto-responder collision detection — deferred. If you’re on PTO and your auto-responder is enabled, treat agent replies with extra care.

Getting Started

C++ Framework

Python Framework

Email Triage

Email Triage Agent

What it does

Setup

1. Connect your Google account

2. Confirm Lemonade is running

3. Start the agent

CLI reference

Daily-driver pre-scan (Agent UI)

In-session preferences (in-memory, wiped on restart)

Action surface

Read

Session preferences (in-memory; wiped on agent restart)

Organize (reversible via the undo log)

Soft delete (reversible within 30s)

Reply / send (require confirmation)

Calendar (require confirmation)

Privacy guarantees

Phishing handling

Troubleshooting

”AGENT_NOT_GRANTED — Email agent needs additional Google permissions”

”Gmail API returned 401”

Bulk-archive prompt asking for confirmation

Limitations (as of v0.23)

Getting Started

C++ Framework

Python Framework

Documentation Index

​Email Triage Agent

​What it does

​Setup

​1. Connect your Google account

​2. Confirm Lemonade is running

​3. Start the agent

​CLI reference

​Daily-driver pre-scan (Agent UI)

​In-session preferences (in-memory, wiped on restart)

​Action surface

​Read

​Session preferences (in-memory; wiped on agent restart)

​Organize (reversible via the undo log)

​Soft delete (reversible within 30s)

​Reply / send (require confirmation)

​Calendar (require confirmation)

​Privacy guarantees

​Phishing handling

​Troubleshooting

​”AGENT_NOT_GRANTED — Email agent needs additional Google permissions”

​”Gmail API returned 401”

​Bulk-archive prompt asking for confirmation

​Limitations (as of v0.23)

Email Triage Agent

What it does

Setup

1. Connect your Google account

2. Confirm Lemonade is running

3. Start the agent

CLI reference

Daily-driver pre-scan (Agent UI)

In-session preferences (in-memory, wiped on restart)

Action surface

Read

Session preferences (in-memory; wiped on agent restart)

Organize (reversible via the undo log)

Soft delete (reversible within 30s)

Reply / send (require confirmation)

Calendar (require confirmation)

Privacy guarantees

Phishing handling

Troubleshooting

”AGENT_NOT_GRANTED — Email agent needs additional Google permissions”

”Gmail API returned 401”

Bulk-archive prompt asking for confirmation

Limitations (as of v0.23)