perch 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.

Installation

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

Prebuilt binaries for Linux, macOS, and Windows are published on the releases page. Every release includes SHA-256 checksums, SBOMs, a keyless cosign signature, and GitHub build provenance. See RELEASING.md for verification details.

With Go

If you have Go 1.26.4 or later, go install builds the latest tagged release. CGO is not required.

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

The binary is written to $(go env GOPATH)/bin (usually ~/go/bin). Add that directory to PATH if needed. To pin a version:

perch init

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

Synopsis

perch init [OPTIONS]

Description

init writes a self-contained perch.yaml and initializes the SQLite database without contacting mxRaven. It is intended for local testing or for deployments where mxRaven is provisioned separately.

If –email is set, init also creates the first account and its default mailbox set. Use –self-signed to generate a local TLS certificate for LAN clients.

Notes

The config is written with mode 0600 and the data directory with mode 0700.
–force overwrites an existing configuration.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--data-dir <value>`	data directory
`--hostname <value>`	server hostname (default: “localhost”)
`--email <value>`	first account email
`--name <value>`	first account display name
`--password <value>`	first account password (prompted when empty)
`--self-signed`	generate a self-signed TLS certificate
`--force`	overwrite an existing configuration
`--help, -h`	show help

Examples

perch init --data-dir ~/.local/share/perch --hostname localhost --email you@example.com

perch init --self-signed --hostname mail.lan --email you@example.com

S3 archival

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

If you want bottomless cloud storage, enable S3 mode. mxRaven writes incoming .eml files directly to your bucket via S3_STORE, and perch reconciles the bucket automatically.

export MXRAVEN_API_TOKEN=...
export PERCH_S3_SECRET_KEY=...

perch setup \
 --config ~/.local/share/perch/perch.yaml \
 --data-dir ~/.local/share/perch \
 --workspace my-workspace \
 --domain example.com \
 --hostname mail.example.com \
 --storage s3 \
 --s3-bucket my-mail-archive \
 --s3-region auto \
 --s3-endpoint https://<account>.r2.cloudflarestorage.com \
 --s3-access-key <access-key>

To expose perch directly on a public VPS with standard ports and automatic Let’s Encrypt certificates, add:

systemd service

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

perch serve runs in the foreground, logs to stderr, drains connections on SIGTERM/SIGINT (waiting up to five seconds), and reloads certificate files on SIGHUP, so it maps directly onto a Type=simple unit. It does not fork, write a PID file, implement sd_notify, or support socket activation; do not use Type=notify or socket units.

The examples below use a dedicated perch service account, /etc/perch/perch.yaml, and /var/lib/perch. Adjust paths if your layout differs, and keep data_dir in YAML in sync with StateDirectory and ReadWritePaths.

Create an mxRaven API key

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

perch setup needs an mxRaven API key to provision your workspace. mxRaven uses ZITADEL for identity, so the key is a Personal Access Token (PAT) on a ZITADEL service account.

This is a control-plane token, not a listener API key. perch uses it only during setup to create the domain, listeners, routes, and listener credentials, and never writes it to perch.yaml.

Before you start

You can sign in to the mxRaven dashboard.
You know your workspace slug, for example my-workspace. It is the --workspace value you pass to perch setup.
You have administrator access to that workspace.

1. Open the ZITADEL console

Sign in at https://id.mxraven.com/ui/console with the same account you use for mxRaven. You can also open the dashboard user menu and choose Manage authentication.

Backup and garbage collection

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

perch gc and perch backup are one-shot commands and are safe to run while perch serve is running: SQLite WAL mode allows concurrent readers and writers.

perch reconcile does not need a timer. serve reconciles S3 at startup and every storage.s3.reconcile_every (default 5m).

Backup timer

perch backup refuses to overwrite an existing destination. Use a wrapper to add timestamps and prune old copies. Write /usr/local/bin/perch-backup:

sudo tee /usr/local/bin/perch-backup >/dev/null <<'EOF'
#!/bin/sh
set -eu
stamp=$(date +%Y%m%d-%H%M%S)
/usr/local/bin/perch backup --config /etc/perch/perch.yaml "/var/lib/perch/backups/perch-$stamp.db"
find /var/lib/perch/backups -type f -name 'perch-*.db' -mtime +14 -delete
EOF
sudo chmod 0755 /usr/local/bin/perch-backup

/etc/systemd/system/perch-backup.service:

Configuration

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

perch init and perch setup write YAML with 0600 permissions. The default path is $XDG_CONFIG_HOME/perch/perch.yaml (usually ~/.config/perch/perch.yaml), but production deployments should pass --config explicitly.

data_dir: /var/lib/perch
hostname: mail.example.com

imap:
 addr: 127.0.0.1:1143
 imaps_addr: ""
 allow_plaintext_loopback: true

submission:
 addr: 127.0.0.1:1587
 tls_addr: ""

tls:
 cert_file: ""
 key_file: ""
 acme:
 enabled: false
 email: ""
 domains: []
 http_addr: ":80"

storage:
 mode: sqlite # sqlite | s3
 s3:
 endpoint: ""
 region: ""
 bucket: ""
 prefix: "perch/"
 access_key: ""
 secret_key: ""
 secret_key_env: PERCH_S3_SECRET_KEY
 force_path_style: false
 key_template: "perch/{{.mailbox.address}}/{{.task.id}}.eml"
 reconcile_every: 5m
 spool: false
 spool_max_bytes: 268435456

limits:
 max_connections: 512
 ingest_concurrency: 2
 blob_cache_bytes: 67108864
 max_message_bytes: 26214400
 max_recipients: 100

mxraven:
 submission_host: smtp.mxraven.email
 submission_port: 587
 notification_url: wss://notifications.mxraven.com
 feedback_url: https://api.mxraven.com
 listeners:
 - id: ...
 kind: mta
 key_prefix: ...
 key_secret_env: PERCH_MXRAVEN_KEY_SECRET
 consumer: notify-...
 - id: ...
 kind: submission
 key_prefix: ...
 key_secret_env: PERCH_MXRAVEN_SUBMISSION_KEY_SECRET

Secrets can be inline (protected by file permissions) or referenced through environment variables. The mxRaven control-plane token is used only by perch setup and is never written to the config.

perch setup

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

Synopsis

perch setup [OPTIONS]

Description

setup calls the mxRaven control plane to provision a workspace domain, MTA listener, optional submission listener, API keys, inbound route, sending-domain policy, and optional S3_STORE rule. It then writes perch.yaml.

The control-plane token is used only during setup and is never written to the config. Listener and S3 secrets are written inline unless you replace them with *_env references.

Quickstart

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

This quickstart provisions mxRaven, creates a local account, starts perch, and connects a mail client.

1. Provision mxRaven and generate config

First create an mxRaven API key, then export it. With the token, perch setup configures your domain, inbound route, submission listener, spam/auth rules, and writes perch.yaml:

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

Publish the DNS records printed by the wizard, or pass --wait to wait until DNS verifies.

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.

perch serve

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

Synopsis

perch serve [OPTIONS]

Description

serve runs in the foreground and starts the configured IMAP, IMAPS, submission, and SMTPS listeners plus the mxRaven WebSocket consumer and S3 reconciler.

It logs to stderr, drains connections on SIGTERM/SIGINT for up to five seconds, and reloads certificate files on SIGHUP when tls.cert_file and tls.key_file are set. It does not fork, write a PID file, or support socket activation.

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:

perch account

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

Synopsis

perch account [OPTIONS] COMMAND

Description

Manage local mailbox accounts. Creating an account also creates the default mailbox set: INBOX, Sent, Drafts, Trash, Junk, and Archive.

Notes

Passwords are hashed with Argon2id.
Account changes are written to SQLite and apply without restarting serve.

Options

Option	Description
`--help, -h`	show help

Commands

Command	Description
perch account add	create an account
perch account list	list accounts
perch account passwd	change an account password
perch account disable	disable an account
perch account enable	enable an account

Examples

perch account add --email you@example.com

perch account list

perch account passwd --email you@example.com

perch account add

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

Synopsis

perch account add [OPTIONS]

Description

Create an account, its primary address, and default mailboxes in one transaction. If –password is omitted, perch prompts on a terminal.

Notes

The account is enabled immediately.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--email <value>`	account email
`--name <value>`	display name
`--password <value>`	password (prompted when empty)
`--help, -h`	show help

