Virtual Recipients

Virtual Recipients

Admin path: Email Relay > Virtual Recipients (view_virtual_recipients.cfm, inc/addvirtualrecipients.cfm, inc/editvirtualrecipient.cfm, inc/delete_virtual_recipients.cfm).

This page manages forward-only address aliases on the relay-topology domains configured under Domains. Each row in the virtual_recipients table maps one inbound address (or a domain-wide catch-all) to exactly one delivery address.address, and an address that delivers to several destinations simply has several rows. The delivery target can be internal to Hermes, on another relay domain, on a mailbox domain, or anywhere on the public InternetInternet. —The therows row isare consumed by Postfix's virtual_alias_maps, which concatenates every row it gets back into a single recipient list, so one inbound message fans out to all of them and rewritten at SMTP time, so the forward isstays transparent to the original sender.

Virtual recipients have no SMTP authentication, no IMAP/POP3 access, and no password. They are not user accounts. They are rewrite rules.

Not the same as Mailbox Aliases

The Email Server topology has its own alias page — Email Server > Aliases, backed by the mailbox_aliases table — and it serves a different need. The add handler enforces the separation explicitly: trying to add a virtual recipient for a domain flagged as mailbox is rejected with the "use Email Server > Aliases" hint.

	Virtual Recipients	Mailbox Aliases
Table	virtual_recipients	mailbox_aliases
Domain type	Relay domains (domains.type = 'relay' or NULL)	Mailbox domains (mailbox_domains.*)
Delivery target	Anywhere — internal or external	A local Dovecot mailbox
Resolved by	Postfix virtual_alias_maps (MySQL lookup)	Postfix virtual_alias_maps (same query, different table)
Auth, IMAP, password	No	No (the resolved mailbox owns those)
Typical use	info@company.com → admin@company.com, info@externalpartner.example	support@company.com → user1@company.com (where user1@ is a local mailbox)

The shared mysql-virtual.cf lookup is a UNION across both tables:

SELECT maps          FROM virtual_recipients WHERE virtual_address = '%s'
UNION
SELECT delivers_to   FROM mailbox_aliases    WHERE alias_address   = '%s'

Postfix doesn't care which table the answer comes from — but the admin UI separates them so the rule for each topology stays focused.

Storage and lookup path

The order of these steps matters, and it is not the obvious one. The rewrite is deferred until after content filtering, because main.cf sets receive_override_options = no_address_mappings globally, which disables virtual alias expansion in the cleanup that runs for mail arriving on port 25. The map is still consulted at smtpd to decide whether the recipient exists, but the envelope keeps the original address through the filter.

inbound SMTP (port 25) ──► hermes_postfix_dkim
                                  │
                                  │  smtpd checks: helo, sender, recipient
                                  │  recipient VALIDATED against
                                  │  relay_recipient_maps / recipient_canonical_mapsvirtual_alias_maps
                                  │  virtual_alias_maps       ◄── mysql:/etc/postfix/mysql-virtual.cf
                                  │            │
                                  │            ▼
                                  │  ┌────────────────────────────────────┐
                                  │  │ hermes_db_server                   │
                                  │  │  SELECT maps FROM virtual_recipients│
                                  │  │   UNION                            │
                                  │  │  SELECT delivers_to FROM           │
                                  │  │   mailbox_aliases                  │
                                  │  └────────────────────────────────────┘
                                  │
                                  v│  cleanup runs with no_address_mappings,
                                  │  so the recipient is NOT rewritten recipient(s)
                                  │yet
                                  ▼
              content filter (amavis on 10024)10021)
              policy keyed on the ORIGINAL virtual address
                                  │
                                  ▼
                         hermes_ciphermail
                                  │
                                  ▼
              reinjection on :10026, which overrides
              receive_override_options and therefore DOES
              expand virtual_alias_maps
                                  │
                                  ▼
                          rewritten recipient(s)
                                  │
                                  ▼
                       outbound or local delivery

No file regeneration is required when virtual recipients change. The MySQL lookup is live — adding a row in the admin UI takes effect on the next inbound message, with zero Postfix restart or postmap step. This is the operational reason virtual aliases are stored in MySQL rather than a hash file.

The virtual_recipients table

Column	Type	Role
id	INT PK	Surrogate key for the row
virtual_address	VARCHAR(255)	The address being rewritten. Full email (info@example.com) or a catch-all token (@example.com).
maps	VARCHAR(255)	Destination address. Single recipientOne per row; an address delivering to several destinations has one row ineach, theand currentPostfix schema.concatenates them.
alias_type	VARCHAR(20)	Defaults to forward. Reserved for future per-alias behavior flags; not surfaced in the UI today.
send_as	TINYINT(3)	Reserved for outbound "send-as" support (allow the destination to send mail as the virtual address). Not wired through Postfix yet.
policy_id	INT	Reserved for per-alias Amavis policy attachment. Not surfaced today.
system	INT	Provenance marker — 1 = seeded by the install/system-addresses flow (postmaster/abuse/root), 2 = admin-created via this page. The system rows are managed by update_system_email_addresses.cfm and recreated when the admin email or postmaster changes.

