Knowledge base
The telemetry contractcriticalMechanismOne block describes the accounting output in full: which record types, which fields, where they go, how files rotate and what gets anonymized.How the policy for a receiver is assembledcriticalMechanismSettings are assembled from the most general pattern to the most precise; the order of blocks in the file means nothing.A named proxy and three levels of its settingscriticalMechanismThe block carries the proxy address, the external sending address, the protocol version, the field type and the number of attempts; the first two lines are required.How the node responds to the receiving server's wordscriticalMechanismMatches SMTP replies against regular expressions and changes the queue mode on a match — the very trigger that all of the backoff mode machinery waits for.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.The sending address — what it is made ofcriticalMechanismA named set of everything that is a property of the address: which IP the message leaves from, how the node introduces itself, what it signs with and how fast it sends.A file, a program or an endpoint — and a file under each of the threecriticalMechanismThree ways to hand off accounting records; an endpoint still has a file underneath, which is deleted only after a successful send, and a non-2xx response triggers a retry.How an accounting record is structuredcriticalMechanismHow an accounting record is structured: the record type in the first column, then the fields, whose composition is configurable.Two attachment points — and two different behaviorscriticalMechanismA list attached to a source rejects the recipient at submission or bounces the message later; attached to a sending address or pool, it always accepts and then bounces.How the node decides whether to let an HTTP request incriticalMechanismTwo ways to identify yourself — an access level by address and a key; the key is stronger and works from any address.Backoff mode — the queue's second personalitycriticalMechanismA queue that a receiver has started refusing switches to a parallel set of limits, retries and routes — ten directives that act only in this mode.The bounce category in accounting — configurable, not vendor-fixedcriticalMechanismThe bounceCat string in every accounting record comes from a pattern list that can be extended with your own rules and your own category names.Parsing bounces that arrive as messagescriticalMechanismBounce reports that arrive as messages are parsed by a separate processor — and it runs before the complaint processor.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.How the node signs messages and chooses a keycriticalMechanismThe key is chosen by the sending domain from the headers, going through the declarations from top to bottom.How to name a queue in a commandcriticalMechanismHow to name a queue in a command argument: the same “receiving server and sending address” pair with asterisks added.Complaints parsed by the node — and they are parsed secondcriticalMechanismMail that arrives at an address from the configured list is parsed as a complaint report; the parsing order matters — the complaint processor runs after the bounce processor.Job headercriticalMechanismThe x-job header tags a message with a job; the node reads it only if the source is allowed process-x-job, and then the job is visible in accounting, the monitor and pause commands.Two tags the sender puts on a messagecriticalMechanismA job groups messages, an envelope identifier identifies one; the submitting side sets both, and only by them can you later select your mail in the node’s queue.What the node tells about itself and through which channelscriticalMechanismSeven observation surfaces: the web monitor, the console in four formats, the log, accounting, accounting search, metrics and export to external analytics.Different domains in one queue, because the gateway is the samecriticalMechanismDomains whose lowest-priority MX records match the list are combined into one queue and limited as a single receiver.External addresses on one machine, nodes insidecriticalMechanismNodes sit on internal addresses and go out through a proxy that holds all the external sending addresses.Do not send what will fail the check at the receivercriticalMechanismThe node checks the SPF of its own mail before sending: if it fails, it bounces the message without waiting for someone else’s refusal.A queue is a receiving server together with a sending addresscriticalMechanismThe engine groups messages by the “recipient domain plus sending address” pair: one domain from two addresses is two independent queues with their own counters, connections and mode.Four ways to say “slower”criticalMechanismMessages, data volume, connection rate and number of connections — each has its own limit, and each has a “per source address” variant and a backoff mode twin.Recipient eventscriticalMechanismThe last 50 delivery, bounce and deferral events per queue — enabled with track-recipient-events and visible in queue output.Who is allowed to submit mail and for whom to accept itcriticalMechanismOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.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.Reserved merge variable namescriticalMechanismSome merge variable names are taken by the engine: you cannot give your own variables these names.Reputation monitoring inside the nodecriticalMechanismThe engine itself watches the receiving servers’ replies and changes the queue mode on a pattern match — a reaction within the connection, not through telemetry.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.A name, an address and a greeting name — what a sending address consists ofcriticalMechanismThe definition is small, and two of its properties are easy to miss — omitting the address line silently inherits the node’s settings, and several addresses in one block rotate round-robin.The sender names the stream for each messagecriticalMechanismThe message carries the name of the stream it should be sent through — the choice is made by the submitting program, not by the node configuration.Six ways to choose a stream and the order among themcriticalMechanismA message’s stream is set by a merge variable, an API call, a header, a pattern rule, a listener and a source default — the manual lists them by precedence.Headers the sender uses to control deliverycriticalMechanismSix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.The stream is named by a header, if the source is allowed to do socriticalMechanismA message header names the stream; the source the message was submitted from must have permission to process the header, and the header is stripped before delivery.Address lists — named and unnamedMechanismA list of addresses, domains, patterns or hashes; a named one is attached by directives such as suppression, an unnamed one lives inside an inbound mail processor.A group of sending addresses with traffic sharesMechanismA named group of sending addresses; without shares messages are distributed in rotation, with shares in the given proportion, in steps of a tenth of a percent.What the submission bindings needMechanismWhat must be in place on the submitting side for the bindings to work: a library, permissions and group membership.Seeding campaigns with control addressesMechanismThe engine mixes the vendor’s addresses into a mailing, and the result is viewed in the vendor’s deliverability tool; independent of event export.Recipients deferred after a temporary refusalMechanismA recipient to whom the receiver responded with 4xx moves into a separate waiting area with a per-receiver interval; two commands can release it early.Two inbound report processors and what to do with themMechanismBounces by message and complaints are parsed by two identically structured blocks; each has its own address list and its own pair of decisions about the message’s fate.Warm-up built into the engineMechanismA warmed-up address hands the first N messages of the day for each receiver to its cold partner; the partner sends them itself and builds history.What the submitting system assembles before sendingMechanismAll five language bindings provide the same three objects — a connection to the node, a message and its recipients — assembled in a fixed order.A retry ladder of your ownMechanismretry-after and backoff-retry-after accept a list of intervals — up to 30 steps, and the last one applies until the bounce.The receiver declares an encryption requirement in its DNS zoneMechanismThe node looks at the recipient domain’s DANE records and, if STARTTLS is required, sends only over an encrypted channel with a certificate verified by fingerprint.The source default is the bottom rung, tied to whoever connectsMechanismA source block matching the sender’s address can name a default stream; it applies when no choice was made higher up the ladder.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.The node can insert pixels and rewrite links by itselfMechanismIn the vendor’s tracking mode the engine parses outgoing HTML, rewrites links to the tracking domain and inserts open pixels — with a choice of what to do if the markup cannot be parsed.Monitor response formatsMechanismThe web monitor serves pages to a person at the address with /ui, and XML or JSON to a program at the same address without the suffix.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.Markup parsing and editingMechanismOpen and click tracking in sparkpost mode edits the message markup with the built-in gumbo-parser; by default a message whose markup could not be parsed is bounced.Accounting sent by the node instead of accounting collected from the nodeMechanismAccounting records can be sent to HTTP endpoints in addition to files and the pipe — not instead of them.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.Hand a message to a webhook instead of a receiverMechanismThe queue sends the message as a POST request in the form of a JSON object; only a 2xx response counts as success.What to do with an accepted messageMechanismWhat the node does with an accepted inbound message: forwards it, writes it to a file, discards it, passes it to a program or parses it as a bounce or complaint.Submission logins, plain-text passwords and per-user settingsMechanismA sender logs in with one of three methods; each login is a configuration block with a plain-text password, and that login’s named source overrides what its address would have given.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.Personalization inside the engineMechanismVariables are set per recipient, and the node substitutes them at delivery — one submitted message goes to many recipients with different content.Exposing metrics to a collectorMechanismExposing the node’s metrics to an external collector in its format.The receiver declares an encryption requirement on its websiteMechanismThe node fetches the recipient domain’s policy over HTTPS and, if it is in enforce mode, delivers only when the MX matches, the connection is encrypted and the certificate is verified.The complaint format of one large receiverMechanismHotmail complaints do not come in standard ARF: for the engine to recognize them and record the recipient, you need the variant with an RFC attachment and the X-HmXmrOriginalRecipient header.Command output formatsMechanismNode commands can print not only text but structure too.The stream is chosen by matching the envelope or a headerMechanismA named rule list matches the return address, the recipient or a header against regular expressions and assigns a stream on the first match.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.Node metrics in a standard formatMechanismThe node exposes counters, gauges and summaries in a widely accepted format: traffic, connections, errors, queue depth and delays.CSV or JSON — chosen by the file extension, not by a directiveMechanismRecords are written as comma-separated values with a header line or as JSON objects, one per line; the choice is made by the extension in the path.The node needs a resolver that does all the work itselfMechanismThe engine requires recursive name resolution; a resolver that answers with a referral to another server forces the query to be repeated and triggers a log warning.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.Submission is a network service, and you can log into itMechanismThe submitting application connects to the node by name or address and port — either without login or with a name and password the node is configured to accept.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.Sending windows set in the message itselfMechanismA header carries one or more intervals during which the message may be sent; the schedule cancels the message’s lifetime, and the message bounces when the windows run out.A second signature on the same messageMechanismTwelve lines with the second- prefix: the message is signed twice, with different keys and under different identities.The node takes the stream whose address matches the connection addressMechanismThe source default accepts a reserved value instead of a stream name — then the node chooses the stream whose sending address matches the address the connection arrived at.The vendor's analytics — and what leaves the node for itMechanismA paid service that receives the node’s accounting data and returns analytics, a health score and a spam trap report; it is enabled by scope and stays off until its block exists.Three pool rules the manual states directlyMechanismRotation-based distribution, inheritance of settings by members with the member’s own values overriding, and a namespace shared with sending addresses.The merge variable is the top rung, and it lives in the contentMechanismA service merge variable names the stream for the message and overrides all other selection methods on its submission path.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.What protects the web monitor and what that protection is notMechanismThree different protections — an address list, encryption and advice not to expose the monitor to the internet; there is not a single account.Selecting a sending address by message contentMechanismRegular expressions are matched against a header, the return address or the recipient and select a sending address or assign a priority; lists can call each other.How a binding reports an errorMechanismThe C++ binding reports an error with an exception, after which the object is discarded; the C binding with a returned flag and a separate query for the last error.The encryption library is part of the distribution, not the systemMechanismOpenSSL comes inside the PowerMTA distribution, so the set of versions and ciphers is determined by the product version, not by system libraries.The directive indexMechanismThe manual’s alphabetical index: 475 lines name 477 places where directives are documented — the only complete inventory of the configuration language.The second complaint report formatMechanismXARF complaints are JSON instead of ARF: the engine fills the main fields itself, and the rest are extracted with the xarf.<path> form.What is not allowed in FIPS modeMechanismIn FIPS mode only a validated set of algorithms is available: some familiar encryption and signing settings become unavailable.The HTTP submission formatMechanismInstead of a finished message, an HTTP request can carry the sender, subject, headers, text, HTML, AMP and attachments as separate fields — the node assembles and encodes the message itself.The line ending requirementMechanismLines of a submitted message end with a CRLF pair; a lone LF is the most common error of a home-grown submitting program, and it is diagnosed with a session recording.The log and accounting — two files and two different questionsMechanismThe engine keeps a separate log and a separate accounting file; the separation is made for the sake of format, performance and the ability to hand over the log without disclosing data.Mail merge via SMTP extensionsMechanismMail merge over SMTP: XMRG instead of MAIL FROM, XDFN with variables before each recipient, and XPRT instead of DATA for each part.Numbered merge partsMechanismNumbered pieces of a message for multi-part merges: the first is implied, each number is used once.Reports the engine does not understand by itselfMechanismReceivers that send bounces and complaints in a non-standard form are parsed with custom patterns; the extracted fields go into accounting on a par with the usual ones.Authentication during deliveryMechanismThe node logs in on the receiver’s side with the login and password from the <domain> block — CRAM-MD5, LOGIN or PLAIN, if the receiver supports them.Which outcomes produce a report — each recipient decidesMechanismFor each recipient separately a report on success, failure, delay, any combination of them or nothing is requested; the default is failure only.Submitting a message by writing a file into a directoryMechanismThe message is placed as a file in a directory, and the envelope is passed in special headers at its start; the engine takes the file into the spool and delivers it.Keeping selected domains resolved at all timesMechanismA file with a list of domains whose DNS records are refreshed on their own schedule, independently of the queue and regardless of their own time to live.Two priorities, and which of them winsMechanismQueue priority decides which recipients get connections first; recipient priority reorders messages within one queue and cannot overtake a queue.Five ways for a queue to hand off a messageMechanismA queue does not have to use SMTP: it can write to a file, run a program, call over HTTP or discard.Merging domains into one queue by hand, by naming itMechanismThe same merging, but by your list rather than by MX match: you set the queue name.Spreading a stuck queue across several addressesMechanismRerouting not to one address but to a pool: messages are spread evenly across its members.What to return in a bounce reportMechanismWhat to enclose in a bounce report: the whole message or only its headers.The stream follows the address you connected toMechanismA named source block is attached to a listener and applies to everyone who connected to that address and port — so the sender picks the stream by picking the connection point.Encodings at submissionMechanismMessage data in a binding is added as 7-bit, 8-bit or base64: the first two do not change the data except for converting a lone LF to CRLF, base64 encodes on the fly; merge data supports only 7-bit and 8-bit.How a message gets into the engineMechanismSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.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.Submission over HTTPS on its own listener, modeled on SparkPostMechanismA separate entry point: its own listener with a certificate, its own keys and a reserved source name through which the usual submission settings apply to such mail.The load balancer header at the entranceMechanismThe node reads the PROXY header at the start of an incoming connection and treats the address from it as the source; this works for both kinds of entry point.Secrets in an external vaultMechanismSigning keys can be kept in HashiCorp Vault: the configuration keeps a path, and the engine fetches the key over HTTP and keeps it in memory without writing it to disk.A return address with the recipient written into itMechanismThe bounce arrives at a unique address, and there is no need to parse its content.A signing key that came along with the messageMechanismA private key is passed in a message header; the node signs with it and removes the header before sending.A message header with which the submitting side adjusts the signatureMechanismFive parameters in X-DKIM-Options: selector, domain, signing identity, query method and key list.Replacing a recipient with one or several othersMechanismA message that arrives at a declared address is forwarded to others; expansion happens after the stream is chosen but before the message is queued into it.A signature that preserves someone else's verification when forwardingMechanismThree headers in which the forwarder attests: the message came to me like this and with these verification results.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.A fake receiver inside the node itselfMechanismThe node listens on its own port and pretends to be someone else’s server: messages go nowhere, but the load is real.Handing a message to a program on the same nodeMechanismThe queue starts a program for each recipient and feeds the message to its input.The group that grants management rightsMechanismMembership in the pmta group gives an unprivileged user the right to call the node’s commands and use submission.Exposing metrics over SNMPMechanismThe node can expose its metrics over SNMP — a second way of monitoring besides the web monitor.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..NET submission APIMechanismThe .NET binding: the manual only names the folder with its description — api\dotnet in the installation directory on Windows — and requires .NET 2.0 or later.Object lifetime in the C bindingMechanismIn the C binding every object is allocated, initialized and freed explicitly — where in C++ a constructor and destructor do this.Authentication directive indexMechanismA summary of the directives related to login: they are scattered across several blocks.C submission APIMechanismThe C binding: the same operations as functions with the PmtaConn, PmtaMsg and PmtaRcpt prefixes, with explicit allocation and freeing of objects and a query for the last error.C++ submission APIMechanismThe C++ binding: connection, message and recipient classes in three header files; an error throws an exception and makes the object unusable.Date headerMechanismThe submission APIs can build a date header themselves for a message composed from scratch.How a message leaves the nodeMechanismAt the introduction level two paths are described: extended SMTP to the receiver or handing off to a local program; the receiver block adds three more.Java submission APIMechanismThe Java binding: pmta.jar in the classpath and a provider file for JavaMail; the description is in JavaDoc.Perl submission APIMechanismThe Perl binding: the CPAN package Port25-Submitter from /opt/pmta/api, built and installed the usual way; the description is in perldoc.Accept, route, deliverMechanismA message’s path inside the node: accept, decide where, deliver — and all the settings live between these three steps.