Examples

perch account add --email you@example.com --name 'Your Name'

perch account list

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

Synopsis

perch account list [OPTIONS]

Description

Print account ID, primary address, display name, disabled state, and creation time.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--help, -h`	show help

Examples

perch account list

Troubleshooting

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

Run the doctor

perch doctor --config /etc/perch/perch.yaml

perch doctor checks SQLite integrity and FTS5, TLS certificate files, DNS, S3 connectivity, and mxRaven listeners. Run it as the same user that runs perch serve.

Mail clients cannot connect

Check the listener addresses in perch.yaml.
Plaintext is only allowed on loopback. Use TLS or STARTTLS from other hosts.
For the quickstart defaults, IMAP is 127.0.0.1:1143 and submission is 127.0.0.1:1587.
If you generated a self-signed certificate, the client must trust it or you must explicitly allow the certificate.
Off-loopback connections always require TLS.

`perch mail` cannot connect

For an explicit loopback address, add --plaintext or --smtp-plaintext.
Config-derived loopback listeners select plaintext automatically.
For remote servers, use imaps://host / smtps://host or imap://host / smtp://host for STARTTLS.
Use --ca-file for a private CA and --insecure only for testing.

Authentication fails

perch mail uses the account password, not the mxRaven API key.
perch account passwd changes the local account password.
Check authlimit logs if logins are being throttled.
For submission, the From address must be an account address, alias, or authorized plus-address.

Messages are delivered but not visible locally

In S3 mode, check perch reconcile and the S3 prefix/key template.
The key template must start with storage.s3.prefix.
perch gc --s3-delete removes objects for deleted messages.
Check perch outbound list for submission status and SMTP errors.

S3 errors

Verify the endpoint, region, bucket, access key, and secret.
secret_key_env names the environment variable; systemd reads it from EnvironmentFile.
Run perch reconcile to force a scan.
Check that mxRaven’s S3_STORE rule writes to the same bucket and prefix.

systemd service exits

Run journalctl -u perch -f.
ExecReload sends SIGHUP. Only keep it when tls.cert_file and tls.key_file are configured; otherwise SIGHUP terminates the process.
ProtectHome/ProtectSystem must allow the configured data_dir.
The service user must be able to read the config and write the data dir.

Versions and releases

perch version
gh release view --repo synqronlabs/perch

Manpages are installed with release archives; perch <command> --help always reflects the installed binary.

perch account passwd

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

Synopsis

perch account passwd [OPTIONS]

Description

Replace the account’s Argon2id password hash. Existing IMAP and submission sessions are not terminated.

Notes

Prompts for the new password when –password is omitted.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--email <value>`	account email
`--password <value>`	new password (prompted when empty)
`--help, -h`	show help

