Metadata-Version: 2.4
Name: ai-courier
Version: 0.5.1
Summary: AI-native email & calendar client over JMAP and CalDAV
Author-email: Jim Perry <jim@hi-team.net>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,caldav,calendar,email,jmap,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.11
Requires-Dist: caldav>=1.3
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: vobject>=0.9
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Courier

**AI-native email & calendar client over JMAP and CalDAV.**

Your AI agent deserves its own email client — not an adapter wrapping a human one.

## The Problem

Every AI agent framework connects to email and calendar by wrapping human-facing apps. MCP servers adapt web UIs. Osascript automates native mail clients. Browser tools click through webmail. Each introduces friction because the agent is fighting an interface designed for someone else.

Courier takes a different approach: connect directly to the open protocols (JMAP for email, CalDAV for calendar) as a first-class client — a peer alongside your human apps, not a wrapper around them.

## What Makes It Different

- **Context-window-optimized output** — emails are structured for AI consumption, not HTML rendering
- **Session state & watermarks** — "what's new?" is a first-class operation that persists between sessions
- **Triage classification** — emails arrive pre-sorted: urgent, needs_reply, actionable, fyi, bulk
- **Batch-first operations** — archive 15 emails in one call, not 15 separate requests
- **Sane timezone handling** — CalDAV with proper TZID normalization and recurrence expansion
- **Composable** — higher-order operations like "find all emails from this person and summarize the thread"

## Quick Start

```bash
pip install ai-courier

# Configure your Fastmail account
courier setup

# Check your inbox (triaged by priority)
courier inbox

# What's new since last check?
courier new

# Today's calendar
courier today

# Find free time
courier free
```

## As an MCP Server

Add to your Claude configuration:

```json
{
  "mcpServers": {
    "courier": {
      "command": "courier-mcp"
    }
  }
}
```

Available tools:

| Tool | Description |
|------|-------------|
| `email_inbox` | Triaged inbox (urgent → bulk) |
| `email_new` | New emails since last check (watermark-based) |
| `email_search` | Flexible email search |
| `email_sent_since` | Recent sent messages (queries Sent mailbox directly) |
| `email_read` | Read full email by ID |
| `email_thread` | Get full thread |
| `email_thread_digest` | Quote-stripped, token-budgeted thread payload |
| `email_archive` | Archive emails (batch) |
| `email_trash` | Trash emails (batch) |
| `email_mark_read` | Mark read (batch) |
| `email_draft` | Create draft |
| `email_send` | Send email |
| `email_mailboxes` | List folders/labels with IDs, paths, roles |
| `email_move` | Move emails to a folder (by ID, name, or path) |
| `email_label` | Add/remove labels without touching other memberships |
| `email_reply` | Threaded reply (In-Reply-To + References); draft or send |
| `email_forward` | Forward an email, re-attaches original as `.eml`; draft or send |
| `calendar_today` | Today's events |
| `calendar_week` | This week's events |
| `calendar_events` | Events in date range |
| `calendar_free` | Find free time slots |
| `calendar_create` | Create event |
| `calendar_rsvp` | Respond to an invite (accepted / tentative / declined) |
| `courier_status` | Connection & watermark status |

## Customizing Triage Rules

Triage rules are defined in YAML. The defaults ship with Courier (see `src/courier/default_rules.yaml`). To customize, create `~/.config/courier/triage-rules.yaml`:

```yaml
# Force specific senders to a classification (checked first, confidence 1.0)
sender_overrides:
  "ceo@mycompany.com": { classification: urgent, reason: "VIP sender" }
  "deals@spammy.com": { classification: bulk, reason: "always bulk" }

# Custom rules — if you define any, they REPLACE the defaults entirely.
# Omit this section to keep defaults and only add sender overrides.
rules:
  - name: my-custom-rule
    classification: urgent
    confidence: 0.9
    reason: "keyword: '{match}'"
    subject_pattern: "\\b(fire|outage|p0)\\b"
```

Each rule supports regex match conditions (`from_pattern`, `subject_pattern`, `body_pattern`, `domain_pattern`) and guard conditions (`requires_known_contact`, `requires_unknown_contact`, `max_size`, `requires_thread`, `requires_flagged`). Rules are evaluated top-to-bottom; first match wins.

See `src/courier/default_rules.yaml` for the full schema documentation and all default rules.

## Architecture

```
AI Agent (Claude, GPT, etc.)
    │
    ▼
Courier MCP Server ← the novel layer
    ├── Email (JMAP)     ├── Calendar (CalDAV)
    │   ├── Watermarks   │   ├── TZID normalization
    │   ├── Triage       │   ├── Recurrence expansion
    │   └── Batch ops    │   └── Free/busy
    └────────────────────┘
    │
    ▼
SQLite (state, watermarks, contact signals)
    │
    ▼
JMAP API ──── CalDAV API
(Fastmail)    (Fastmail)
```

Courier talks to the same backend your human apps do. It's a parallel client, not a wrapper.

## Requirements

- Python 3.11+
- A Fastmail account with an API token ([get one here](https://www.fastmail.com/settings/security/tokens))
- Scopes needed: Mail, Calendars (Contacts optional)

## Development

```bash
git clone https://github.com/iamdadzilla/courier.git
cd courier
pip install -e ".[dev]"
pytest
```

## Why "Courier"?

A courier delivers messages directly. No intermediary, no adapter, no wrapper. Just the message.

## License

MIT
