Aegis documentation

#Cube: mail

The facade over the virtual mail data: domains, mailboxes, aliases, forwards and storage. It owns no daemon and generates no configuration — Postfix and Dovecot read the same database tables, so every change here is live.

In the panel: Mail → Domains; mailboxes and aliases live on the domain page. Every write there is a task.

#Configuration

toml
[mail]hostname = ""                     # mail host name, used by dovecot/postfixdomain = ""                       # SRS domain and mail originvmail_uid = 5000vmail_gid = 5000vmail_base = "/aegis/data/mail"data_dir = "/aegis/data/mail"[mail.quota]default_bytes = 1073741824        # 1 GiB for new mailboxesmax_bytes = 10737418240           # 10 GiB ceiling per mailbox[mail.database]host = "127.0.0.1"user = "aegis_mail"password = ""                     # generated once, stored in server.tomlname = "aegis_mail"sqlite_path = "/aegis/data/mail/mail.sqlite3"
KeyDefaultMeaning
mail.hostnameemptymyhostname for Postfix, certificate name for IMAPS
mail.domainemptymydomain and the SRS domain
mail.vmail_uid, mail.vmail_gid5000owner of every maildir
mail.vmail_base/aegis/data/mailroot of the mailbox tree
mail.quota.default_bytes1073741824quota applied when none is given
mail.quota.max_bytes10737418240value written into aegis_domains.max_quota_bytes
mail.database.*see abovewhere the mail schema lives

Per-domain and per-mailbox values are rows, not keys: quotas, limits and the catch-all address live in aegis_domains (see schema.md). The domain created automatically by mail configure is setup.primary_domain.

#Files

text
<mail.vmail_base>/└── <domain>/    └── <local_part>/        ├── cur/        ├── new/        └── tmp/

Mailbox directories are owned by <mail.vmail_uid>:<mail.vmail_gid> (5000 by default), the numeric ids both daemons are configured with.

#Commands

bash
aegis cubes mail configure                  # create the mail tree, report stateaegis cubes mail validateaegis cubes mail reload                     # "nothing to reload", by designaegis cubes mail domains listaegis cubes mail domains show example.comaegis cubes mail domains add example.com --quota BYTES --max-mailboxes Naegis cubes mail domains set example.com --quota BYTES --max-mailboxes Naegis cubes mail domains enable example.comaegis cubes mail domains disable example.comaegis cubes mail domains remove example.comaegis cubes mail domains catch-all example.com postmaster@example.comaegis cubes mail domains catch-all example.com          # clear itaegis cubes mail mailboxes list --domain example.comaegis cubes mail mailboxes show sales@example.comaegis cubes mail mailboxes add postmaster@example.com --password 'secret123'aegis cubes mail mailboxes add sales@example.com --password 'secret123' --quota 5368709120aegis cubes mail mailboxes add postmaster@a.com postmaster@b.com     --password 'secret123'                # one mailbox per address, one passaegis cubes mail mailboxes password sales@example.com --password 'new-secret'aegis cubes mail mailboxes quota sales@example.com 2147483648aegis cubes mail mailboxes disable sales@example.comaegis cubes mail mailboxes enable sales@example.comaegis cubes mail mailboxes remove sales@example.com              # row onlyaegis cubes mail mailboxes remove sales@example.com --purge --yes  # + maildiraegis cubes mail aliases listaegis cubes mail aliases add info@example.com sales@example.comaegis cubes mail aliases remove info@example.comaegis cubes mail forwards listaegis cubes mail forwards add sales@example.com person@gmail.comaegis cubes mail forwards add sales@example.com person@gmail.com --no-copyaegis cubes mail forwards remove sales@example.comaegis cubes mail relocated listaegis cubes mail relocated add old@example.com new@example.comaegis cubes mail relocated remove old@example.comaegis cubes mail tls listaegis cubes mail tls set example.org encryptaegis cubes mail tls remove example.orgaegis cubes mail storage usageaegis cubes mail storage list --limit N     # per mailbox, biggest firstaegis cubes mail storage purge sales@example.com --yesaegis cubes mail demo prepare --domain inhive.dev --email demo@inhive.devaegis cubes mail demo run --to paul.cocis87@gmail.com --subject TEXTaegis cubes mail expose

Every table behind this is documented in schema.md.

#Demo

demo prepare builds a complete hook test bed outside the platform tree (/var/aegis/demo, overridable with mail.demo.dir):

text
/var/aegis/demo/├── demo-php-hook.php      inbound handler (logs the envelope)├── demo-python-hook.py    outbound handler (same log)├── account.json           demo address and its password (0600)└── logs/    ├── hooks.log          one line per message, written by the pipe user    └── <ts>-<pid>-<hook>.eml   the raw message, headers and body

