perch

perch by mxRaven

Open source inbox for you, your agent, or your application — in 1 file.

perch is a single-binary IMAP + SMTP server with a POSIX CLI. Run it on a homelab, give an AI agent an inbox, or wire mail into your app — without a public IP, port forwarding, or an MTA to babysit.

Why perch

• 1 file, zero sidecars. A CGO-free Go binary with embedded SQLite and FTS5. No Postfix, Dovecot, Rspamd, or container orchestra.
• No public IP required. Inbound mail arrives over an outbound WebSocket. Works behind NAT, CGNAT, or a homelab router.
• Your storage, your rules. Keep compressed mail in SQLite or offload raw .eml files to S3/R2 while metadata and search stay local.
• Agent-ready CLI. POSIX commands with NDJSON, raw .eml, mbox, Maildir, and real exit codes. Easy to wire into an agent loop.
• Standard protocols. IMAP and authenticated SMTP. Use Thunderbird, Apple Mail, mutt, or your own application client.
• Private by default. Self-hosted mail with zero inbound SMTP ports. mxRaven does not retain your messages.

mxRaven handles the public edge — MX, SPF/DKIM/DMARC, IP reputation, and spam filtering — so perch can stay inside your network. Your mail stays on your disk or bucket.

Use it as

• A personal mailbox. Point any standard mail client at it and keep the data on your hardware.
• An agent inbox. Give an AI agent an address it can search, read, reply to, and attach files to.
• An application mail layer. Provision inboxes for users or services, read via IMAP, and send via SMTP or the CLI.

For agents and harnesses

# Structured context
perch mail search -q 'unseen from:alice' --json

# Full message for RAG or archival
perch mail fetch --uids 42 > message.eml

# Reply with an attachment
perch mail send --to alice@example.com \
  --subject 'Report ready' \
  --body 'See attached.' \
  --attach report.pdf

No browser sessions, no scraping, and no vendor-specific mailbox API. The same commands work against a local perch server or any remote IMAP/SMTP server. See Agents and applications for more patterns.

Documentation

Full documentation, including configuration, S3 storage, TLS, systemd, mail-client recipes, and the generated CLI reference:

https://perch.mxraven.com/

• Installation
• Create an mxRaven API key
• Quickstart
• Configuration
• Mail client
• Agents and applications
• Sending mail
• CLI reference
• Troubleshooting

The documentation sources live in website/content/docs and are published by the Website workflow.

Install

Prebuilt binaries for Linux, macOS, and Windows are published on the releases page. Every release includes SHA-256 checksums, SBOMs, keyless cosign signatures, GitHub build provenance, and manpages.

With Go 1.26.4 or later:

go install github.com/synqronlabs/perch/cmd/perch@latest

Or build from source:

CGO_ENABLED=0 go build -trimpath -o perch ./cmd/perch

See Installation for the release download script, Windows notes, and manpage installation.

Quickstart

# 1. Provision mxRaven and write perch.yaml.
# Create an API key first: https://perch.mxraven.com/docs/getting-started/mxraven-api-key/
export MXRAVEN_API_TOKEN=...
perch setup \
  --config ~/.local/share/perch/perch.yaml \
  --data-dir ~/.local/share/perch \
  --workspace my-workspace \
  --domain example.com \
  --hostname localhost

# 2. Create an account and start the server.
perch account add --config ~/.local/share/perch/perch.yaml --email you@example.com
perch serve --config ~/.local/share/perch/perch.yaml

Point Thunderbird, Apple Mail, or any IMAP client at the loopback listeners:

perch mail works against the same listeners:

perch mail list --server 127.0.0.1:1143 --plaintext --username you@example.com
perch mail send --smtp-server 127.0.0.1:1587 --smtp-plaintext \
  --from you@example.com --to alice@example.com \
  --subject 'Hello' --body 'See attached.' --attach report.pdf

See the Quickstart for LAN TLS, real mail clients, and the first perch mail recipes.

Manpages

Release archives include man/*.1 pages for perch, its subcommands, and the mail client. Install them system-wide with:

sudo install -d /usr/local/share/man/man1
sudo install -m 0644 man/perch*.1 /usr/local/share/man/man1/
sudo mandb

Then use man perch, man perch-mail, or man perch-mail-send. Manpages are generated from the same command tree as --help and the website CLI reference.

Development

make test          # go test ./...
make race          # go test -race ./...
make vet lint
make docs          # regenerate manpages and website CLI reference
make website       # build the Hugo documentation site
make snapshot      # cross-build release archives locally

Generated docs are checked in CI with make docs-check; run make docs after changing commands or flags.

License

Released under the MIT No Attribution (MIT-0) license. See LICENSE.