Knowledge base
run-as-rootGlobalcriticalDirectiveMust be false to run as an unprivileged user; changing it requires a restart.http-enable-api-configGlobalDirectiveOpens an interface that allows creating address lists and sending addresses over HTTP; off by default.includeGlobalset by the HubDirectiveReads an additional file — by path, by mask or by HTTP address; the contents are processed as if written in this place.smtp-hosts<domain>DirectiveA list of hosts with preference levels, ports and addresses — or an instruction to take another domain’s MX.include<domain>DirectiveThe same directive written inside a recipient block — the included lines become that recipient’s rules.relay-debugGlobalDirectiveSwitches relay control into debug mode: instead of a final refusal the node responds with a temporary one, and the message stays with the sender instead of bouncing.backoff-max-msg-per-hour<domain>deprecatedDirectiveThe replacement is backoff-max-msg-rate, and it has a default this form did not have.broken-auth-clients<source>deprecatedDirectiveOne of two directives in the catalog about which the manual says nothing except the word “deprecated”.check-spf-inbound-best-guess<source>deprecatedDirectiveThe manual marks it as deprecated and explicitly advises against using it.delivery-priority<domain>deprecatedDirectiveThe section contains only the deprecation mark and a pointer to the replacement: queue priority.max-msg-per-hour<domain>deprecatedDirectiveThe replacement is max-msg-rate: the same limit, but the interval is written in the value itself.max-smtp-out-per-source-ip<domain>deprecatedDirectiveThe former name of the per-address connection limit; the manual says nothing more about it.route<domain>deprecatedDirectiveThe same mechanism under an old name: the manual gives it word for word the same description and asks you to use the new one.smtp-ipGlobaldeprecatedDirectiveThe replacement is smtp-listener: address and port in one line, and its presence silences this line.smtp-portGlobaldeprecatedDirectiveThe other half of a replaced pair: the port was set separately from the address, now they are written in one line.smtp-server-tls-allow-sslv3GlobaldeprecatedDirectivePowerMTA no longer supports SSLv3; the line is kept only for configuration compatibility.smtp-tls-allow-sslv3<domain>deprecatedDirectivePowerMTA no longer supports SSLv3; the line is kept only for configuration compatibility.spoolGlobaldeprecatedDirectiveIt set the spool location with one line; replaced by a block that has priority, a free space threshold and modes.How the node selects a source and combines its settingscriticalMechanismA connection falls under all source blocks whose addresses cover it, and they act merged — the narrow one overrides the wide one; named blocks are attached only by direct reference.Configuration through the API and the file do not reconcilecriticalMechanismObjects created through the configuration interface cannot be edited in the file: two sources of truth about the configuration do not reconcile.Reloading settings versus restarting the servicecriticalMechanismThe 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.Four value types the whole config is written incriticalMechanismBoolean, domain pattern, regular expression and time interval — defined once in § 3.2 and then used by all directives.Directives with the same nameMechanismA directive name defines a setting only together with its block: 48 of 417 names are documented in more than one place, and one name in different blocks is not always one setting.How the API reports an errorMechanismHTTP submission reports errors with response codes, while the configuration API answers 200 to everything except an access refusal and puts the outcome in the status field.The regular expression dialectMechanismConfiguration regular expressions are Perl-compatible, based on the PCRE library: that is how sending address selection, reply rules, bounce categories, address lists and signing headers are written.The directive indexMechanismThe manual’s alphabetical index: 475 lines name 477 places where directives are documented — the only complete inventory of the configuration language.Third-party components of the engineMechanismPowerMTA runs on five third-party libraries — PCRE, OpenSSL, ICU, gumbo-parser and prometheus-cpp; their behavior is determined by the engine build.Accept, route, deliverMechanismA message’s path inside the node: accept, decide where, deliver — and all the settings live between these three steps.Initial configurationcriticalProcedureThe manual requires two things to be set by hand: the responsible person’s address and relaying control — sources for submitting machines with always-allow-relaying; reception rules are needed only if the node accepts inbound mail.Change a sending address when messages are already queuedProcedureNew connections pick up the new definition right after the configuration reload; already open ones live out their lives on the old one.Investigating a startup failureProcedureThe order of looking for the cause when the engine does not come up: the separate startup error file, the main log, a console run with output to the screen.Starting and stopping the engineProcedureThe engine runs as a service on Windows and as a daemon on Unix; after start the watchdog must be running next to it, and a stop halts delivery without touching the messages on disk.<virtual-mta-pool>Configuration blockSeveral addresses addressed as one, with rotation among them.<address-list>Configuration blockA named list is attached by its name; an unnamed one lives inside a bounce or complaint processor and selects mail for parsing.<email-patterns>Configuration blockA block with pattern files, nested inside a bounce or complaint processor; it has two lines.<include-config>Configuration blockThe same as include with an address, but lets you set request headers — for example, authorization.<smtp-user>Configuration blockOne block, one login: what confirms the login and which named source gives it rights; declared at the root of the file.<source-group>Configuration blockGathers sources into a group so that inbound connection limits apply to them together; members name the group on their side.<transmissions-api-listener>Configuration blockThe address, port and encryption for submitting messages over HTTP.<transmissions-api>Configuration blockAccess keys, the request size limit and logging for submitting mail over HTTPS; declared once at the root of the file.<rewrite-list>Configuration blockA named list of rules; attached to a source by name, and all messages from there pass through it.<signals-filter>Configuration blockA block with rules by sender domain; attached to the scope by name, and anything not matched is considered disabled.reloadcriticalCommandRereads the configuration file and enables the new settings; if the file has an error, the command fails and the node keeps running on the previous ones.show settingscriticalCommandPrints the settings for a “receiving server and sending address” pair after all blocks have been merged.test configcriticalCommandParses the configuration without applying anything.pmtad –debugCommandStarts the engine in the foreground, printing messages to the screen instead of a file.Replace the configuration file over the networkAPI endpointWrites one or more configuration files to the node — without checking the contents and without reloading.Read the configuration file over the networkAPI endpointReturns the contents of a configuration file from /etc/pmta/ — the file itself or as a string inside JSON.List of configuration filesAPI endpointLists the node’s active configuration files: the main one, the included ones and the defaults file.Spool reading at startupMetricThe share of the spool read completed at startup, in percent.ConfigurationMonitor screenShows the main and included configuration files and lets you edit them; saving reloads the configuration by itself.The node's main configuration filecriticalFile/etc/pmta/config is a plain UTF-8 text file, read at startup and on a settings reload; it stores passwords and signing keys in plain text.Where the node writes why it did not startFileA separate file with the startup failure message — the first thing to read when the engine does not come up after installation or a configuration edit.The defaults fileFileThe second main configuration file: the defaults over which the main one is read.