v1.1.22

• courier connects to IMAP only when a call needs the server. A search or read that the local index answers makes no connection, and in:sent is served from the index when the Sent folder is synced.
• read --message-id looks the message up in the local index first, and falls back to a live search.
• On a reply-all, an explicit --cc adds to the thread's Cc instead of replacing it. Cc is deduplicated, ignoring case. Closes #70.
• Every run keeps the Claude Code command file current. install-claude-command writes it unconditionally and no longer takes --yes.

Install

PyPI (pip or pipx, any platform)

pip install courier            # CLI only
pip install "courier[mcp]"     # CLI plus MCP server mode

For an isolated install that does not touch your system or project environment, use pipx: pipx install courier (or pipx install "courier[mcp]" for MCP mode).

uv (any platform, no install step)

uvx courier search "subject:invoice"

To install permanently: uv tool install courier

Homebrew (all features, macOS and Linux)

brew tap overseers-desk/od
brew install courier

Debian / Ubuntu (CLI-only)

Download the .deb below and install:

sudo apt install ./courier_*_all.deb

RPM / Fedora (CLI-only)

Download the .rpm below and install:

sudo dnf install ./courier-<version>-1.noarch.rpm

Upgrade

Homebrew (macOS / Linux)

brew update
brew upgrade courier

brew upgrade courier alone reports "already installed and up-to-date" because Homebrew's auto-update does not pull third-party taps. Run brew update first so the overseers-desk/od tap fetches the new formula.

Debian / Ubuntu

Download the new .deb below and re-run the install command. apt handles the upgrade transparently when the version is higher:

sudo apt install ./courier_<version>_all.deb

RPM / Fedora

Same shape as install: dnf upgrades when the file's version is higher than the installed one:

sudo dnf install ./courier-<version>-1.noarch.rpm

pip / pipx / uv

pip install --upgrade courier   # if installed via pip
pipx upgrade courier            # if installed via pipx
uv tool upgrade courier         # if installed via uv tool install

🤖 Generated with Claude Code

v1.1.21

A local-index miss on read, search, attachments, and links is now served as an unconfirmed miss, not a confirmed one: the empty result's provenance names that IMAP was not consulted, and --no-cache re-runs the query live. Closes #95.

Install

PyPI (pip or pipx, any platform)

pip install courier            # CLI only
pip install "courier[mcp]"     # CLI plus MCP server mode

For an isolated install that does not touch your system or project environment, use pipx: pipx install courier (or pipx install "courier[mcp]" for MCP mode).

uv (any platform, no install step)

uvx courier search "subject:invoice"

To install permanently: uv tool install courier

Homebrew (all features, macOS and Linux)

brew tap overseers-desk/od
brew install courier

Debian / Ubuntu (CLI-only)

Download the .deb below and install:

sudo apt install ./courier_*_all.deb

RPM / Fedora (CLI-only)

Download the .rpm below and install:

sudo dnf install ./courier-<version>-1.noarch.rpm

Upgrade

Homebrew (macOS / Linux)

brew update
brew upgrade courier

brew upgrade courier alone reports "already installed and up-to-date" because Homebrew's auto-update does not pull third-party taps. Run brew update first so the overseers-desk/od tap fetches the new formula.

Debian / Ubuntu

Download the new .deb below and re-run the install command. apt handles the upgrade transparently when the version is higher:

sudo apt install ./courier_<version>_all.deb

RPM / Fedora

Same shape as install: dnf upgrades when the file's version is higher than the installed one:

sudo dnf install ./courier-<version>-1.noarch.rpm

pip / pipx / uv

pip install --upgrade courier   # if installed via pip
pipx upgrade courier            # if installed via pipx
uv tool upgrade courier         # if installed via uv tool install

🤖 Generated with Claude Code

v1.1.20

read and reply find a message by its Message-ID:

courier --imap work reply --message-id "<abc@example.com>" -b "Thanks." --send

The lookup needs an explicit --imap NAME and runs a live search on that account. It refuses instead of guessing when the search fails, when the server does not honour it, or when the ID sits in several folders; -f then picks the folder.

Text and oneline search output now carry the UID (and oneline the folder), so a hit can be passed straight to read, reply and the other verbs.

The local index is served at any age. Its mtime is reported as provenance.indexed_at, and the caller decides whether that is fresh enough; --no-cache asks for live data. max_staleness_seconds is no longer read. Message bodies are read from disk without consulting the index.

--help shows bracketed TOML table names such as [imap.NAME] intact.

Install

PyPI (pip or pipx, any platform)

pip install courier            # CLI only
pip install "courier[mcp]"     # CLI plus MCP server mode

For an isolated install that does not touch your system or project environment, use pipx: pipx install courier (or pipx install "courier[mcp]" for MCP mode).

uv (any platform, no install step)