Examples

perch account passwd --email you@example.com

perch account disable

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

Synopsis

perch account disable [OPTIONS]

Description

Disable prevents new IMAP and submission logins without deleting messages. Use enable to reverse it.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--email <value>`	account email
`--help, -h`	show help

Examples

perch account disable --email you@example.com

perch account enable

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

Synopsis

perch account enable [OPTIONS]

Description

Re-enable a previously disabled account.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--email <value>`	account email
`--help, -h`	show help

Examples

perch account enable --email you@example.com

perch alias

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

Synopsis

perch alias [OPTIONS] COMMAND

Description

Aliases map additional addresses to an account. A catch-all is stored as *@domain and accepts any local part for that domain.

Notes

Plus-addressing (user+tag@domain) works without an explicit alias.

Options

Option	Description
`--help, -h`	show help

Commands

Command	Description
perch alias add	add an alias or catch-all
perch alias remove	remove an alias
perch alias list	list aliases for an account

Examples

perch alias add --account you@example.com --address sales@example.com

perch alias add --account you@example.com --catch-all --address example.net

perch alias list --account you@example.com

perch alias add

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

Synopsis

perch alias add [OPTIONS]

Description

Add an exact address alias, or use –catch-all with a domain to route all unmatched addresses at that domain to the account. The address must not already belong to another account.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--account <value>`	account email
`--address <value>`	alias address or domain
`--catch-all`	route all unmatched addresses at –address
`--help, -h`	show help

Examples

perch alias add --account you@example.com --address sales@example.com

perch alias add --account you@example.com --catch-all --address example.net

perch alias remove

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

Synopsis

perch alias remove [OPTIONS]

Description

Remove an alias address or catch-all from the address table. Messages already delivered are unaffected.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--address <value>`	alias address
`--help, -h`	show help