There is no UNIQUE constraint on virtual_address, because a single inbound address can fanfans out to multipleseveral destinations —by eachholding destinationone getsrow itseach.

own

There row.is Thedeliberately addno handlerunique dedupeskey on the (virtual_address, maps) pair soeither, even though mailbox_aliases gained one in v260815. Existing installs may already hold exact duplicates, and ADD UNIQUE would abort the samewhole forwardschema isn'tupgrade insertedon twice.the first one it met. The console is the guard instead: Add refuses an address that already exists, so a duplicate pair cannot be created through the UI.

Two address shapes — specific and catch-all

Specific aliases

A regular forward of one address to one destination:

info@company.com       →   owner@company.com
sales@company.com      →   sales-team@externalcrm.example
legal@company.com      →   external-counsel@lawfirm.example

The local-part is rewritten by Postfix beforeafter content filtering.filtering, at the :10026 reinjection listener. The recipient never sees the original info@/sales@/legal@ address unless the destination mail system surfaces the original envelope.

Catch-alls

A single row starting with @ matches every local-part on the domain that is not already a more specific virtual recipient or a mailbox:

@company.com           →   admin@company.com

With the catch-all row above, mail to jdoe@company.com, random-string@company.com, and does-not-exist@company.com all forward to admin@company.com. Specific aliases on the same domain (info@company.com → owner@company.com) win over the catch-all because they match the more specific lookup key first.

Catch-alls are useful for sunset domains, migration phases, or small domains where one mailbox owner is willing to receive everything. They are not appropriate for high-volume domains: every spam attempt against a random local-part lands in the catch-all destination.

Catch-all visibility in the user portal

A user whose mailbox is the destination of a catch-all (e.g., admin@company.com above) has a special branch in the user portal's Quarantined Messages, Total Messages, and Message History queries. config/hermes/var/www/html/users/2/index.cfm, view_message.cfm, and view_message_history.cfm all consult virtual_recipients for catch-all entries that explicitly map TO the logged-in user, then widen the query with a LIKE '%@domain.tld' clause so the user sees the messages that were swept up by the catch-all. Specific aliases do not get this treatment yet — a known parity gap for the rare case where one user owns many specific aliases and wants the same widened visibility.

Fields on the page

Add Virtual RecipientsRecipient cardmodal

Opened by the Add Virtual Recipient button above the table. One address per submission, matching Email Server > Aliases.

Field	Notes
Virtual Address(es)Address	Newline-delimited textarea. Each line is oneOne full email address or a @domain.com catch-all. Lowercased,Lowercased trimmed,and deduped against virtual_recipients AND mailbox_aliases before insert.trimmed.
Delivers To	SingleOne destinationor addressmore fordestinations, the whole batch. Validatedentered as anremovable email.chips. AutocompleteTyping sourcedsearches fromexisting relay recipients through inc/getintrecipients.cfm; (existingany relayother recipientsaddress can be typed in and mailboxaccepted addresses)on soEnter. youOne canrow typeahead-pickis awritten knownper recipient.chip.

TheBecause handlera iteratessubmission thecarries textareaexactly line-by-lineone andaddress, accumulatesit per-lineproduces results.exactly Theone successverdict, banner reports the count and addresses that landed, and separate error banners surface invalid-format lines, lines whose domain isn't configuredreported as a relaysingle domain,message linesrather whosethan domaina tally:

Condition Message Virtual Address blank 1 Delivers To empty 2 A destination is not a valid email 3 Address is neither a valid email nor a @domain catch-all 4 Domain not configured in the system 5 Domain is a mailbox domain (with the "use Email Server > Aliases"Aliases) pointer),6 Address already exists as a mailbox alias 7 Address already exists as a virtual recipient (use Edit) 8

Until v260815 this was a newline-delimited textarea creating many addresses at once. That shape forced every outcome to be an accumulating per-row tally across four separate callouts, and duplicateit lines.meant Noan transactionaddress wrapsthat already existed could only be reported rather than refused, because other rows in the same batch —still partialhad successto process. The trade for the simpler model is thethat expectedcreating behavior.several addresses now takes several submissions.

Virtual Recipients table

Standard DataTables surface —surface: searchable, sortable, exportable (copy / CSV / Excel / PDF / print), stateSave: true so column order and page size persist across reloads. Columns:Rows are grouped by address, so an entry with twenty destinations is one row with twenty chips.