uvx courier search "subject:invoice"

To install permanently: uv tool install courier

Homebrew (all features, macOS and Linux)

brew tap overseers-desk/od
brew install courier

Debian / Ubuntu (CLI-only)

Download the .deb below and install:

sudo apt install ./courier_1.1.20_all.deb

RPM / Fedora (CLI-only)

sudo dnf install ./courier-1.1.20-1.noarch.rpm

Upgrade

Homebrew (macOS / Linux)

brew update
brew upgrade courier

brew upgrade courier alone reports "already installed and up-to-date" because Homebrew's auto-update does not pull third-party taps. Run brew update first so the overseers-desk/od tap fetches the new formula.

Debian / Ubuntu

sudo apt install ./courier_1.1.20_all.deb

RPM / Fedora

sudo dnf install ./courier-1.1.20-1.noarch.rpm

pip / pipx / uv

pip install --upgrade courier   # if installed via pip
pipx upgrade courier            # if installed via pipx
uv tool upgrade courier         # if installed via uv tool install

v1.1.19

The Claude Code command installs into the configuration directory the session actually reads: $CLAUDE_CONFIG_DIR when it is set, ~/.claude otherwise.

A machine that carries several Claude Code configuration trees used to take the install in one of them. A session started against any other tree found no courier command and fell back to a raw IMAP path. The installer, the staleness nudge and the version probe now resolve the same directory the session does, so courier install-claude-command registers courier for the session you are in. Run it once per tree.

Install

PyPI (pip or pipx, any platform)

pip install courier            # CLI only
pip install "courier[mcp]"     # CLI plus MCP server mode

For an isolated install that does not touch your system or project environment, use pipx: pipx install courier (or pipx install "courier[mcp]" for MCP mode).

uv (any platform, no install step)

uvx courier search "subject:invoice"

To install permanently: uv tool install courier

Homebrew (all features, macOS and Linux)

brew tap overseers-desk/od
brew install courier

Debian / Ubuntu (CLI-only)

Download the .deb below and install:

sudo apt install ./courier_1.1.19_all.deb

RPM / Fedora (CLI-only)

sudo dnf install ./courier-1.1.19-1.noarch.rpm

Upgrade

Homebrew (macOS / Linux)

brew update
brew upgrade courier

brew upgrade courier alone reports "already installed and up-to-date" because Homebrew's auto-update does not pull third-party taps. Run brew update first so the overseers-desk/od tap fetches the new formula.

Debian / Ubuntu

sudo apt install ./courier_1.1.19_all.deb

RPM / Fedora

sudo dnf install ./courier-1.1.19-1.noarch.rpm

pip / pipx / uv

pip install --upgrade courier   # if installed via pip
pipx upgrade courier            # if installed via pipx
uv tool upgrade courier         # if installed via uv tool install

v1.1.18

What's new

Search correctness across every backend. Gmail-style queries now translate faithfully to plain IMAP and the local cache instead of being sent as literal text that a non-Gmail server rejects into a silent empty result.

• Parentheses group as written, and multi-term OR nests into valid IMAP criteria, so after:2026-07-13 (ticket OR booking OR e-ticket) and from:a OR from:b OR from:c return their matches on any RFC 3501 server.
• Operators a backend cannot honour (has:, label:, filename: on plain IMAP; anything unrecognised) refuse with a clear message and the nearest alternative, instead of silently searching for the literal text and returning nothing.
• Non-ASCII search terms are sent with a UTF-8 charset, so from:josé works on servers that accept it.
• Search failures now appear in the result. A folder that errors or times out is listed in folders_failed, a dead connection reports an error instead of an empty mailbox, and exit codes separate hits (0), a genuine empty result (1), and a failure (2). An empty answer can no longer impersonate a mailbox with no matching mail.

Access, privacy, and delivery honesty:

• The allowed_folders whitelist is enforced on the local-cache and disk read paths, not only on live IMAP.
• A redact policy is honoured wherever a message is copied, exported, or sent, instead of copying an empty placeholder.
• SMTP reports recipients the server refuses, uses CRLF line endings, and sets a connection timeout.
• mark/move/delete/trash verify the UIDs exist and report which matched and which were not found.
• courier watch keeps folder events across its IDLE reissue and backs off correctly on a flaky connection.

---

Install

PyPI (pip or pipx, any platform)

pip install courier            # CLI only
pip install "courier[mcp]"     # CLI plus MCP server mode

For an isolated install that does not touch your system or project environment, use pipx: pipx install courier (or pipx install "courier[mcp]" for MCP mode).

uv (any platform, no install step)

uvx courier search "subject:invoice"

To install permanently: uv tool install courier

Homebrew (all features, macOS and Linux)

brew tap overseers-desk/od
brew install courier

Debian / Ubuntu (CLI-only)