Examples

perch alias remove --address sales@example.com

perch alias list

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

Synopsis

perch alias list [OPTIONS]

Description

List the addresses and catch-all domains assigned to an account.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--account <value>`	account email
`--help, -h`	show help

Examples

perch alias list --account you@example.com

perch mailbox

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

Synopsis

perch mailbox [OPTIONS] COMMAND

Description

Inspect mailbox metadata stored in SQLite. This reads the local database directly and does not require serve to be running.

Notes

The mailbox command is local-only; use perch mail list for a remote IMAP server.

Options

Option	Description
`--help, -h`	show help

Commands

Command	Description
perch mailbox list	list mailboxes for an account

Examples

perch mailbox list --account you@example.com

perch mailbox list

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

Synopsis

perch mailbox list [OPTIONS]

Description

Print each mailbox name, special-use attribute, and subscription state for an account.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--account <value>`	account email
`--help, -h`	show help

Examples

perch mailbox list --account you@example.com

perch mail

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

Synopsis

perch mail [OPTIONS] COMMAND

Description

The mail command group is a scriptable IMAP and SMTP client. list, search, and fetch talk IMAP; send talks SMTP; caps prints the SMTP EHLO extensions of a submission server.

Credentials and TLS flags are shared. IMAP flags are local to list/search/fetch; SMTP flags are local to send/caps.

Notes

If –server or –smtp-server is omitted, the matching listener is taken from –config.
Use –plaintext or –smtp-plaintext only for trusted loopback listeners.
Password sources: –password-file, –password-stdin, PERCH_IMAP_PASSWORD, or an interactive prompt.

Options

