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:

  --public \
  --acme-email admin@example.com \
  --acme-domain mail.example.com

How it works

• mxRaven stores the raw message in S3.
• perch keeps metadata, flags, and the FTS index in SQLite.
• serve reconciles S3 at startup and every storage.s3.reconcile_every (default 5m).
• perch reconcile forces an immediate scan.
• perch gc --s3-delete removes S3 objects belonging to deleted messages. Without it, tombstones accumulate.

storage.s3.spool can keep a bounded local copy for faster reads and offline access. spool_max_bytes caps that cache; perch gc enforces it.

Key template

storage.s3.key_template must include {{.task.id}}, end in .eml, and identify a mailbox address:

key_template: "perch/{{.mailbox.address}}/{{.task.id}}.eml"

The template must start with storage.s3.prefix so reconciliation lists the same objects that mxRaven writes.