Download the .deb from this release and install:

sudo apt install ./courier_1.1.18_all.deb

RPM / Fedora (CLI-only)

Download the .rpm from this release and install:

sudo dnf install ./courier-1.1.18-1.noarch.rpm

---

Upgrade

Homebrew (macOS / Linux)

brew update
brew upgrade courier

brew upgrade courier alone reports "already installed and up-to-date" because Homebrew's auto-update does not pull third-party taps. Run brew update first so the overseers-desk/od tap fetches the new formula.

Debian / Ubuntu

sudo apt install ./courier_1.1.18_all.deb

RPM / Fedora

sudo dnf install ./courier-1.1.18-1.noarch.rpm

pip / pipx / uv

pip install --upgrade courier   # if installed via pip
pipx upgrade courier            # if installed via pipx
uv tool upgrade courier         # if installed via uv tool install

v1.1.17

What's new

• New search operator msgid: finds a message by its RFC 5322 Message-ID, with rfc822msgid: accepted as a synonym. It works on plain IMAP, on the local cache, and on Gmail: courier search 'msgid:<abc@mail.example.com>'.
• courier search --help and the MCP search tool description now list every operator the parser accepts. The list is rendered from the parser's own tables and pinned by tests, so the help can no longer drift from the behaviour.
• New courier watch verb streams IMAP IDLE folder events as JSON lines, one per event.
• Data-returning commands (search, attachments, links) exit 0 on hits and 1 on zero results, so shell fallback chains like courier search 'from:x' || courier search 'x' work.
• Sending and FCC filing are available as library API, not only through the CLI.
• Typed IMAP errors, capability-aware mutations, and batch UID operations for library users.
• The Claude command now stops and asks when a reply's prior sending identity is no longer configured, instead of picking the closest name.

---

Install

PyPI (pip or pipx, any platform)

pip install courier            # CLI only
pip install "courier[mcp]"     # CLI plus MCP server mode

For an isolated install that does not touch your system or project environment, use pipx: pipx install courier (or pipx install "courier[mcp]" for MCP mode).

uv (any platform, no install step)

uvx courier search "subject:invoice"

To install permanently: uv tool install courier

pipx from GitHub (latest unreleased build)

To track the development version ahead of the latest PyPI release, install straight from the repository:

pipx install "courier[mcp] @ git+https://github.com/overseers-desk/courier"

This installs everything including MCP server mode. For CLI-only (no MCP):

pipx install "git+https://github.com/overseers-desk/courier"

Homebrew (all features, macOS and Linux)

brew tap overseers-desk/od
brew install courier

Debian / Ubuntu (CLI-only)

Download the latest .deb from the Releases page and install:

sudo apt install ./courier_*_all.deb

The .deb provides all CLI commands. The MCP server subcommand (courier mcp) is not supported in the .deb: it requires the mcp Python package, which is not yet available as a Debian package. Users who need MCP mode should install via pipx or Homebrew.

RPM / Fedora (CLI-only)

Download the latest .rpm from the Releases page and install:

sudo dnf install ./courier-<version>-1.noarch.rpm

Upgrade

Homebrew (macOS / Linux)

brew update
brew upgrade courier

brew upgrade courier alone reports "already installed and up-to-date" because Homebrew's auto-update does not pull third-party taps. Run brew update first so the overseers-desk/od tap fetches the new formula.

Debian / Ubuntu

Download the new .deb from the Releases page and re-run the install command. apt handles the upgrade transparently when the version is higher:

sudo apt install ./courier_<version>_all.deb

RPM / Fedora

Same shape as install: dnf upgrades when the file's version is higher than the installed one:

sudo dnf install ./courier-<version>-1.noarch.rpm

pip / pipx / uv

pip install --upgrade courier   # if installed via pip
pipx upgrade courier            # if installed via pipx
uv tool upgrade courier         # if installed via uv tool install

v1.1.16

What's new

This is the first release under the courier name. The project was previously published as mailroom; the PyPI package, binary name, and all documentation now use courier.

• Project renamed from mailroom to courier.
• Package is now available on PyPI as courier (pip install courier).
• PyPI install path added to the installation documentation.
• trash action added to triage/process_email_action.
• delete demoted to expunge-in-place.
• compose --to is now optional, enabling Bcc-only sends.
• Free-form --smtp send refuses when no copy can be filed.

---

Install

PyPI (pip or pipx, any platform)

pip install courier            # CLI only
pip install "courier[mcp]"     # CLI plus MCP server mode

For an isolated install that does not touch your system or project environment, use pipx: pipx install courier (or pipx install "courier[mcp]" for MCP mode).

uv (any platform, no install step)

uvx courier search "subject:invoice"

To install permanently: uv tool install courier

pipx from GitHub (latest unreleased build)

