Mail Agent¶

Thinklio Built-in Agent Specification Version 0.1 | March 2026

1. Purpose and Problem Statement¶

The Mail Agent gives Thinklio conversational and automated access to email. A user can ask it to summarise their inbox, draft replies, send messages, flag items for follow-up, and surface what needs attention — all within the governance framework that ensures autonomous sending never happens without appropriate authorisation.

It also functions as a feeder for other agents: inbound emails can trigger Enquiry Agent Items, create Taskmaster tasks, log Rolodex interactions, and surface time-sensitive content to the Calendar Agent.

Governance: The Mail Agent follows the shared governance model defined in 00-governance-model.md. All send operations are subject to permission levels and constraints configured at org, team, and user level.

2. UI Structure¶

[ Chat ]  [ Inbox ]  [ Drafts ]  [ Sent ]  [ Rules ]

Chat Tab¶

The primary interface for intelligent mail operations: - "Summarise my unread emails" - "Draft a reply to the invoice from Lavan Lawyers — say we'll process it by end of week" - "Are there any emails I should deal with urgently today?" - "Send a follow-up to Marcus re the Novansa contract — keep it brief" - "Flag everything from support@acme.com for the Enquiry Agent"

Inbox Tab¶

A filtered, agent-curated view of the inbox — not a raw email client. The agent groups and prioritises messages: - Needs action — emails the agent has identified as requiring a response or decision - FYI — informational, no action needed - Newsletters/digests — bulk sender content - Waiting — emails sent by the user awaiting reply

Each message shows sender, subject, date, and an agent-generated one-line summary. Clicking opens the full message with an action panel (reply, forward, create task, log interaction, route to Enquiry Agent).

Drafts Tab¶

Drafts created by the agent awaiting user approval (when operating at draft or send_with_approval level). Each draft shows the intended recipient, subject, and a preview. Approve, edit, or discard actions are available.

Sent Tab¶

A log of emails sent by or through the agent, with permission level applied and approval chain if applicable.

Rules Tab¶

User-configured routing rules that determine how the agent handles inbound email automatically (see section 5).

3. Configuration¶

3.1 Admin Configuration¶

Setting	Description
Connected accounts	Which email providers are supported and how they are authenticated (OAuth via Keeper)
Default permission matrix	Default permission level per action type for new users
Autonomous send constraints	Hard limits on autonomous sending: volume per day, permitted recipient domains
Auto-routing enabled	Whether inbound routing rules can be configured at all
Enquiry Agent integration	Whether the Mail Agent may route inbound emails to the Enquiry Agent

3.2 Permission Matrix (configurable at org → team → user)¶

Action	Permission Level
Read email	`read`
Summarise inbox	`read`
Draft reply/compose	`draft`
Send — known contacts (Rolodex match)	configurable
Send — unknown recipients	configurable
Send — bulk / multiple recipients	configurable
Auto-archive / label	configurable
Route to Enquiry Agent	configurable

3.3 User Configuration¶

Setting	Description
Connected accounts	Which email accounts the agent has access to
Inbox summary frequency	How often the agent proactively summarises the inbox (or on-demand only)
Signature	Email signature to append to agent-drafted outbound emails
Tone preference	Default tone for agent-drafted replies (professional / friendly / concise)
Auto-log to Rolodex	Whether sent/received emails from known contacts are logged as Interactions

4. Inbox Intelligence¶

The Mail Agent does more than retrieve email. When reading the inbox it applies a layer of interpretation:

Priority scoring — based on sender (Rolodex match + relationship strength), subject urgency signals, and thread age
Action detection — identifying emails that contain a request, a deadline, or an implied task
Grouping — threading, sender clustering, and bulk sender identification
Summarisation — generating one-line summaries per message and a digest summary across the inbox

The inbox summary returned by the agent is structured:

InboxSummary
├── unread_count        integer
├── needs_action[]
│   ├── message_id      string
│   ├── from            string
│   ├── subject         string
│   ├── summary         string
│   ├── urgency         enum (high | normal | low)
│   └── suggested_action string | null
├── fyi[]               (same structure, no urgency)
├── waiting[]           (sent emails awaiting reply, with age)
└── digest              string (natural language summary of the above)

The digest is what the agent returns in conversational mode: "You have 14 unread emails. Three need attention: there's an invoice from Lavan Lawyers due this week, a follow-up request from Marcus Chen, and a question from the Cares Communities board secretary that needs a response. The rest is mostly newsletters and FYI updates."

5. Routing Rules¶

Rules allow the user to configure automatic handling of inbound email without per-message interaction:

Rule
├── rule_id             UUID
├── name                string
├── conditions[]
│   ├── field           enum (from | to | subject | domain | has_attachment | body_contains)
│   ├── operator        enum (is | contains | starts_with | matches_domain)
│   └── value           string
├── actions[]
│   ├── type            enum (label | archive | create_task | create_item | log_interaction | notify | forward_to_agent)
│   └── params          object
└── enabled             boolean

Example rule: all emails to support@org.com → create an Enquiry Agent Item of type support.

Rules that trigger agent actions (create_item, create_task) are subject to the same governance constraints as direct agent actions.

6. Agent Capabilities¶

Capability	Description
Read inbox	Retrieve and summarise inbox contents
Read message	Retrieve full content of a specific message
Draft	Compose an email (reply or new) without sending
Send	Send an email, subject to permission level
Create task	Create a Taskmaster task from an email
Log interaction	Log an email as a Rolodex Interaction
Route to Enquiry	Forward an inbound email to the Enquiry Agent as a new Item
Apply label	Label or archive a message
Search	Search across email by sender, subject, date, keyword

7. Inter-Agent Behaviour¶

Keeper provides authenticated email account access via OAuth proxy
Rolodex is queried to enrich sender context and to log interactions
Taskmaster receives tasks created from email flagging
Enquiry Agent receives routed inbound emails as new Items
Calendar Agent receives meeting invitations detected in email for processing

8. Use Cases¶

UC-1: Morning inbox briefing¶

A user opens Thinklio and asks "what's in my inbox?" The Mail Agent returns a digest: 14 unread, two needing action (invoice and follow-up request), and a note about a meeting invitation already handled by the Calendar Agent.

UC-2: Autonomous reply to a known contact¶

A user has configured send_autonomous for replies to Rolodex-matched contacts. The Mail Agent drafts and sends a brief reply to a known contact's routine enquiry without interrupting the user. The send is logged in the audit trail.

UC-3: Draft for approval¶

A user asks the agent to draft a reply to a supplier about a payment dispute. The agent composes a professional draft and queues it in the Drafts tab. The user reviews, edits one paragraph, and approves. The email is sent.

UC-4: Routing inbound support emails¶

An admin sets up a rule: emails to support@org.com → create Enquiry Agent Item (type: support). Inbound support emails are automatically converted to Items without manual processing, with the original email attached.

UC-5: Follow-up detection¶

The user asks "are there any emails I'm waiting on a reply for?" The Mail Agent reviews the Sent folder for outbound messages with no reply after 3+ days and returns a list with send dates and original subjects.

9. Open Questions¶

Multi-account support (personal and work email in one interface) adds significant complexity. Is this in scope for the initial release?
The autonomous send capability requires careful UX — users need to feel confident about what the agent will and won't do autonomously. An onboarding flow that walks through permission configuration may be needed before the agent is activated.
Email content contains sensitive information. How is this handled in terms of storage — does Thinklio retain email content, or does it query the mail provider on demand and process in memory only?
Attachment handling is not addressed in this spec. Reading, summarising, and routing attachments is a natural extension but adds scope.

Previous: Keeper Agent | Next: Calendar Agent