Index Column Source Checkbox0 Bulk-selectActions forEdit deleteand Delete. Not sortable or searchable 1 Recipient virtual_recipients.virtual_address 2 Delivers To virtual_recipients.mapsDisplay-only chips, one Actionsper Editdestination, (opensexternal modal)ones badged

Actions sits on the left to match Aliases. Note for anyone changing this table: order and columnDefs are index-based and stateSave persists the sort by index, so inserting or removing a column requires updating both plus the stateLoadParams guard.

Edit modal

InlineEdits editthe ofwhole virtual_addressentry, keyed on the address rather than a row id. The destination set opens as removable chips and maps.the save is a diff: insert what is new, delete what was taken off, leave the rest untouched. Diffing rather than delete-then-reinsert means there is never a moment when the address has no destinations. Re-runs the same domain validation,validation and catch-all detection, and dedupe checkdetection as Add —Add, including the rejection of mailbox-domain rows.

Adding and removing destinations happens here and only here. Add creates.

Delete

Checkbox-drivenOne bulkDelete deletebutton fromper row, confirmed in a modal that names the tableaddress card.and its destination count. The row carries dest_ids, every underlying row id for that address comma-joined by the grouped query, and the handler (delete_virtual_recipients.cfm) just runs DELETE FROM virtual_recipients WHERE id = ? per selectedid, rowso —one thereclick removes the address and all of its destinations together. There is no dependency check, because nothing else in the schema points back at a virtual recipient row.

The select-all checkbox column and its bulk Delete Selected button were removed in v260815. They existed because the pre-grouping table rendered one row per destination, so an address with a large destination set filled the screen and needed bulk selection to clear.

ContentVirtual filterrecipients bypassare —content by design, loudfiltered

TheThey yelloware calloutfiltered onexactly like any other inbound mail. This section previously claimed the opposite, and the page exists forcarried a reason.callout Postfix rewrites the recipient before the message reaches Amavis content filtering, but Amavis policy lookups key on the post-rewrite recipient. If the destination address is an external Internet address (Gmail, Outlook.com, a personal mailbox, etc.), Amavis applies the default outbound policy to it — which typically means lighter spam/banned-files enforcement than a domain-scoped inbound policy would.

The net effect:saying mail aliased through a virtual recipient was delivered "while bypassing ALL content checking (spam, virus, banned files)". Both were wrong. The wording traced back to build-220203 and described no part of this pipeline. Removed in v260815.

Three independent reasons it was never true:

content_filter is global. main.cf sets content_filter = amavis:[hermes_mail_filter]:10021 with no per-recipient exception. The only bypass lane in the system is :10030, the BYPASSALLCHECKS policy bank, and it is reachable only through a FILTER action set by Global Sender Block/Allow, which is keyed on the sender. Amavis sees the original address. Because receive_override_options = no_address_mappings defers expansion past the filter, the envelope recipient reaching Amavis is the virtual address itself, not the destination. There is no "post-rewrite recipient" for policy to key on at that point. A domain-scoped policy always matches. Adding a domain inserts an external@domain row into recipients carrying the default policy, and Amavis's recipient lookup falls back from user@domain to @domain. The code that does it says so: "ensures Amavis applies SVF filtering to all mail for this domain."

Amavis also classifies the mail correctly as inbound, because @local_domains_maps reads /etc/postfix/relay_domains and the virtual address is generallyon lessone aggressivelyby filtereddefinition, thansince the sameAdd mailhandler deliveredrefuses toany adomain local mailbox or relayed to a known partner domain. Thisthat is finenot forconfigured.

legitimate

The forwards,real butcaveat admins who usewith virtual recipients tois bridgenot afiltering, sunsetit domainis toforwarding. aMail personalleaves Gmail should expect Amavis to be permissive about it. Tightenwith the policyoriginal bysender's editingaddress, so SPF fails at the destinationreceiving recipient'send, recipients row directly under Relay Recipientsand if the destinationmessage iswas itselfmodified on the way through, by an External Banner or LinkGuard, the original DKIM signature no longer validates either. Senders publishing a knownstrict HermesDMARC recipient.policy can therefore have mail to external destinations rejected. That warning lives in the Add modal, beside the field it applies to.

Domain-delete dependency

Deleting a relay domain via Domains is blocked when virtual recipients reference it. deletedomain.cfm runs:

SELECT * FROM virtual_recipients WHERE virtual_address LIKE '%<domain>%'

Any match aborts the domain delete with error code 2 and the admin must clear the matching rows from this page before the domain can be removed. The same back-pressure protects against silently stranding a forward when its destination domain disappears.

System-managed rows