To track the development version ahead of the latest PyPI release, install straight from the repository:

pipx install "courier[mcp] @ git+https://github.com/overseers-desk/courier"

This installs everything including MCP server mode. For CLI-only (no MCP):

pipx install "git+https://github.com/overseers-desk/courier"

Homebrew (all features, macOS and Linux)

brew tap overseers-desk/ot
brew install courier

Debian / Ubuntu (CLI-only)

Download the latest .deb from the Releases page and install:

sudo apt install ./courier_*_all.deb

The .deb provides all CLI commands. The MCP server subcommand (courier mcp) is not supported in the .deb — it requires the mcp Python package which is not yet available as a Debian package. Users who need MCP mode should install via pipx or Homebrew.

RPM / Fedora (CLI-only)

Build from the included spec file:

rpmbuild -ba courier.spec

---

Upgrade

Homebrew (macOS / Linux)

brew update
brew upgrade courier

brew upgrade courier alone reports "already installed and up-to-date" because Homebrew's auto-update does not pull third-party taps. Run brew update first so the overseers-desk/ot tap fetches the new formula.

Debian / Ubuntu

Download the new .deb from the Releases page and re-run the install command. apt handles the upgrade transparently when the version is higher:

sudo apt install ./courier_<version>_all.deb

RPM / Fedora

Same shape as install: dnf upgrades when the file's version is higher than the installed one:

sudo dnf install ./courier-<version>-1.noarch.rpm

pip / pipx / uv

pip install --upgrade courier   # if installed via pip
pipx upgrade courier            # if installed via pipx
uv tool upgrade courier         # if installed via uv tool install

v1.1.15

• compose --to is now optional, enabling Bcc-only sends.
• Free-form --smtp send refuses when no copy can be filed.
• Slash-command: non-ASCII body and subject sent verbatim; failure-mode D4 added.
• Slash-command: description routes by trigger; routing logic reformatted.

Install

Homebrew (macOS / Linux)

brew tap SmartLayer/mailroom https://github.com/SmartLayer/mailroom
brew install mailroom

Debian / Ubuntu

Download the .deb from this release and install:

sudo apt install ./mailroom_1.1.15_all.deb

pipx

pipx install "mailroom[mcp] @ git+https://github.com/SmartLayer/mailroom"

Upgrade

Homebrew

brew update
brew upgrade mailroom

brew upgrade mailroom alone reports "already installed and up-to-date" because Homebrew's auto-update does not pull third-party taps. Run brew update first.

Debian / Ubuntu

sudo apt install ./mailroom_1.1.15_all.deb

pipx / uv

pipx upgrade mailroom
uv tool upgrade mailroom

v1.1.14

reply now defaults to reply-all. Use --no-thread to reply to sender only (replaces the former --reply-all opt-in flag).

Install

Homebrew (macOS / Linux)

brew tap SmartLayer/mailroom https://github.com/SmartLayer/mailroom
brew install mailroom

Debian / Ubuntu

Download the .deb from this release and install:

sudo apt install ./mailroom_1.1.14_all.deb

pipx

pipx install "mailroom[mcp] @ git+https://github.com/SmartLayer/mailroom"

Upgrade

Homebrew

brew update
brew upgrade mailroom

brew upgrade mailroom alone reports "already installed and up-to-date" because Homebrew's auto-update does not pull third-party taps. Run brew update first.

Debian / Ubuntu

sudo apt install ./mailroom_1.1.14_all.deb

pipx / uv

pipx upgrade mailroom
uv tool upgrade mailroom

v1.1.13

What's changed

• mailroom install-claude-command no longer warns about the command being unregistered or dated when it is the subcommand being invoked; the nudge was circular in that context.
• Nudge messages for an unregistered or outdated Claude command file are now phrased as agent directives, instructing the agent to run mailroom install-claude-command and then continue with the user's request.

Install

Homebrew (macOS / Linux)

brew tap SmartLayer/mailroom https://github.com/SmartLayer/mailroom
brew install mailroom

Debian / Ubuntu

sudo apt install ./mailroom_1.1.13_all.deb

pipx / uv

pipx install "mailroom[mcp] @ git+https://github.com/SmartLayer/mailroom"

uvx mailroom --version

Upgrade

Homebrew

brew update
brew upgrade mailroom

brew upgrade mailroom alone reports "already installed and up-to-date" because Homebrew's auto-update does not pull third-party taps. Run brew update first so the SmartLayer/mailroom tap fetches the new formula.

Debian / Ubuntu

sudo apt install ./mailroom_1.1.13_all.deb

RPM / Fedora

sudo dnf install ./mailroom-1.1.13-1.noarch.rpm

pipx / uv

pipx upgrade mailroom        # if installed via pipx
uv tool upgrade mailroom     # if installed via uv tool install