#Mail database schema
The mail stack shares one database: Postfix reads domains, mailboxes, aliases and policies from it on every lookup, Dovecot authenticates against it, OpenDKIM stores its keys and the mail cube is the only thing that writes. Nothing is cached in files, so a row change is live immediately.
#Where it lives
| Backend | Database | Role | Configured by |
|---|---|---|---|
| PostgreSQL | mail.database.name (aegis_mail) | mail.database.user (aegis_mail) | aegis cubes postfix configure |
| MariaDB | same | same | same |
| SQLite | mail.database.sqlite_path | — | same |
The backend is chosen at install time ([apps.postfix] database) and can be changed later; the schema files below are per backend and idempotent.
storage/data/apps/postfix/schema/pgsql.sql applied by the postfix cubestorage/data/apps/postfix/schema/mysql.sqlstorage/data/apps/postfix/schema/sqlite.sqlThe role password is generated once and stored in config/server.toml under [mail.database] password; the cube re-applies it to the role on every configure, so the two can never drift apart.
#Ownership: who writes what
| Table | Written by | Read by |
|---|---|---|
aegis_domains | mail domains … | Postfix domain map, mail, opendkim, postsrsd |
aegis_mailboxes | mail mailboxes … | Postfix mailbox/quota/login maps, Dovecot |
aegis_aliases, aegis_forwards | mail aliases/forwards … | Postfix alias map |
aegis_relocated | mail relocated … | Postfix relocated_maps |
aegis_transport | panel/SQL | Postfix transport map |
aegis_relays, aegis_relay_domains | postfix relays … | Postfix transport map + master.cf |
aegis_tls_policy | mail tls … | Postfix smtp_tls_policy_maps |
aegis_security_rules | postfix security … | compiled into header_checks and access maps |
aegis_hooks | postfix hooks … | hook runner (hooks.json) |
aegis_dkim | opendkim (key material) | not read by Postfix; the key files are |
aegis_sender_bcc, aegis_recipient_bcc | panel/SQL | Postfix BCC maps |
aegis_outbound_ips, aegis_access, aegis_admins, aegis_autoresponders | reserved | — |
#Routing tables
#aegis_domains
The list of domains Postfix accepts mail for.
| Column | Type | Meaning |
|---|---|---|
id | serial | primary key |
domain | text, unique | the name, lowercase, no trailing dot |
active | bool | false = treat the domain as remote (MX lookup again) |
transport | text | default virtual; kept for non-LMTP setups |
catch_all | text | address that receives unmatched recipients |
max_mailboxes | int | advisory limit used by the panel |
default_quota_bytes | bigint | quota for new mailboxes |
max_quota_bytes | bigint | ceiling for a single mailbox |
dkim_selector | text | selector OpenDKIM uses for this domain |
created_at, updated_at | timestamp | bookkeeping |
#aegis_mailboxes
One row per usable address, including its Dovecot password and maildir.
| Column | Type | Meaning |
|---|---|---|
address | text, unique | full address, lowercase |
local_part | text | everything before @, duplicated for lookups |
domain | text, FK → aegis_domains.domain | ON DELETE CASCADE |
display_name | text | free text for the panel |
password | text | crypt hash, never plaintext |
password_scheme | text | SHA512-CRYPT (Dovecot 2.4 refuses MD5) |
maildir | text | absolute path, also used as Dovecot home |
quota_bytes | bigint | null = domain default |
active | bool | false = no delivery, no login |
disabled_reason | text | why it was disabled |
last_login_at, last_auth_at | timestamp | reserved for the panel |
created_at, updated_at | timestamp | bookkeeping |
Indexes: domain, active — the map queries filter on both.
#aegis_aliases
Plain redirects, one destination per row.
| Column | Type | Meaning |
|---|---|---|
address | text, unique | the alias itself |
destination | text | full address, or a comma-separated list |
owner_login | text | login allowed to send as this address |
active | bool | false = ignored by the map |
#aegis_forwards
Forwarding that can keep a local copy.
| Column | Type | Meaning |
|---|---|---|
address | text | source address |
destination | text | external (or internal) target |
owner_login | text | login allowed to send as the source |
keep_local | bool | true = deliver here and forward |
active | bool | false = ignored |
UNIQUE (address, destination) allows several targets per address.
#aegis_relocated
Answers 551 User not local; please try <destination>.
| Column | Type | Meaning |
|---|---|---|
address | text, unique | the old address |
destination | text | where the user moved |
active | bool | false = no answer |
#aegis_transport
Per-destination transport override, used before the relay routes.
| Column | Type | Meaning |
|---|---|---|
destination | text, unique | domain or address |
transport | text | for example lmtp:unix:…, smtp:[host]:25 |
active | bool | false = ignored |
#Relay tables
aegis_relays describes named outbound transports: each one becomes a service in master.cf with its own source address and HELO name.
| Column | Type | Meaning |
|---|---|---|
name | text, unique | transport name, aegis-<name> in master.cf |
host | text, null | smarthost; null = deliver to the recipient's MX |
port | int | smarthost port, default 587 |
username, password | text | SASL credentials for a smarthost |
tls | bool | require TLS towards a smarthost |
bind_ip | text | source address the transport binds |
helo_name | text | HELO/EHLO announced by the transport |
syslog_name | text | tag in the log, default aegis-<name> |
priority | int | display order |
active | bool | false = not rendered |
aegis_relay_domains routes destinations through one of those transports:
| Column | Type | Meaning |
|---|---|---|
destination | text | domain or address |
relay | text, FK → aegis_relays.name | ON DELETE CASCADE |
active | bool | false = ignored |
aegis_outbound_ips is a reservation for the multi-IP panel page: it lists the addresses a server may send from (address, label, is_default, active) without duplicating what aegis_relays.bind_ip already does.
#Policy tables
| Table | Columns | Used for |
|---|---|---|
aegis_sender_bcc | address, destination, active | blind copy of mail from an address |
aegis_recipient_bcc | address, destination, active | blind copy of mail to an address |
aegis_access | pattern, action, active | reserved for the anti-abuse access lists |
aegis_tls_policy | domain, policy, active | outbound TLS: may, encrypt, secure, verify, none |
#Signing and content
#aegis_dkim
One row per domain and selector. The private key stays on disk; this table is the record of what was generated and when.
| Column | Type | Meaning |
|---|---|---|
domain, selector | text | unique together |
private_key | text | reserved; the cube keeps keys under opendkim.key_dir |
public_key | text | reserved |
active | bool | false = not published |
#aegis_security_rules
Compiled into Postfix check files by postfix configure.
| Column | Type | Meaning |
|---|---|---|
kind | text | header, body, sender, helo, rbl |
pattern | text | regexp, or a blocklist zone for rbl |
action | text | reject, defer, discard, warn |
message | text | text shown to the sender |
priority | int | order inside the generated file |
active | bool | false = not compiled |
#aegis_hooks
Mail hooks executed by the pipe runner.
| Column | Type | Meaning |
|---|---|---|
name | text, unique | hook identifier |
enabled | bool | false = skipped by the runner |
direction | text | inbound, outbound, both |
match_type | text | all, domain, address |
match_value | text | domain or address for the two specific matches |
handler_type | text | script or webhook |
handler_value | text | shell command, or URL for a webhook |
timeout_sec | int | how long the handler may run |
#aegis_autoresponders
Reserved for vacation replies: address, subject, body, active, starts_at, ends_at. The table exists so the panel can store the text; the Sieve side is not implemented yet.
#aegis_admins
Reserved for postmaster accounts that log into the panel rather than receive mail: username, password, active.
#Views read by the maps
| View | Returns | Used by |
|---|---|---|
aegis_mail_forwarding | one row per address, destinations joined with , | virtual_alias_maps |
aegis_transport_map | destination → transport | transport_maps |
aegis_mail_quota | address → effective quota | reference only (Dovecot enforces) |
aegis_sender_login | address → allowed logins | smtpd_sender_login_maps |
aegis_mail_forwarding merges aliases and forwards; keep_local adds the address itself to the destination list, which is what delivers a copy locally before forwarding.
aegis_transport_map turns a relay route into aegis-<relay>:, the service name the postfix cube writes into master.cf.
#Map files → queries
Each file under config/postfix/maps/ holds a driver, the connection details and one SQL query; %s is the lookup key.
| Map file | Postfix parameter |
|---|---|
domains.cf | virtual_mailbox_domains |
mailboxes.cf | virtual_mailbox_maps |
aliases.cf | virtual_alias_maps (exact match or catch-all) |
transport.cf | transport_maps |
relocated.cf | relocated_maps |
sender_bcc.cf, recipient_bcc.cf | sender_bcc_maps, recipient_bcc_maps |
sender_login.cf | smtpd_sender_login_maps |
tls_policy.cf | smtp_tls_policy_maps |
quota.cf | reference only |
The alias map is the only one with two branches, and it uses UNION rather than UNION ALL so an address that is both an alias and covered by the catch-all resolves once:
SELECT destination FROM aegis_mail_forwarding WHERE address = '%s'UNIONSELECT catch_all FROM aegis_domainsWHERE domain = split_part('%s', '@', 2) AND catch_all IS NOT NULL AND active#Inspecting the data
# as the mail role, over TCPpsql -h 127.0.0.1 -U aegis_mail -d aegis_mail# who has mailboxes, how many, how muchSELECT d.domain countm.id AS boxes pg_size_prettysumCOALESCEm.quota_bytes d.default_quota_bytesFROM aegis_domains dLEFT JOIN aegis_mailboxes m ON m.domain = d.domain AND m.activeGROUP BY d.domain ORDER BY d.domain;# what the alias map returns for one addressSELECT FROM aegis_mail_forwarding WHERE address = 'info@example.com';# which domains are signed with which selectorSELECT domain dkim_selector FROM aegis_domains WHERE active;The CLI wraps all of it: aegis cubes mail domains list|show, mailboxes show, storage list, postfix security list, opendkim keys list.
#Changing the schema
The files are applied with CREATE … IF NOT EXISTS on every configure, so a new table is a safe addition. A new column on an existing table needs an ALTER TABLE … ADD COLUMN IF NOT EXISTS for PostgreSQL and MariaDB (SQLite has no such clause: the column is added to the CREATE TABLE and existing SQLite installs must be recreated or altered by hand). Columns added after the first release are grouped together in each file, next to a comment saying why.