Metadata-Version: 2.4
Name: ai-courier
Version: 0.8.2
Summary: AI-native email & calendar client over JMAP and CalDAV
Project-URL: Homepage, https://github.com/iamdadzilla/courier
Project-URL: Repository, https://github.com/iamdadzilla/courier
Project-URL: Changelog, https://github.com/iamdadzilla/courier/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/iamdadzilla/courier/issues
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
- **Real scheduling, not just storage** — RSVPs send iTIP REPLY to the organizer; events with attendees send real invitations
- **Identity-aware sending** — `from` on every write tool picks the matching Fastmail identity (alias) per call
- **Contacts as a first-class surface** — full CRUD: lookup, search, create, update, delete (JMAP Contacts, RFC 9610/9553)
- **Sane timezone handling** — TZID normalization, recurrence expansion, and input datetimes that land at the right instant (offsets honored; naive = account-local)
- **Composable** — higher-order operations like "find all emails from this person and summarize the thread"

## Quick Start

```bash
pip install ai-courier        # or: uv tool 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:

### Email — read & triage

| Tool | Description |
|------|-------------|
| `email_inbox` | Triaged inbox (urgent → bulk), 200-char snippets, saturation signal |
| `email_new` | New emails since last check (watermark-based) |
| `email_search` | Flexible search, including by mailbox (folder ID, name, or path) |
| `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_drafts` | Authoritative Drafts listing with `created_at` / `last_modified_at` |
| `email_attachments` | List attachments on an email |
| `email_attachment_save` | Download an attachment to disk |
| `email_mailboxes` | List folders/labels with IDs, paths, roles |

### Email — write & file

| Tool | Description |
|------|-------------|
| `email_send` | Send email (plain or HTML; optional `from` identity) |
| `email_reply` | Threaded reply (In-Reply-To + References); draft or send; replies to alias-addressed mail default to that alias |
| `email_forward` | Forward an email, re-attaches original as `.eml`; draft or send |
| `email_draft` | Create draft |
| `email_archive` | Archive emails (batch; optional atomic label add/remove) |
| `email_trash` | Trash emails (batch) |
| `email_mark_read` | Mark read (batch) |
| `email_move` | Move emails to a folder (by ID, name, or path) |
| `email_label` | Add/remove labels without touching other memberships |
| `list_identities` | Sending identities (aliases) available to `from` |

### Contacts

| Tool | Description |
|------|-------------|
| `contact_lookup` | Full contact record by email address |
| `contact_search` | Search contacts by name / text |
| `contact_create` | Create a contact (name, emails, phones, org, title, notes) |
| `contact_update` | Update a contact — name/org/title/notes replace; emails/phones append |
| `contact_delete` | Delete a contact — permanent; there is no trash can for contacts |

### Calendar

| Tool | Description |
|------|-------------|
| `calendar_today` | Today's events |
| `calendar_week` | This week's events |
| `calendar_events` | Events in date range |
| `calendar_search` | Text search across summary / location / description |
| `calendar_free` | Find free time slots (respects working hours) |
| `calendar_free_both` | Free slots intersected across primary + delegate accounts |
| `calendar_create` | Create event — attendees get real iTIP REQUEST invitations (`notify_attendees=false` to skip) |
| `calendar_update` | Update event fields |
| `calendar_move` | Move event between calendars |
| `calendar_delete` | Delete event |
| `calendar_rsvp` | Respond to an invite — sends iTIP REPLY to the organizer (`notify_organizer=false` to skip) |

### Status

| Tool | Description |
|------|-------------|
| `courier_status` | Live connection probe, watermark status, server version |

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

## As a Python Library

For in-process consumers (cron scripts, pipelines) that don't want to host an MCP server or shell out to the CLI:

```python
from courier import Client

client = Client()                      # lazy connect, reads ~/.config/courier/config.json
for email in client.email_new():       # shares the MCP server's watermark
    if looks_routine(email):
        client.email_archive([email.id])
```

The library surface is deliberately narrow — read, label, archive, mark-read. No send, no calendar.

## Architecture

```
AI Agent (Claude, GPT, etc.)
    │
    ▼
Courier MCP Server ← the novel layer
    ├── Email (JMAP)     ├── Calendar (CalDAV)    ├── Contacts (JMAP)
    │   ├── Watermarks   │   ├── TZID handling    │   ├── Lookup/search
    │   ├── Triage       │   ├── Recurrence       │   └── Create/update
    │   ├── Identities   │   ├── Free/busy
    │   └── Batch ops    │   └── iTIP REPLY/REQUEST
    └─────────────────────┘
    │
    ▼
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 **two credentials** (Fastmail issues these separately; `courier setup` prompts for both):
  - a JMAP API token ([get one here](https://www.fastmail.com/settings/security/tokens)) — scopes: Mail, and Contacts if you want the contact tools
  - a CalDAV app password — for the calendar tools

Other JMAP/CalDAV providers are on the roadmap ([Gmail #2](https://github.com/iamdadzilla/courier/issues/2), [iCloud #3](https://github.com/iamdadzilla/courier/issues/3), [Exchange #1](https://github.com/iamdadzilla/courier/issues/1) — contributions welcome).

## Development

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

See [CHANGELOG.md](CHANGELOG.md) for release history and [docs/ROADMAP.md](docs/ROADMAP.md) for the auto-generated feature roadmap.

## Why "Courier"?

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

## License

MIT
