Aegis documentation

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

text
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

bash
aegis cubes postfix hooks listaegis cubes postfix hooks add <name> --handler <command|url> optionsaegis cubes postfix hooks remove <name>
OptionValuesDefault
--handlershell command, or URL for a webhookrequired
--typescript, webhookscript
--directioninbound, outbound, bothboth
--matchall, domain, addressall
--valuedomain or address for --matchempty
--timeoutseconds30

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

bash
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 inbound

The runner exports three variables to the command:

VariableValue
AEGIS_HOOKthe hook name (audit)
AEGIS_MAIL_DIRECTIONinbound or outbound
AEGIS_MAIL_FROMenvelope sender (SRS-decoded for inbound mail)
AEGIS_MAIL_TOrecipient addresses from the headers, comma separated

#Notify an external service

bash
aegis cubes postfix hooks add notify     --type webhook     --handler https://hooks.example.com/aegis     --direction inbound --match domain --value example.com

The runner POSTs JSON:

json
{  "hook": "notify",  "direction": "inbound",  "from": "customer@example.org",  "to": ["support@example.com"]}

#Copy outbound mail to an archive daemon

bash
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

bash
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

bash
aegis cubes postfix hooks list# audit [inbound/all] script; notify [inbound/domain:example.com] webhookaegis cubes postfix hooks remove audit

#What configure generates

text
hooks/hooks.json       {"domains": […], "database": "pgsql", "hooks": […]}hooks/transport        /^hooks@aegis\.invalid$/ aegis-hooks:hooks/runner.py        executable, 0755

and in master.cf:

text
# 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 HOOKS

main.cf gains one parameter and one map entry:

text
always_bcc     = hooks@aegis.invalidtransport_maps = pgsql:…/transport.cf, regexp:…/hooks/transport

When 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

  • Direction. With a sender rewritten by postsrsd (SRS0=…) the message is
  • inbound. 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.

  • Match. all always matches, domain compares the domain of the sender
  • and of every header address, address compares the full addresses.

  • Handler. script runs /bin/sh -c with the envelope in the environment;
  • webhook POSTs JSON with Content-Type: application/json.

  • Failure. An exception or a non-zero exit is written to stderr (so it lands
  • 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:

    bash
    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.org

    That runs every hook that applies to that message. For a full path test, send a real message and watch the log:

    bash
    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:

    bash
    cat /aegis/config/postfix/hooks/hooks.jsoncat /aegis/config/postfix/hooks/transportpostconf -c /aegis/config/postfix -h always_bcc transport_maps

    #Limits

  • Envelope sender, header recipients — no body, no envelope recipient, no way
  • to modify the message.

  • One copy per message (always_bcc), not one per hook: a slow hook delays
  • the others in the same run, up to its own --timeout.

  • The pipe runs as nobody because Postfix refuses to run a pipe service as
  • the mail system owner. Scripts that need to write somewhere must be permitted for that account (or hand the work to a local socket).

  • The copy is separate mail: it has its own queue id and appears in the log
  • as a delivery to hooks@aegis.invalid.

  • No retry: a hook that fails is logged and not retried; the original
  • message is unaffected.