Demo
Demo

Knowledge base

PMTA knowledge base›Block <domain>›Directive§ 3.3.10.98

route

<domain>deprecated

Deprecated in favor of smtp-hosts
in the configuration this is a linerouteinside the block <domain>
The deprecated form of explicit delivery hosts

It set the hosts to which this receiver’s mail should be delivered, bypassing the usual MX lookup — or told the engine to look up the MX of another domain. Replaced by the smtp-hosts directive.

Both have word for word the same definition. Section § 3.3.10.98 repeats the first sentence of § 3.3.10.100 word for word and adds one line: “deprecated, use smtp-hosts”. The vendor gives no syntax, no default and no difference in behavior for the old name.

What is known about the notation. It is described only for the new name: hosts separated by commas within a preference level, a semicolon between levels, an optional port after a colon, lookup-mx:domain instead of a host list, and empty quotes to clear an inherited value. Whether the old name accepts all of this, the manual does not say.

The main trap. In an inherited configuration the directive keeps working — and keeps diverting mail past the receiver’s MX records. It causes no error, looks like a working line in the settings output, and therefore lives for years. It is worth finding before the vendor stops accepting it.
What the Hub does. It writes neither the old name nor the new one: the configuration generator sets no explicit delivery hosts, mail goes by the receivers’ MX records. The Hub does not analyze other people’s configurations at all: it shows deprecated lines here, in the catalog — with a “deprecated” mark and a link to the replacement — but it neither looks for them in a node’s configuration nor edits them.
Recommended values

No new values are chosen. The only sensible value is none: the line is moved to smtp-hosts as is, and you check that delivery goes where it went before.

When moving it, recheck the meaning. Explicit hosts are liable to go stale along with the infrastructure they pointed to: the gateway address changes, but the line stays. Before copying the value, make sure the host is still the right one.

Empty quotes clear the inherited value. For the new name this is documented, and it is a needed technique: a receiver that inherited explicit hosts from a more general block cannot get rid of them otherwise.

All from the manual: the deprecation mark is from § 3.3.10.98, the notation from § 3.3.10.100, where the replacement is described.
Example configuration
# before — the deprecated name
<domain example.com>
    route mail.example.net
</domain>

# the right way — the same with the new name, with a port and a fallback level
<domain example.com>
    smtp-hosts mail.example.net:2525; [10.1.1.1]</domain>
The upper block is what sits in an inherited configuration; the lower one is its replacement in the form described for smtp-hosts. The manual gives no example of its own for the old name.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends3 mistakes▶

Leaving the line in an inherited configuration

§ 3.3.10.98

What it costsThe directive works and silently overrides the route. The host it points to may have changed or disappeared — then delivery stalls while the receiver is alive.
How to spot itThe receiver’s mail goes somewhere other than its MX records point, and a DNS check explains nothing.
How to do it rightFind all occurrences in the configuration, move them to smtp-hosts and check each address before copying.

Writing explicit hosts into the general block

§ 3.3.10.100

What it costsThe value from <domain *> goes to every receiver. Normal MX delivery stops for everyone at once, and it is noticed not by an error but by other people’s rejections.
How to spot itAll of the node’s mail goes to one gateway, although the rule was set up for a single receiver.
How to do it rightWrite explicit hosts only in the block of the receiver that needs them; in the general block clear the value with empty quotes.

Expecting the old name to accept the full notation

§ 3.3.10.100

What it costsThe full notation is described only for the new name. What of it the old one accepts, the manual does not say — this is untested territory.
How to spot itA value with ports and preference levels behaves differently than expected, and there is no error when the configuration is parsed.
How to do it rightDo not extend the old line, but move it to smtp-hosts and use the full notation there.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
route <hosts>
Values
no notation is described for the old name; for the replacement — hosts or bracketed addresses separated by commas within a level, levels separated by semicolons, a port after a colon, lookup-mx:domain or empty quotes
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<domain>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
<domain> blocks merge from general to specific, the narrowest match wins — so explicit hosts written in <domain *> go to all receivers at once. This is cleared with empty quotes for the new name. It is picked up by pmta reload.
⇄

Related directives

1 relation

Replaced by

smtp-hosts<domain>The supported form of writing a route; this line is deprecated. § 3.3.10.98

How to check on the node
The receiver’s effective route is printed by the queue settings output:
pmta show settings example.com
Look at the smtp-hosts line in the Queue Settings section: it shows the value after merging blocks, regardless of which name it was written under. An empty value means normal delivery by MX records.
◇

What else to read

3 articles

◇Accept, route, deliverA message’s path inside the node: accept, decide where, deliver — and all the settings live between these three steps.◇Four value types the whole config is written inBoolean, domain pattern, regular expression and time interval — defined once in § 3.2 and then used by all directives.◇Reloading settings versus restarting the serviceThe configuration is read at startup, and after that edits are picked up by the reload command — except for the directives the manual marks as requiring a restart.

In the Hub
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Configuration lifecycle
Neighboring settings of the block <domain>:queue-tobackoff-reroute-to-virtual-mtasmtp-hostsreroute-to-virtual-mtadisable-mx-rollupAll 135 directives of the block →