Knowledge base
always-allow-relayingGlobalcriticalset by the HubDirectiveThe very reason a node sends mail at all — and the thing that makes it an open relay if granted to the wrong source.smtp-listenerGlobalcriticalset by the HubDirectiveIf no listener is declared, the node silently brings one up on 0.0.0.0:25.source<smtp-user>set by the HubDirectiveBinds the login to a named source block; its settings apply after login and override what the connection’s address would have given.source<smtp-listener>DirectiveBinds the listener to a named source block, canceling the usual address-based matching for its connections.accept-invalid-recipients<source>DirectiveSyntactically invalid addresses are accepted and immediately bounced instead of being rejected right in the submission session; they will not be delivered either way.allow-auth<source>DirectiveA switch for the very possibility of logging in: with no the engine neither advertises nor accepts AUTH, and there is no way to log in.allow-smtputf8<source>DirectiveAdvertises the SMTPUTF8 extension, allowing addresses beyond Latin script; sending is not guaranteed — the receiver may not support it.always-allow-api-submission<source>DirectiveOne line instead of listing the permissions required by submission through the vendor API; currently equivalent to the merge permission.await-slot<smtp-listener>DirectiveDecides for one listener whether to wait for a free slot or respond with a refusal; the node-wide line sets the same for all the others.disconnect-on-transient-error<source>DirectiveInstead of a 4xx response the engine drops the connection — for a submitting side that cannot handle temporary refusals.max-message-size<source>set by the HubDirectiveWithout the line the size is not limited at all — the engine’s default is “unlimited.”max-message-size<transmissions-api>DirectiveA limit on the payload size of a request to the submission API; the size multiplier is mandatory, and the engine will not accept a value above two gigabytes.max-rcpt-per-message<source>DirectiveA ceiling on acceptance: how many addresses the node agrees to take in one message from the submitting system.pickupGlobalDirectiveSets a pair of paths: where to read submitted files from and where to put the ones that could not be processed. Only one directory is supported.process-x-sp-subaccount-id<signals>DirectiveAllows the submitting side to assign a subaccount with a message header; the number from the header overrides the one set by the configuration.process-x-sp-subaccount-id<inline-seeding>DirectiveAllows taking the subaccount number from a message header; off by default.relay-addressGlobalset by the HubDirectiveThe address counterpart of accepting by domain: it accepts a specific address or a regular expression, not a whole domain; the line is repeated.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.relay-domainGlobalDirectiveLists domains for which the node accepts mail regardless of who submits it; the line is repeated, and it is needed only where the node handles inbound mail.smtp-await-slotGlobalDirectiveWhen there are no free inbound connection slots, the node either waits for one to free up or answers with a 421 greeting and closes the connection.source-group<source>DirectiveNames the group the source is assigned to; the limits shared by the group are set in the group block, not here.too-many-rcpts-fails-message<source>DirectiveInstead of refusing the extra recipients, the engine rejects the message at the DATA command; it works together with the recipient number limit.total-max-smtp-inGlobalset by the HubDirectiveLimits the number of simultaneous inbound SMTP connections for the whole node.allow-chunking<source>DirectiveAllows the submitting side to transfer a message with the BDAT command instead of DATA; the default is to allow.auto-qualify-domain<source>set by the HubDirectiveAn address of the form user@host arriving in MAIL FROM or RCPT TO is completed to a full one by adding a suffix; the default is to complete.domain-suffixGlobalDirectiveThe suffix appended to a single-part domain when completing addresses; it works only together with completion itself.max-message-hops<source>DirectiveLoop protection: the node does not accept a message that has passed through too many mail systems.smtp-command-timeout<source>DirectiveThe wait limit for data from the submitting side during the command exchange; the paired line to the body transfer limit.smtp-data-timeout<source>DirectiveThe wait limit for data from the submitting side after the DATA or BDAT command; applies only to incoming connections.total-max-transmissions-apiGlobalDirectiveHow many submitting HTTP connections the node serves at once; the engine does not check an upper bound — the operating system sets it.pickup-retry-intervalGlobaldeprecatedDirectiveThe directive is marked deprecated in the manual and not described: no purpose, no syntax, no default.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.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.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.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.Reserved merge variable namescriticalMechanismSome merge variable names are taken by the engine: you cannot give your own variables these names.What the submission bindings needMechanismWhat must be in place on the submitting side for the bindings to work: a library, permissions and group membership.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.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.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.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.How a message gets into the engineMechanismSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.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..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.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.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.<source>criticalConfiguration blockRules for whoever connects to submit: whether relaying is allowed, which control headers to honor, which limits apply and whether authentication is required.<smtp-listener>Configuration blockSettings that apply to connections on one address and port: encryption, rights through a named source, behavior when the ceiling is reached.<source-group>Configuration blockGathers sources into a group so that inbound connection limits apply to them together; members name the group on their side.Submitting a message over HTTPAPI endpointAccepts a message as a JSON request over HTTPS instead of an SMTP session — with recipients, substitutions and content.Latency on receptionMetricThe number of submissions and the time by reception stage.