Knowledge base
host-nameGlobalcriticalDirectiveThe first name is the main one; which one ends up in the greeting is decided by a five-step resolution.postmasterGlobalcriticalDirectiveOne of the two settings the engine does not work without: the watchdog sends crash and license expiration reports here, and mail to service addresses is forwarded here as well.smtp-source-hostGlobalcriticalDirectiveBinds outgoing connections to a local address or CIDR range and sets the name in the SMTP greeting.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.domain-macroGlobalset by the HubDirectiveDeclares a variable with a list of domains; after that its name with a dollar sign is substituted where the domains would otherwise have to be listed again.http-extra-headers<include-config>DirectiveNames a file whose lines the node will add as HTTP request headers when loading the configuration.include<virtual-mta>DirectiveThe same directive written inside a sending address — the included lines become its settings.include<domain>DirectiveThe same directive written inside a recipient block — the included lines become that recipient’s rules.include<source>DirectiveThe same directive written inside a source block — the included lines become its settings.include<smtp-pattern-list>DirectiveThe same directive written inside an SMTP response parsing list — the included lines become its rules.min-free-space<signals>DirectiveBelow this threshold the node starts deleting unsent export files; the default is 20 MB.volume-audit-api-keyGlobalDirectiveMandatory under a license that counts volume: with this key the node authenticates itself when sending data to the vendor. It is issued together with such a license.thread-reuseGlobalDirectiveTurning it off makes the engine discard threads immediately; this costs performance and removes a workaround for an old library bug. The default depends on the platform.thread-max-priorityGlobalDirectiveSets the fast end of the priority range the engine’s threads run with; a Unix-only directive, paired with the lowest one.thread-min-priorityGlobalDirectiveSets the slow end of the priority range the engine’s threads run with; a Unix-only directive, paired with the highest one.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 to turn a sending plan into hardwareMechanismTwo constants for sizing any node: about 2 KB of memory per queued recipient and spool space proportional to the total size of the messages.Cloud restrictionsMechanismClouds restrict outbound mail on port 25 until you ask them to lift the limit, and mailbox providers treat their address ranges with suspicion.The activation key is a prerequisite for installation, not a step after itMechanismWithout an activation key from SparkPost support the engine neither installs nor runs, and the license tier sets the outbound connection ceiling: on Standard everything above 200 is ignored.The watchdog that restarts the engineMechanismKeeps an eye on the engine and brings it back up after a crash by itself, sending a crash report to the postmaster address.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.What makes a virtual machine riskyMechanismRunning on a virtual machine is possible, but the manual does not recommend it without sufficient hardware and properly tuned hypervisor settings: under load the node may stop responding.A license for a fleet, not for a serverMechanismThe license is not bound to a server: it is installed on as many machines as the instance limit allows, and the nodes send volume statistics to the vendor every hour.The directive indexMechanismThe manual’s alphabetical index: 475 lines name 477 places where directives are documented — the only complete inventory of the configuration language.Who took the portMechanismTwo listeners do not fit on one port: if the port is already taken, the node will not come up, and the cause will be only in the log.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.Engine version rollback and configuration via the APIMechanismWhen PowerMTA is rolled back to a version without the configuration API, what was created through it becomes invisible but is not deleted; the manual’s table says what survives a rollback between versions with the API.Running in an imageMechanismExperimental running of the engine in a Linux container: the package, license and configuration are installed when building the image or attached at startup.National alphabetsMechanismConfiguration files are UTF-8, so internationalized domains and addresses are written as is; a message with an internationalized address in the envelope goes out only if the receiver supports SMTPUTF8.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.Installing on LinuxcriticalProcedureInstall the vendor’s package with the standard package manager, put the license key in place, check the configuration against the requirements and start the engine once — after that it comes up by itself.Prepare a machine for the enginecriticalProcedureFive requirements and a supported operating system must be in place before installation: a static address with a name, a reachable resolver, synchronized time, sized hardware and a license key.Node backup and restoreProcedureFive directories make up the node’s recoverable state; restoring means stopping the engine, putting the directories back and starting it again.Upgrading the engineProcedureBefore upgrading, make sure the license file holds a key valid for the new version and that the support term has not expired — and only then upgrade the package.Switching over to a standby nodeProcedureThe procedure for handing work to another machine: redirect submission, attach the failed node’s spool as a second one if possible, restart the standby, and do the reverse on return.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.Removing the engineProcedureRemoving the package with the standard package manager. The node’s state stays on disk.Deployment in the cloudProcedureInstalling in the cloud adds a few conditions of its own to the ordinary installation: choosing the machine type by estimate, a fixed address and a lifted restriction on the outgoing mail port.Contacting the vendorProcedureWhat to collect and where to turn when you could not sort it out on your own.Installing on WindowsProcedureInstallation with a wizard, with the same license and configuration requirements as on Linux.GlobalcriticalConfiguration blockLines that belong not to a queue but to the instance itself: ceilings, the spool, listeners, logging, the license and the web monitor.<spool>Configuration blockThe directory where the engine keeps message files while they wait for delivery; there can be several directories, each with its own priority and free space threshold.<include-config>Configuration blockThe same as include with an address, but lets you set request headers — for example, authorization.disable sourcecriticalCommandThere is an option to bring it back automatically after an interval — without it the address stays disabled forever.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.test configcriticalCommandParses the configuration without applying anything.enable sourceCommandReturns an address early — and this is the only way if no timer was set when it was disabled.show disabled sourcesCommandThe only window into the disabling mechanism: shows both manual disablings and those made by mailbox provider rules.show licenseCommandPrints the license details: product, version, platform, licensee, serial number, issue and expiry dates.show versionCommandPrints the version, the build date and the revision.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.Addresses present on the machineAPI endpointLists the addresses configured on the machine itself.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.LicenseMonitor screenShows the engine license and lets you add or replace it.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.License fileFileThe license key as a plain file — /etc/pmta/license on Linux, license.dat in the installation directory on Windows; on Windows ASCII is mandatory, not Unicode.The defaults fileFileThe second main configuration file: the defaults over which the main one is read.