ai-courier 0.8.2

AI-native email & calendar client over JMAP and CalDAV

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

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:

{
  "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:

# Force specific senders to a classification (checked first, confidence 1.0)
sender_overrides:
  "[e-mail]": { classification: urgent, reason: "VIP sender" }
  "[e-mail]": { 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.

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 — contributions welcome).

Development

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

See CHANGELOG.md for release history and 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