#Postfix: mail hooks
Postfix cannot run a program per message, so the cube copies every message once through always_bcc to hooks@aegis.invalid, routes that copy to a pipe transport, and a small Python runner decides what to do with it. The runner reads the message, runs every hook whose rules apply, and exits 0 — the copy is discarded and the real delivery never waits for the hook.
message ──▶ cleanup ──▶ always_bcc: hooks@aegis.invalid │ transport map ▼ aegis-hooks (pipe) ──▶ runner.py + hooks.json │ script (sh -c) or webhook (POST)Configuration for the cube itself (paths, database backend, hook user) is in postfix.md; this page covers only the hook table and the generated runner.
#What a hook can see
The handler receives the whole message on stdin and, in the environment, the envelope sender and the addresses found in the message headers (To, Cc, Delivered-To, X-Original-To, Resent-To). The body and the rest of the headers are not passed, so a hook is the right place for auditing, notifications, spam learning and integrations — not for rewriting content (that is what the security rules and the milter are for).
Postfix does not preserve the envelope recipient in a BCC copy, so the recipient side comes from those headers, the same way the delivered message shows them. The sender is the envelope sender; when postssrsd rewrote it on the way in (SRS0=…@domain), the runner unwraps it from the From header first.
#Commands
aegis cubes postfix hooks listaegis cubes postfix hooks add <name> --handler <command|url> optionsaegis cubes postfix hooks remove <name>| Option | Values | Default |
|---|---|---|
--handler | shell command, or URL for a webhook | required |
--type | script, webhook | script |
--direction | inbound, outbound, both | both |
--match | all, domain, address | all |
--value | domain or address for --match | empty |
--timeout | seconds | 30 |
add creates or replaces: running it again with the same name is how a hook is edited. Each add and remove re-renders the files and restarts Postfix: the cleanup daemons cache the BCC setting, so a reload is not enough.
#Examples
#Audit every inbound message
aegis cubes postfix hooks add audit --handler printf "%s %s -> %s\n" "$(date -Is)" "$AEGIS_MAIL_FROM" "$AEGIS_MAIL_TO" >> /var/log/aegis-mail-audit.log --direction inboundThe runner exports three variables to the command:
| Variable | Value |
|---|---|
AEGIS_HOOK | the hook name (audit) |
AEGIS_MAIL_DIRECTION | inbound or outbound |
AEGIS_MAIL_FROM | envelope sender (SRS-decoded for inbound mail) |
AEGIS_MAIL_TO | recipient addresses from the headers, comma separated |
#Notify an external service
aegis cubes postfix hooks add notify --type webhook --handler https://hooks.example.com/aegis --direction inbound --match domain --value example.comThe runner POSTs JSON:
{ "hook": "notify", "direction": "inbound", "from": "customer@example.org", "to": ["support@example.com"]}#Copy outbound mail to an archive daemon
aegis cubes postfix hooks add archive --handler '/usr/local/bin/aegis-archive --from "$AEGIS_MAIL_FROM" --to "$AEGIS_MAIL_TO"' --direction outbound --timeout 10#A single heavy hook, with its own timeout
aegis cubes postfix hooks add spamlearn --handler 'curl -s -m 5 -d "to=$AEGIS_MAIL_TO" http://127.0.0.1:8089/learn >/dev/null' --direction inbound --timeout 15#Listing and removing
aegis cubes postfix hooks list# audit [inbound/all] script; notify [inbound/domain:example.com] webhookaegis cubes postfix hooks remove audit#What configure generates
hooks/hooks.json {"domains": […], "database": "pgsql", "hooks": […]}hooks/transport /^hooks@aegis\.invalid$/ aegis-hooks:hooks/runner.py executable, 0755and in master.cf:
# BEGIN AEGIS HOOKS — generated by the postfix cube, do not editaegis-hooks unix - n n - - pipe flags=Fq user=nobody argv=<python> <hooks>/runner.py ${recipient} ${sender}# END AEGIS HOOKSmain.cf gains one parameter and one map entry:
always_bcc = hooks@aegis.invalidtransport_maps = pgsql:…/transport.cf, regexp:…/hooks/transportWhen the last hook is removed, the runner files stay on disk but the always_bcc line, the transport entry, the block and the parameters disappear on the next configure.
#How the runner decides
SRS0=…) the message isinbound. Otherwise a sender in a hosted domain means outbound; if a hosted address also appears among the recipients, the message is inbound as well (local to local). The hosted domains come from hooks.json.
all always matches, domain compares the domain of the senderand of every header address, address compares the full addresses.
script runs /bin/sh -c with the envelope in the environment;webhook POSTs JSON with Content-Type: application/json.
in mail.log) and ignored: a broken hook must never lose mail.
#Testing a hook without sending mail
The runner reads the message from stdin and takes the copy recipient and the envelope sender as arguments, so it can be invoked directly:
printf 'To: demo@inhive.dev\nFrom: sender@example.org\n\nbody\n' | runuser -u nobody -- /etc/aegis/runtime/python/current/bin/python3 /aegis/config/postfix/hooks/runner.py hooks@aegis.invalid sender@example.orgThat runs every hook that applies to that message. For a full path test, send a real message and watch the log:
grep -E "aegis-hooks|aegis.invalid" /aegis/logs/postfix/mail.log# pipe[1234]: ABC: to=<hooks@aegis.invalid>, relay=aegis-hooks,# status=sent (delivered via aegis-hooks service)Check the generated pieces:
cat /aegis/config/postfix/hooks/hooks.jsoncat /aegis/config/postfix/hooks/transportpostconf -c /aegis/config/postfix -h always_bcc transport_maps#Limits
to modify the message.
always_bcc), not one per hook: a slow hook delaysthe others in the same run, up to its own --timeout.
nobody because Postfix refuses to run a pipe service asthe mail system owner. Scripts that need to write somewhere must be permitted for that account (or hand the work to a local socket).
as a delivery to hooks@aegis.invalid.
message is unaffected.