A few rows in virtual_recipients are created and managed by the System > Server Setup flow, not by this page directly:

Pattern	Created by
postmaster@<every-domain> → admin email	inc/update_system_email_addresses.cfm on every Server Setup save
root@<every-domain> → admin email	Same
abuse@<every-domain> → admin email	Same

These rows are marked system = '1' (the install/system flow) versus admin-created rows which are marked system = '2'. Editing or deleting a system-managed row from this page works mechanically, but the row will be recreated on the next Server Setup save. Edit the admin email there if you want a different destination for these reserved local-parts; do not maintain them by hand here.

Failure semantics

What breaks	What happens
Virtual address blank in Add	error 1 banner, no DB write
Delivers To blank or invalid email in Add	error 2/3 banner, no DB write
Edit virtual address fails email or catch-all format	session.m = 10, redirect, no DB write
Edit Delivers To blank or invalid	session.m = 11/12, redirect, no DB write
Domain not in domains table	session.m = 13 on edit; per-lineerrormessage invalid-domain= banner5 on addadd, —nothing line skipped, others continuewritten
Domain is a mailbox domain	Per-lineerrormessage invalid-domain= banner6 on add, with the "use Email Server > Aliases" hint; line skippedhint
DuplicateAddress (virtual_address,already maps) pairexists in virtual_recipients or mailbox_aliases	Per-lineerrormessage duplicate= banner7 on add;add

Address already exists in virtual_recipients errormessage = 8 on add, pointing at Edit; session.m = 14 on edit Delete withrequest carries no rows selectedid session.m = 1 banner, no DB write MySQL hermes_db_server down Postfix virtual_alias_maps lookups fail. By default Postfix defers mail to the affected recipients with a temporary error and retries on the next queue run; legitimate mail is held, not bounced.

Bulk import

TheThere currentis pageno supportsbulk newline-delimitedpath. pasteAdd intocreates one address per submission.

Until v260815 the Add textarea,card whichwas isa newline-delimited textarea and pasting many addresses at once was the practical bulk path:route. pasteIt hundredswas ofremoved alias@domain.combecause linesa (allsubmission forwardingcarrying tomany oneaddresses destination)can atonly once, click Add, getreport a per-line outcome report. A separate CSV import is not provided because the table is intentionally one-destination-per-row — fan-out is expressed by adding the same virtual_address multiple times with different maps,tally, which is easierwhat forced the page's four accumulating callouts and made it impossible to dosimply refuse an address that already existed. Fan-out in the textareaother thandirection, inone address to many destinations, is unaffected and is entered as chips.

If a CSV.bulk path is wanted again it should be a real import with its own report, not a shared text field whose failure mode is a tally.

Files and containers touched

Path	Owner	Role
config/hermes/var/www/html/admin/2/view_virtual_recipients.cfm	hermes_commandbox	Page + Add card + table + modals
config/hermes/var/www/html/admin/2/inc/addvirtualrecipients.cfm	hermes_commandbox	Add handler with per-line validation
config/hermes/var/www/html/admin/2/inc/editvirtualrecipient.cfm	hermes_commandbox	Edit handler
config/hermes/var/www/html/admin/2/inc/delete_virtual_recipients.cfm	hermes_commandbox	Delete handler (per selected id)
config/hermes/var/www/html/admin/2/inc/getintrecipients.cfm	hermes_commandbox	Autocomplete source for the Delivers To field
config/hermes/var/www/html/admin/2/inc/update_system_email_addresses.cfm	hermes_commandbox	Manages the system = '1' rows (postmaster/root/abuse)
/etc/postfix/mysql-virtual.cf	hermes_postfix_dkim (volume-mounted)	Postfix MySQL lookup definition for virtual_alias_maps
virtual_recipients, mailbox_aliases, domains	hermes_db_server	The lookup tables and the domain-type gate

Nothing on this page shells out to Postfix — there is no postmap, no postfix reload, no template regeneration. The MySQL lookup is the only integration surface.

Related

• Domains — the relay-topology domain list these aliases attach to. Domain deletes are blocked when virtual recipients still reference the domain.
• Relay Recipients — recipient validation for domains with Recipient Delivery = SPECIFIED. A specific relay recipient and a virtual recipient can coexist for the same address; the relay recipient wins for recipient-list validation, the virtual recipient still rewrites at delivery.
• Email Server > Aliases — the mailbox- topology equivalent. Aliases for domains where Hermes is the destination MTA live there.
• Email Server > Shared Mailboxes — when several users need to read the same incoming mail (not just one user receiving forwards), use a shared mailbox instead of a fan-out virtual recipient.
• Server Setup — manages the system = '1' postmaster/root/abuse forwards. Change the admin email there to retarget those reserved local-parts.