Option	Description
`--username, -u <value>`	account username (env PERCH_IMAP_USER)
`--password <value>`	account password (prefer PERCH_IMAP_PASSWORD or –password-file)
`--password-file <value>`	read the account password from a file
`--password-stdin`	read the account password from stdin
`--timeout <value>`	connection timeout (default: 30s)
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--help, -h`	show help

Commands

Command	Description
perch mail list	list mailboxes
perch mail search	search message metadata
perch mail fetch	fetch raw messages
perch mail send	compose and send a message
perch mail caps	show the SMTP extensions advertised by a submission server

Examples

perch mail list --server imaps://mail.example.com --username you@example.com

perch mail search -q 'unseen from:alice' --json

perch mail fetch -q 'from:alice' --format mbox > alice.mbox

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

Environment

Variable	Purpose
`PERCH_IMAP_USER`	default account username
`PERCH_IMAP_PASSWORD`	account password

perch mail list

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

Synopsis

perch mail list [OPTIONS]

Description

List mailboxes on the selected IMAP server. The default output is a table; –json writes one JSON object per line.

Aliases: ls.

Notes

–subscribed requires server support for LIST-EXTENDED.

Options

Option	Description
`--username, -u <value>`	account username (env PERCH_IMAP_USER)
`--password <value>`	account password (prefer PERCH_IMAP_PASSWORD or –password-file)
`--password-file <value>`	read the account password from a file
`--password-stdin`	read the account password from stdin
`--timeout <value>`	connection timeout (default: 30s)
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--json`	write one JSON object per mailbox
`--subscribed`	only list subscribed mailboxes
`--server, -s <value>`	IMAP server (imaps://host, imap://host, or host[:port]); defaults from –config
`--plaintext`	connect to IMAP without TLS (use only on trusted networks)
`--starttls`	require STARTTLS for IMAP
`--insecure`	skip IMAP TLS certificate verification
`--ca-file <value>`	PEM CA bundle used to verify the IMAP server certificate
`--help, -h`	show help

Examples

perch mail list --server 127.0.0.1:1143 --plaintext --username you@example.com

perch mail list --server imaps://mail.example.com --username you@example.com --json

Environment

Variable	Purpose
`PERCH_IMAP_USER`	default account username
`PERCH_IMAP_PASSWORD`	account password

perch mail search

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

Synopsis

perch mail search [OPTIONS]

Description

Search a mailbox with IMAP SEARCH and print metadata for matching messages. Results are newest first by default; –reverse flips the order.

Bare query words search the message text. Supported keys: from, to, cc, bcc, subject, body, text, header:Name=Value, since, before, on, sent-since, sent-before, sent-on, seen, unseen, answered, unanswered, flagged, unflagged, deleted, undeleted, draft, undraft, larger, smaller, uid, flag/keyword, and unflag/unkeyword.

perch mail fetch

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

Synopsis

perch mail fetch [OPTIONS]

Description

Fetch complete RFC 5322 messages selected by UID, query, or –all. The default format writes one .eml per message when –dest is a directory, or raw bytes to stdout for a single message.

mbox writes a standard mbox stream. maildir creates tmp/new/cur and preserves message flags.

Aliases: get.

Notes

BODY.PEEK[] is used unless –mark-seen is set.
Writing eml to stdout requires exactly one message.
–dest is a directory for eml/maildir and a file for mbox.
Existing files are not overwritten unless –overwrite is passed.

Options

Option	Description
`--username, -u <value>`	account username (env PERCH_IMAP_USER)
`--password <value>`	account password (prefer PERCH_IMAP_PASSWORD or –password-file)
`--password-file <value>`	read the account password from a file
`--password-stdin`	read the account password from stdin
`--timeout <value>`	connection timeout (default: 30s)
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--mailbox, -m <value>`	mailbox to fetch from (default: “INBOX”)
`--query, -q <value>`	search expression
`--uids <value>`	explicit UID set, for example 1,3:5,10:*
`--all`	fetch every message in the mailbox
`--limit, -n <value>`	maximum messages (0 means unlimited) (default: 0)
`--format, -f <value>`	eml, mbox, or maildir (default: “eml”)
`--dest, -d, -o <value>`	destination directory (eml/maildir) or file (mbox); default stdout
`--mark-seen`	let the server set \Seen (default uses BODY.PEEK)
`--overwrite`	overwrite an existing eml/mbox destination
`--reverse`	fetch newest first instead of oldest first
`--server, -s <value>`	IMAP server (imaps://host, imap://host, or host[:port]); defaults from –config
`--plaintext`	connect to IMAP without TLS (use only on trusted networks)
`--starttls`	require STARTTLS for IMAP
`--insecure`	skip IMAP TLS certificate verification
`--ca-file <value>`	PEM CA bundle used to verify the IMAP server certificate
`--help, -h`	show help

Examples

perch mail fetch --uids 42 > message.eml

perch mail fetch -q 'from:alice' --format mbox > alice.mbox

perch mail fetch -q 'unseen' --format maildir --dest ~/Mail

perch mail fetch -q 'unseen' --dest ./messages

Environment

Variable	Purpose
`PERCH_IMAP_USER`	default account username
`PERCH_IMAP_PASSWORD`	account password

perch mail send

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

Synopsis

perch mail send [OPTIONS]

Description

Compose a MIME message and submit it through SMTP. Text and HTML bodies are combined as multipart/alternative; attachments wrap the result in multipart/mixed.

Bodies come from –body/–body-file and –html-body/–html-file, or stdin when it is not a terminal. Attachments are base64 encoded and content types are detected from the file extension or contents.

Notes

Bodies are quoted-printable unless –8bitmime is set; attachments are base64.
SMTPUTF8 is detected from non-ASCII envelope addresses and extra headers; force it with –smtputf8.
Bcc recipients are envelope-only and never appear in headers.
SIZE is sent automatically and checked against the server’s advertised limit.

Options

Option	Description
`--username, -u <value>`	account username (env PERCH_IMAP_USER)
`--password <value>`	account password (prefer PERCH_IMAP_PASSWORD or –password-file)
`--password-file <value>`	read the account password from a file
`--password-stdin`	read the account password from stdin
`--timeout <value>`	connection timeout (default: 30s)
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--from <value>`	sender address (default: –username)
`--to <value>...`	recipient address or list; repeatable
`--cc <value>...`	Cc recipient address or list; repeatable
`--bcc <value>...`	Bcc recipient address or list; repeatable
`--reply-to <value>...`	Reply-To address or list; repeatable
`--subject, -s <value>`	message subject
`--body <value>`	plain-text body
`--body-file <value>`	read the plain-text body from a file (use - for stdin)
`--html-body <value>`	HTML body
`--html-file <value>`	read the HTML body from a file (use - for stdin)
`--attach, -a <value>...`	attach a file; repeatable
`--header, -H <value>...`	add an extra header (Name: Value); repeatable
`--in-reply-to <value>`	Message-ID being replied to
`--references <value>`	space-separated Message-IDs for References
`--8bitmime`	send UTF-8 text with BODY=8BITMIME
`--smtputf8`	force SMTPUTF8 (usually detected automatically)
`--dry-run, -n`	write the composed message to stdout without sending
`--verbose, -v`	print SMTP capabilities and delivery details to stderr
`--smtp-server, -S <value>`	SMTP submission server (smtps://host, smtp://host, or host[:port]); defaults from –config
`--smtp-plaintext`	connect to SMTP without TLS (use only on trusted networks)
`--smtp-starttls`	require STARTTLS for SMTP
`--smtp-implicit-tls`	use implicit TLS for SMTP (usually port 465)
`--smtp-insecure`	skip SMTP TLS certificate verification
`--smtp-ca-file <value>`	PEM CA bundle used to verify the SMTP server certificate
`--help, -h`	show help

Examples

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

echo 'Body from stdin' | perch mail send --from you@example.com \
 --to alice@example.com --subject Hello

perch mail send --from you@example.com --to alice@example.com \
 --subject Report --body-file message.txt --html-file message.html \
 --attach report.pdf

perch mail send ... --dry-run > message.eml

Environment

Variable	Purpose
`PERCH_IMAP_USER`	default account username and sender
`PERCH_IMAP_PASSWORD`	account password

perch mail caps

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

Synopsis

perch mail caps [OPTIONS]

Description

Connect to the configured submission server, perform EHLO, and print the advertised extensions. No message is sent and no credentials are used.

Aliases: capabilities.

Notes

The local perch relay advertises PIPELINING, 8BITMIME, ENHANCEDSTATUSCODES, SIZE, SMTPUTF8, STARTTLS, and AUTH on loopback or TLS.
It does not expose DSN, CHUNKING, BINARYMIME, REQUIRETLS, or DELIVERBY.

Options

Option	Description
`--username, -u <value>`	account username (env PERCH_IMAP_USER)
`--password <value>`	account password (prefer PERCH_IMAP_PASSWORD or –password-file)
`--password-file <value>`	read the account password from a file
`--password-stdin`	read the account password from stdin
`--timeout <value>`	connection timeout (default: 30s)
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--smtp-server, -S <value>`	SMTP submission server (smtps://host, smtp://host, or host[:port]); defaults from –config
`--smtp-plaintext`	connect to SMTP without TLS (use only on trusted networks)
`--smtp-starttls`	require STARTTLS for SMTP
`--smtp-implicit-tls`	use implicit TLS for SMTP (usually port 465)
`--smtp-insecure`	skip SMTP TLS certificate verification
`--smtp-ca-file <value>`	PEM CA bundle used to verify the SMTP server certificate
`--help, -h`	show help

Examples

perch mail caps

perch mail caps --smtp-server smtp.mxraven.email:587

perch doctor

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

Synopsis

perch doctor [OPTIONS]

Description

Run integrity and connectivity checks for SQLite/FTS5, TLS certificate files, DNS, S3, and configured mxRaven listeners. The command exits non-zero when a check fails.

Notes

Run as the same user that runs serve so file permissions match.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--help, -h`	show help

Examples

perch doctor --config /etc/perch/perch.yaml

perch backup

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

Synopsis

perch backup [OPTIONS] <destination.db>

Description

Use SQLite’s online backup API to write a consistent copy while serve is running. The destination must not already exist.

Notes

Safe alongside serve because SQLite WAL mode allows concurrent readers and writers.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--help, -h`	show help

Examples

perch backup --config /etc/perch/perch.yaml /var/lib/perch/backups/perch-$(date +%F).db

perch reconcile

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

Synopsis

perch reconcile [OPTIONS]

Description

Scan the configured S3 bucket and bind objects written by mxRaven to local message metadata. Requires storage.mode=s3.

Notes

serve runs this at startup and every storage.s3.reconcile_every (default 5m).

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--help, -h`	show help

Examples

perch reconcile --config /etc/perch/perch.yaml

perch gc

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

Synopsis

perch gc [OPTIONS]

Description

Remove orphaned local blobs, dead letters older than –dead-letter-age, enforce the S3 spool limit, and optionally delete S3 objects for deleted messages. An incremental vacuum runs by default.

Notes

–s3-delete is ignored in SQLite mode.
Without –s3-delete, S3 tombstones accumulate.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--dry-run`	report what would be removed
`--s3-delete`	delete S3 objects for deleted messages
`--dead-letter-age <value>`	delete dead letters older than this (default: 720h0m0s)
`--vacuum`	run incremental vacuum after cleanup
`--spool`	enforce storage.s3.spool_max_bytes
`--help, -h`	show help

Examples

perch gc --config /etc/perch/perch.yaml --dry-run

perch gc --config /etc/perch/perch.yaml --s3-delete

perch outbound

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

Synopsis

perch outbound [OPTIONS] COMMAND

Description

Inspect the outbound table populated by the submission relay. It shows acceptance and later delivery attempts reported by mxRaven.

Options

Option	Description
`--help, -h`	show help

Commands

Command	Description
perch outbound list	list submitted messages

Examples

perch outbound list --account you@example.com

perch outbound list

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

Synopsis

perch outbound list [OPTIONS]

Description

Print recent outbound submissions, optionally filtered by account. –limit defaults to 100.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--account <value>`	filter by account email
`--limit <value>`	maximum rows (default: 100)
`--help, -h`	show help

Examples

perch outbound list --limit 20

perch version

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

Synopsis

perch version [OPTIONS]

Description

Print the version embedded at build time, or the module version for go install builds.

Options

Option	Description
`--help, -h`	show help

Examples

perch version

perch

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

Synopsis

perch [OPTIONS] COMMAND

Description

perch runs a local IMAP server and authenticated submission endpoint, backed by mxRaven for inbound MX, outbound delivery, SPF/DKIM/DMARC, IP reputation, and spam filtering.

Messages are stored in SQLite or offloaded to S3. The same binary provides administrative commands and a scriptable mail client for IMAP and SMTP.

Notes

Run perch help <command> or see the per-command manpages for details.
The default configuration path is $XDG_CONFIG_HOME/perch/perch.yaml.
perch does not need a public IP, port forwarding, or inbound SMTP ports.

Options

Option	Description
`--help, -h`	show help
`--version, -v`	print the version

Commands

Command	Description
perch init	create a local configuration and optional first account
perch setup	create the mxRaven domain, listeners, keys, and routes
perch serve	run IMAP, submission, and the notification consumer
perch account	add, list, password, disable, or enable accounts
perch alias	manage address aliases and catch-all domains
perch mailbox	list mailboxes for an account
perch mail	list, search, fetch, and send mail
perch doctor	check the database, TLS, S3, and mxRaven connectivity
perch backup	write a consistent SQLite backup
perch reconcile	force one S3 bucket reconciliation pass
perch gc	remove orphan blobs, old dead letters, and S3 tombstones
perch outbound	list submitted messages and delivery status
perch version	print the version

Examples

perch setup --workspace my-workspace --domain example.com --hostname localhost

perch account add --email you@example.com

perch serve --config ~/.local/share/perch/perch.yaml

perch mail list --server 127.0.0.1:1143 --plaintext --username you@example.com

perch on perch docs

Fetching mail

Formats

Installation

With Go

perch init

Synopsis

Description

Notes

Options

Examples

See also

S3 archival

systemd service

Create an mxRaven API key

Before you start

1. Open the ZITADEL console

Backup and garbage collection

Backup timer

Configuration

perch setup

Synopsis

Description

Quickstart

1. Provision mxRaven and generate config

Sending mail

Bodies

perch serve

Synopsis

Description

Agents and applications

Why use perch for an agent

Patterns

One mailbox per agent

perch account

Synopsis

Description

Notes

Options

Commands

Examples

See also

perch account add

Synopsis

Description

Notes

Options

Examples

See also

perch account list

Synopsis

Description

Options

Examples

See also

Troubleshooting

Run the doctor

Mail clients cannot connect

perch mail cannot connect

Authentication fails

Messages are delivered but not visible locally

S3 errors

systemd service exits

Versions and releases

perch account passwd

Synopsis

Description

Notes

Options

Examples

See also

perch account disable

Synopsis

Description

Options

Examples

See also

perch account enable

Synopsis

Description

`perch mail` cannot connect