#Postfix: relays and routes
A relay is a named outbound transport with its own source address and HELO name, so one server can send different mail from different IPs. A route decides which destinations use which relay.
example.org ──route──▶ relay1 (203.0.113.10, helo mail.example.com)shop.example ──route──▶ relay2 (203.0.113.11, helo shop.example.com)anything else ────────▶ default smtp transport (server's primary IP)Use cases: separate IPs per customer domain for reputation, a second IP after a blocklisting, or an IP with a matching reverse DNS for transactional mail.
Configuration for the cube itself (paths, database backend, hook user) is in postfix.md; this page covers only the relay tables and the generated services.
#How it is built
A relay is not a database abstraction over relayhost; it is a real Postfix service:
aegis_relays holds one row per relay (see schema.md).configure (or relays command) writes a block into master.cf: # BEGIN AEGIS RELAYS — generated by the postfix cube, do not edit aegis-relay1 unix - - n - - smtp -o syslog_name=aegis-relay1 -o smtp_bind_address=203.0.113.10 -o smtp_helo_name=mail.example.com # END AEGIS RELAYSaegis_relay_domains holds the routes. The SQL transport map turns theminto aegis-relay1:, which is the service name above.
#Commands
aegis cubes postfix relays listaegis cubes postfix relays routesaegis cubes postfix relays add <name> --bind-ip <ip> --helo <name>aegis cubes postfix relays remove <name>aegis cubes postfix relays route-add <destination> <relay>aegis cubes postfix relays route-remove <destination> --relay <name>#Creating relays
# first IP, for customer Aaegis cubes postfix relays add relay1 --bind-ip 203.0.113.10 --helo mail.example.com# second IP, its own HELO and its own syslog tagaegis cubes postfix relays add relay2 --bind-ip 203.0.113.11 --helo shop.example.com --syslog aegis-shop# created but not rendered (kept for later)aegis cubes postfix relays add standby --bind-ip 203.0.113.12 --helo mail.example.com --disabledadd creates or updates: running it again with the same name changes the address, HELO or state, which is how a relay is edited.
Validation happens before anything is written:
| Rule | Rejected example |
|---|---|
name: lowercase, starts with a letter, [a-z0-9-], max 31 chars | Relay_1, 1relay |
bind_ip must parse as an IP address | 203.0.113.999 |
bind_ip must be configured on this host | an IP of another machine |
two active relays may not share bind_ip | relay2 --bind-ip 203.0.113.10 |
helo_name must be a hostname | mail example.com |
syslog_name: [A-Za-z0-9._-], max 64 | aegis shop |
The host check reads ip -o addr show; if iproute2 is missing the check is skipped and the mistake surfaces later as smtp_bind_address failing at delivery time.
#Routing destinations
aegis cubes postfix relays route-add example.org relay1aegis cubes postfix relays route-add '@shop.example' relay2aegis cubes postfix relays route-add billing@example.org relay1aegis cubes postfix relays routes# example.org -> relay1; @shop.example -> relay2; billing@example.org -> relay1aegis cubes postfix relays route-remove example.orgaegis cubes postfix relays route-remove billing@example.org --relay relay1The destination is matched by the transport map as a whole value, so write what Postfix looks up: a bare domain (example.org) or a full address (billing@example.org). A @domain form matches only the domain part in this implementation — use the bare domain for "everything at example.org".
Every command above re-renders master.cf, runs postfix check and reloads the daemon, so the change is live without a restart.
#Removing
aegis cubes postfix relays remove relay1The schema has ON DELETE CASCADE on the routes, so removing a relay removes its routes in the same statement; the next configure drops both the master.cf block and the transport rows.
#Verifying
# the service exists and carries the right addressaegis cubes postfix relays listpostconf -c /aegis/config/postfix -M | grep aegis# the route resolves to the service namepostmap -q example.org pgsql:/aegis/config/postfix/maps/transport.cf# aegis-relay1:# a message actually leaves from the relaygrep 'relay=aegis-relay1' /aegis/logs/postfix/mail.logA successful delivery through a relay logs the service name, not the transport column:
postfix/smtp[1234]: ABC123: to=<user@example.org>, relay=example.org[192.0.2.10]:25, delays=0.02/0.01/0.3/0.2, dsn=2.0.0, status=sent (250 2.0.0 Ok)and the syslog_name you set appears as the log tag (postfix/aegis-shop).
#Testing without real mail
# does the map return the right transport?postmap -q example.org pgsql:/aegis/config/postfix/maps/transport.cf# does Postfix accept the generated master.cf?aegis cubes postfix validate# which source address would be used for one destination?postconf -c /aegis/config/postfix -M | grep -A3 aegis-relay1#Limits and gotchas
aegis_relays has host, port,username, password and tls columns, but the generated transport only sets smtp_bind_address and smtp_helo_name: a relay sends directly to the destination's MX. Use [apps.postfix] relayhost for a global smarthost.
address to an interface is an operator step (ip addr add …).
aegis_transport row: the transport map lists the manual entries first.
their aegis-relay1: transport and are deferred; flush or requeue them after the change.
unix service in master.cf; a name that collides with aPostfix built-in (smtp, relay, lmtp, …) is rejected by the name regex only if it does not start with a letter — otherwise give it a distinct name.