It also creates the domain and the mailbox when they are missing, and registers two hooks (demo-in inbound, demo-out outbound) that append to logs/hooks.log and restart Postfix. Running prepare again keeps the account password and updates the hooks.

demo run sends one message through submission (AUTH as the demo address), so the whole path runs: SMTP AUTH, queue, OpenDKIM, both hook directions, then the real delivery:

bash
aegis cubes mail demo prepare --domain inhive.dev --email demo@inhive.devaegis cubes mail demo run --to paul.cocis87@gmail.comtail -f /var/aegis/demo/logs/hooks.log# 2026-11-16T09:12:03 hook=demo-out dir=outbound from=demo@inhive.dev to=paul.cocis87@gmail.com# 2026-11-16T09:12:41 hook=demo-in  dir=inbound  from=paul.cocis87@gmail.com to=demo@inhive.dev

The handlers receive the whole message on stdin, which is why every run leaves an .eml next to the log: it is the exact copy Postfix handed to the pipe.

prepare sets the password of an existing demo mailbox when account.json is missing, because the plain password cannot be read back from the database.

#Domains

A domain row is what makes Postfix accept mail for a name: the domain map reads aegis_domains on every lookup, so adding one needs no reload. remove deletes the mailboxes and, because aliases and forwards are plain address strings with no foreign key, also the rows whose address ends in @<domain>.

catch-all sets aegis_domains.catch_all. The alias map is an exact lookup, so the generated query has a second branch:

sql
SELECT destination FROM aegis_mail_forwarding WHERE address = '%s'UNIONSELECT catch_all FROM aegis_domainsWHERE domain = <domain part of '%s'> AND catch_all IS NOT NULL AND active

UNION (not UNION ALL) matters: an address that is both an alias and covered by the catch-all must resolve once, not twice.

#Mailboxes

mailboxes add:

  • validates the address ([a-z0-9._+-], length limits, existing domain);
  • hashes the password with SHA512-CRYPT (openssl passwd -6). Dovecot 2.4
  • refuses MD5-CRYPT unless weak schemes are enabled;

  • creates <vmail_base>/<domain>/<local> with cur, new, tmp and hands it
  • to the mail uid;

  • inserts the row with the maildir path, the quota and SHA512-CRYPT;
  • defaults the quota to [mail.quota] default_bytes.
  • mailboxes remove deletes the row and leaves the maildir on disk — deleting someone's mail is not something a metadata command should do.

    disable sets active = false: Postfix stops accepting mail for the address (the mailbox map filters on active) and Dovecot refuses authentication.

    #Aliases and forwards

  • alias (aegis_aliases) — one row per source, a single destination.
  • forward (aegis_forwards) — a destination list per source, each row with
  • keep_local. keep_local = true means "deliver a copy here and send one to the destination", which the schema view turns into destination,address.

    Both end up in the same Postfix alias map through aegis_mail_forwarding.

    #Quotas

    Quota is stored per mailbox (quota_bytes), with per-domain defaults in aegis_domains.default_quota_bytes and the global default in [mail.quota] default_bytes / max_bytes. Postfix does not enforce it: Dovecot does, because mail is delivered over LMTP.

    #Relocated addresses

    relocated add records a move; Postfix answers 551 User not local; please try <destination> for that address, so senders learn the new one. The rows are read through the relocated_maps map that postfix configure already renders.

    #Outbound TLS policy

    tls set <domain> <policy> writes aegis_tls_policy, which Postfix reads through smtp_tls_policy_maps. Policies are the Postfix ones: may, encrypt, secure, verify, none.

    #Storage

    bash
    aegis cubes mail storage usagemail: 3 mailboxes 1.2G under /aegis/data/mailaegis cubes mail storage purge sales@example.com --yesmail: purged 412 messages from sales@example.com

    Usage is measured with du -sk per maildir — the filesystem is the truth, not the database. purge deletes the messages in new, cur and tmp and keeps the directory structure and the Dovecot indexes; without --yes it refuses to run.

    #expose

    bash
    aegis cubes mail exposecube           mailinstalled      n/aconfiguration  /aegis/data/mailmail tree      /aegis/data/mailmail uid       5000:5000domains        1mailboxes      3default quota  1073741824

    installed is n/a: the facade manages rows, not a buildable application, and publish() returns nothing so expose does not try to write wrappers.

    #Notes

  • No reload is needed after any change; the SQL maps and the Dovecot queries
  • read the database on every lookup.

  • Maildir deletion, autoresponders, relocated users and per-domain TLS policy
  • are not implemented yet — see roadmap.md.