semos-agentura-email

Unified email client with LLM agent. Supports IMAP/SMTP, Outlook COM, CalDAV, and Microsoft Graph API backends.

Backends

Email and calendar backends are independent (for example, IMAP for email plus CalDAV for calendar).

Auto-detection priority:

1. Explicit BACKEND=com|imap|graph overrides
2. IMAP_HOST + AZURE_CLIENT_ID + EMAIL_ADDRESS → IMAP
3. GRAPH_CLIENT_ID → Graph API
4. Windows → COM

Setup

uv sync              # base (IMAP + LLM agent)
uv sync --extra com  # + Outlook COM (Windows)

Create a .env in this directory and configure the keys below.

IMAP/SMTP (any OS)

AZURE_CLIENT_ID=your-azure-app-client-id
AZURE_TENANT_ID=your-tenant-id
EMAIL_ADDRESS=user@example.com
IMAP_HOST=outlook.office365.com
SMTP_HOST=smtp.office365.com

COM (Windows, no config needed)

Outlook must be running. Auto-detected on Windows if no IMAP config is set.

@mailgent agent

MODEL=anthropic/claude-sonnet-4-5
AZURE_API_KEY=your-api-key
AZURE_API_BASE=https://your-endpoint.openai.azure.com

Agent discovery and runtime keys (AGENT_HOST, LOG_LEVEL, ROUTER_LLM_*) are documented in the root README.

CLI

uv run python run.py                    # show help

# Email
uv run python run.py search-emails <query>
uv run python run.py read-email <query>
uv run python run.py read-email <query> --save-att
uv run python run.py draft <to> <subject> <body> [--cc=...] [--att=file1,file2]
uv run python run.py send <to> <subject> <body>

# Calendar
uv run python run.py events [days]
uv run python run.py free-slots [days]
uv run python run.py create-event <subject> <start> <end>

# @mailgent agent
uv run python run.py agent [interval]   # polling loop (default 30s)
uv run python run.py agent-once         # process pending and exit

# Archive
uv run python run.py archive            # incremental dump to SQLite
uv run python run.py archive-stats
uv run python run.py archive-search <query>

@mailgent

Write @mailgent: in a draft or incoming email to trigger the LLM agent:

Dear colleague,
@mailgent: What are my free slots next week?

Best regards

The agent processes the prompt, calls tools (search emails, check calendar, etc.), and inserts the response directly below the prompt with a unique ID:

Dear colleague,
@mailgent[a1b2c3d4]: What are my free slots next week?
------------ mailgent[a1b2c3d4] ------------
Monday: 10:00-12:00, 14:00-17:00
Tuesday: 8:00-10:00, 13:00-17:00
------------ mailgent[a1b2c3d4] ------------

Best regards

Re-run: Delete the response block and remove the [id] from the prompt.

Multiple prompts per email are supported, and each gets its own ID.

Tools available to @mailgent

• search_emails: search by subject
• read_email: read full email content
• list_events: calendar events for next N days
• free_slots: free meeting slots
• create_draft: create email draft
• draft_reply / send_reply: reply to an email
• draft_event / send_event: create calendar event
• set_flag: set an email's flag to marked (follow-up), complete, or none

Config

MAILGENT_TAG=@mailgent
MAILGENT_MODEL=anthropic/claude-sonnet-4-5    # or use MODEL=
MAILGENT_AUTO_REPLY=false                      # reply to inbox emails
MAILGENT_AUTO_SEND=false                       # send replies immediately
MAILGENT_TRUSTED_REPLY=*@company.com           # auto-reply trust list
MAILGENT_TRUSTED_SEND=me@company.com           # auto-send trust list

Tests

uv run pytest tests/ -v                        # all tests
uv run pytest tests/test_backend.py -v         # unit tests (mocked, no backend needed)
uv run pytest tests/test_integration.py -v     # integration tests (needs real backend)

Architecture

src/semos/agentura/email/
  config.py        Settings (Pydantic BaseSettings)
  models.py        EmailMessage, Attachment, EventInfo
  exceptions.py    Exception hierarchy
  auth.py          OAuth2 (MSAL device code flow)
  imap_client.py   IMAP read/search/draft
  smtp_client.py   SMTP send
  client.py        MailClient facade (IMAP + SMTP)
  backend.py       EmailBackend + CalendarBackend protocols, IMAPBackend, COMBackend, factory
  com_client.py    Outlook COM wrapper (Windows)
  tools.py         LLM tool definitions + executor
  mailgent.py      @mailgent agent loop
  formatting.py    Markdown ↔ plain/HTML conversion
  archive.py       Incremental SQLite archive