Mail client on perch docs

Fetching mail

Mon, 01 Jan 0001 00:00:00 +0000

perch mail fetch writes raw RFC 5322 messages to stdout, files, an mbox stream, or a Maildir.

# One raw message on stdout.
perch mail fetch --server imaps://mail.example.com --username you@example.com \
 --uids 42 > message.eml

# An mbox stream for formail, procmail, or archival.
perch mail fetch --server imaps://mail.example.com --username you@example.com \
 --query 'from:alice' --format mbox > alice.mbox

# One .eml file per message.
perch mail fetch --server imaps://mail.example.com --username you@example.com \
 --query 'unseen' --dest ./messages

# Maildir, preserving flags.
perch mail fetch --server imaps://mail.example.com --username you@example.com \
 --query 'from:alice' --format maildir --dest ~/Mail

Formats

Format	Destination	Notes
`eml` (default)	stdout for one message, or a directory	Writes `<uid>.eml` per message
`mbox`	stdout or a file	Escapes `From` lines and separates messages
`maildir`	a Maildir root	Creates `tmp/`, `new/`, `cur/`; preserves flags

--dest is a directory for eml and maildir, and a file for mbox. Existing files are not overwritten unless --overwrite is passed.

Sending mail

Mon, 01 Jan 0001 00:00:00 +0000

perch mail send composes a MIME message and submits it through the SMTP submission listener.

# Simple text message.
perch mail send --from you@example.com --to alice@example.com \
 --subject 'Hello' --body 'Hi Alice'

# Read the body from stdin.
echo 'Hi Alice' | perch mail send --from you@example.com \
 --to alice@example.com --subject 'Hello'

# Attachments, Cc/Bcc, and both text and HTML bodies.
perch mail send \
 --from you@example.com \
 --to 'Alice <alice@example.com>' \
 --cc bob@example.net \
 --bcc audit@example.net \
 --subject 'Quarterly report' \
 --body-file message.txt \
 --html-file message.html \
 --attach report.pdf \
 --attach chart.png

# Compose and inspect the raw message without sending it.
perch mail send --from you@example.com --to alice@example.com \
 --subject 'Draft' --body 'Hello' --dry-run > message.eml

Bodies

The body is read from --body, --body-file, --html-body, --html-file, or stdin when stdin is not a terminal.

Agents and applications

Mon, 01 Jan 0001 00:00:00 +0000

perch is a normal mail server with a scriptable interface. That makes it useful anywhere a program needs an inbox but you do not want to build or rent a vendor-specific mailbox API.

Why use perch for an agent

Standard email. Agents get a real address that can receive from and send to the outside world.
POSIX CLI. Search, read, reply, and attach files with commands that work in a shell, a tool call, or a cron job.
Structured output. --json emits NDJSON, one object per message.
Raw messages. fetch writes the complete RFC 5322 message for RAG, summarization, or archival.
Local or remote. The same commands work against a local perch server or any remote IMAP/SMTP server.
No public IP. perch can sit behind NAT or CGNAT while mxRaven handles the public mail edge.

Patterns

One mailbox per agent

Give each agent its own account or alias so its context and credentials are isolated: