Courier

Fastmail-only Alpha preview. An AI-native email & calendar client over JMAP and CalDAV.

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

Not Courier Inc. / trycourier.com (notification API). This project's PyPI name is ai-courier. The CLI is courier; the MCP server command is courier-mcp.

Today Courier talks to Fastmail only. Gmail, iCloud, and Exchange are not supported — they are contribution targets, not a cold-install path. courier setup configures a Fastmail JMAP token plus a Fastmail CalDAV app password.

MCP write tools are gated by trust_level in ~/.config/courier/config.json (read → file → correspond → manage). courier setup defaults new installs to file (read + archive/move/label/drafts). Existing configs that omit the field stay at manage so upgrades do not revoke send/trash. An agent cannot raise its own trust level.

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). courier setup asks for the IANA timezone.
• Composable — higher-order operations like "find all emails from this person and summarize the thread"

Quick Start

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

mcp 2.x: Courier 0.8.5+ pins mcp>=1.28,<2. Releases before 0.8.5 declared mcp>=1.0, so an unpinned uvx / pip install can pull mcp 2.x and crash courier-mcp on import (Server has no list_tools). Upgrade to 0.8.5+ (0.9.0 recommended), or pin the extra while you wait:

uvx --from ai-courier --with 'mcp>=1.12,<2' courier-mcp

As an MCP Server

Add to your Claude configuration:

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

list_tools only returns tools allowed at the configured trust_level. A file-tier agent never sees email_send. Calling a hidden tool still fails loudly with the required tier. See docs/THREAT_MODEL.md.

Available tools (full manage surface):

Email — read & triage

Email — write & file

Contacts

Calendar

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:

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

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. Write methods honor trust_level (a read config cannot archive).

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) — 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, iCloud #3, Exchange #1). Do not invent a second provider on speculation — see CONTRIBUTING.md.

Development

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

See CONTRIBUTING.md for tests and scope, SECURITY.md to report issues, CHANGELOG.md for release history, and docs/ROADMAP.md for the generated feature roadmap.

Why "Courier"?

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

License

MIT